Skip to content

feat(S): 乘客評分司機(B5)——ride_ratings + 評分端點 + 三處讀回 - #45

Merged
thothawei merged 1 commit into
mainfrom
claude/b5-ride-rating
Jul 27, 2026
Merged

thothawei merged 1 commit into
mainfrom
claude/b5-ride-rating

Conversation

@thothawei

Copy link
Copy Markdown
Owner

為什麼是這個任務

App 完成卡的「留下評分(即將開放)」從 2026-07-08 佔位至今,註記「真實 API 待 Phase C」——
那是全 App 最後一個還印著「即將開放」的出貨畫面。後端當時確實沒有評分資料表與端點
(grep -i rating 全 repo 零命中)。對應 docs/backend-api-gaps.md P4 #16。

付款(P4 #19)仍待真金流,不在本批。

改了什麼

migration 000023 ride_ratings

  • 一趟一評、不可重評(唯一索引 uq_ride_ratings_ride_id):分數送出即定論。
    允許改分會讓司機平均分變成可被事後情緒左右的浮動值,也讓「評過沒」失去明確答案
    (App 完成卡要據此決定顯示星星還是評分按鈕)。
  • customer_id/driver_id 是寫入當下的快照,不靠 rides 反查——評分屬於
    「這位乘客給這位司機」的事實,行程資料日後若調整不該改寫歷史評分。
  • CHECK:score BETWEEN 1 AND 5、char_length(comment) <= 500
    (服務層另有 200 字上限;DB 這層是直打 SQL 也擋得住的最後防線,比照 lost_item_requests)。

POST /api/customer/rides/:id/rating(customer JWT)

驗證順序刻意是「輸入 → 歸屬 → 狀態 → 重複」:先擋不必查 DB 的輸入錯誤,
再依序回答「這趟是不是你的」「完成了沒」「你評過了沒」。

情況 狀態碼 理由
星等越界/評論過長 400 輸入格式錯
非本人的訂單 403 訂單存在,只是不是你的
訂單不存在 404
已評過/行程未完成 409 狀態衝突不是輸入錯,App 據此知道不必請乘客改參數重送

沒司機的行程(派單前取消)沒有評分對象,與「未完成」同走 ErrRideNotCompleted。

讀回三處(沒有讀回,App 無從知道評過沒)

  • CustomerRideView.rating — 只在 status=completed 時才查。這條路徑也服務乘客端的
    active 輪詢,對永遠不可能有評分的進行中訂單每幾秒打一次 ride_ratings 是純浪費。
  • CustomerRideRow.rating_score(歷史列表 LEFT JOIN)— 完成卡關掉後唯一的補評路徑。
  • GET /driver/me 的 rating_avg/rating_count — 查失敗不擋 /me
    (加值資訊,不該讓司機因此載不出首頁);新司機無評分回 (0, 0) 而非錯誤。

三處注入都是可選的 SetRating/SetRatings,未注入時既有回應形狀一個欄位不少。

驗收

  • go build ./.../go vet ./.../gofmt -l 全乾淨。
  • internal/service/rating_test.go 3 案(主流程+四道守門與 trim/平均分含無評分 (0,0)/
    訂單視圖與歷史列表讀回)——真 PostGIS 跑全部 migration,順帶驗證 000023 本身可套用。
  • internal/handler/rating_test.go 2 案(401/403/壞 id 400/壞 JSON 400/
    星等越界含「缺 score 等同 0 也擋」/未啟用 503)。
  • internal/handler/route_shape_test.go:POST /customer/rides/estimate(靜態)與
    /customer/rides/:id/rating(參數)同層並存——gin 舊版對此會在註冊當下 panic,
    那是啟動即死、單元測試照樣全綠、一路到部署才發現的失敗模式。gin 1.12 實測四條路徑都解析正確。
  • 既有 ride_history_customer_integration_test(涵蓋改過的 ListRecentByCustomer)
    與 handler 的 Driver|Me|Profile|Vehicle 測試皆綠。

註:本機跑 go test ./internal/service/ 或 -timeout 60s ./internal/handler/ 會逾時,
這是既有現象(已用 git stash 在乾淨狀態下重現確認):本機有 Docker 會真的起
testcontainers,CI 不啟 Docker 所以那些測試秒跳過。CI 的實際指令集全綠。

未做(誠實揭露)

沒有 docker compose live E2E——本批只有單元/整合測試。App 端 PR 已把
「B5 評分的模擬器實跑 E2E」列為下次任務最優先(含重複評分撞 409 這條只有直打 API 才遇得到的路徑)。

App 端對應:thothawei/fleet-app#45

🤖 Generated with Claude Code

App 完成卡的「留下評分(即將開放)」從 2026-07-08 佔位至今,註記「真實 API 待
Phase C」。後端當時確實沒有評分資料表與端點(grep -i rating 全 repo 零命中),
本批補齊。對應 backend-api-gaps.md P4 #16。付款(#19)仍待真金流,不在本批。

- migration 000023 ride_ratings:一趟一評、不可重評(唯一索引 uq_ride_ratings_ride_id)。
  允許改分會讓司機平均分變成可被事後情緒左右的浮動值,也讓「評過沒」失去明確答案。
  customer_id/driver_id 是寫入當下的快照,不靠 rides 反查——行程資料日後若調整
  不該改寫歷史評分。CHECK:score 1–5、comment ≤ 500 字(服務層另有 200 字上限)。
- POST /api/customer/rides/:id/rating(customer JWT):驗證順序「輸入 → 歸屬 →
  狀態 → 重複」。非本人 403(訂單存在,只是不是你的)、不存在 404、
  已評過/未完成 409(狀態衝突不是輸入格式錯,App 據此知道不必改參數重送)。
- 讀回三處(沒有讀回,App 無從知道評過沒):
  · CustomerRideView.rating——只在 status=completed 時才查,這條路徑也服務乘客端的
    active 輪詢,對永遠不可能有評分的進行中訂單每幾秒打一次 ride_ratings 是純浪費。
  · CustomerRideRow.rating_score(歷史列表 LEFT JOIN)——完成卡關掉後唯一的補評路徑。
  · GET /driver/me 的 rating_avg/rating_count,查失敗不擋 /me(加值資訊,不該讓
    司機因此載不出首頁);新司機無評分回 (0,0) 而非錯誤。
- 三處注入都是可選的 SetRating/SetRatings,未注入時既有回應形狀一個欄位不少。

驗收:go build/go vet/gofmt 乾淨。
- internal/service/rating_test.go 3 案(主流程+四道守門與 trim/平均分含無評分 (0,0)/
  訂單視圖與歷史列表讀回),真 PostGIS 跑全部 migration,順帶驗證 000023 可套用。
- internal/handler/rating_test.go 2 案(401/403/壞 id 400/壞 JSON 400/星等越界
  含缺 score 等同 0 也擋/未啟用 503)。
- internal/handler/route_shape_test.go:POST /customer/rides/estimate(靜態)與
  /customer/rides/:id/rating(參數)同層並存——gin 舊版對此在註冊當下 panic,
  是啟動即死、單元測試照樣全綠的失敗模式。gin 1.12 實測四條路徑都解析正確。
- 既有 ride_history_customer_integration_test(涵蓋改過的 ListRecentByCustomer)
  與 handler 的 Driver/Me/Profile/Vehicle 測試皆綠。

App 端對應:fleet-app PR #45。

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
@thothawei
thothawei merged commit dcd0379 into main Jul 27, 2026
1 check passed
@thothawei
thothawei deleted the claude/b5-ride-rating branch July 27, 2026 11:43
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant