Skip to content

feat(O2/O3/P1-P4): 司機車輛資訊+接單 gate+乘客指定車種 - #30

Merged
thothawei merged 3 commits into
mainfrom
claude/o2-driver-vehicle-api
Jul 17, 2026
Merged

thothawei merged 3 commits into
mainfrom
claude/o2-driver-vehicle-api

Conversation

@thothawei

@thothawei thothawei commented Jul 17, 2026 •

Copy link
Copy Markdown
Owner

接續 O1(#29),實作 O2(車輛資訊 API) 與 O3(接單前置 gate)——O 章節的車輛地基。兩者同 PR 是因為 O2 的欄位若沒有 O3 把關,就只是一張沒人必須填的表單;分開合併會留下「填了也沒用」的中間狀態。

O2:GET/PUT /api/driver/vehicle

  • GET — 回 {vehicle_type, plate_number, has_vehicle};未設定時兩欄為空字串、has_vehicle=false(非錯誤)。
  • PUT — body {vehicle_type, plate_number};driver_id 一律取自 token,司機只能改自己的。

has_vehicle 附在回應裡,讓 App 不必自行判斷「兩欄皆非空」,與 O3 gate 用同一判準(model.Driver.HasVehicle())。

車牌格式拍板:寬鬆驗證

只檢查長度(2–10)與字元集(半形 A-Z/0-9/-,至少一個英數字),不綁樣式。台灣車牌多代並存(ABC-1234/1234-AB/AB-1234/電動車/機車格式),硬綁正則會誤擋真車牌;擋不住的髒值由 O3 gate 與人工審核(O5,若做)兜底。

NormalizePlateNumber(去空白+轉大寫)是唯一索引的前提——不正規化就存,同一台車會以「abc-1234」「ABC-1234」各佔一列,uq_drivers_plate_number(O1)形同虛設。

狀態碼

情況 回應
車種非白名單/車牌格式錯/任一為空 400
車牌已被其他司機使用 409
司機不存在 404

409 的關鍵是 repository.UpdateVehicle 把唯一索引衝突翻成 ErrPlateTaken——原樣往上丟會變 500,司機看到「伺服器錯誤」而無從修正。判斷用 pgconn.PgError 的 SQLSTATE 23505 +約束名,不比對錯誤訊息字串;jackc/pgx/v5 因此從 indirect 升為 direct 依賴。

O3:接單前置 gate(強制填寫,無寬限期)

兩道都在後端——只靠 App 端跳轉擋不住,API 可被直接呼叫:

  1. 派單過濾:dispatchRound 候選迴圈跳過未填車輛者(與既有「已派過/已拒接/非待命」同層)。
  2. 接單擋下:AcceptRide 回 ErrDriverNoVehicle。

handler 一行未改:statusForErr 對非 ErrForbidden 的錯誤一律回 409,API 自動就是 409;LINE webhook 既有的 err.Error() 回覆,會把「請先填寫車種與車牌才能接單」原樣送給司機。

gate 排在既有「非待命狀態」檢查之前:沒填車輛卻被告知「非待命狀態」,司機不會知道要去填車輛。

既有司機在 O1 migration 後兩欄皆為 '' → 一律無法接單直到填完。後端不需回填 migration,但上線前要通知司機(營運事項)。

驗收(實際跑過)

  • go build / go vet / gofmt 綠;internal/service 全套通過(781s,無 FAIL)。
  • O2:constants 單元測試(正規化、寬鬆驗證合法/非法各案,含全形字元不視為合法);handler 測試(無 token/customer token 皆 401;參數驗證 8 案皆 400);service 與 repository 真 PostGIS 整合測試(正規化後才寫入、驗證失敗不留半套資料、大小寫不同但同一車牌仍撞 ErrPlateTaken、同一司機沿用自己車牌換車種不算衝突)。
  • O3:真 PostGIS + Redis 整合測試——兩台同樣待命且都在附近,只有填了車輛的收到 ride.assigned;未填車輛接單回 ErrDriverNoVehicle 且訂單/司機狀態皆無副作用;有車司機隨後仍能接走該單(釘住 gate 早退時有正確釋放搶單鎖)。
  • 反向驗證:拿掉衝突翻譯 → 錯誤原樣為 SQLSTATE 23505;拿掉 NormalizePlateNumber → 正規化與車牌衝突兩案 FAIL;停用派單過濾 → 兩台都收到派單;停用接單 gate → AcceptRide 回 nil。四項皆確認對應測試會 FAIL。

未驗:docker compose 起全服務的 live E2E。

Reviewer 請注意

本次之前沒有任何測試走過 service.AcceptRide/Dispatch(既有測試一律用 repository.AcceptRide 直接改狀態)。所以「回歸全綠」不代表 gate 被既有測試考驗過——這兩條路徑的覆蓋完全來自本 PR 新增的測試。

下一步

車輛地基完成 → P1(rides 加 required_vehicle_type)。

🤖 Generated with Claude Code

thothawei and others added 2 commits July 17, 2026 09:23
車牌格式拍板:寬鬆驗證(長度 2-10+字元集 A-Z/0-9/-,不綁樣式)。
台灣車牌多代並存,硬綁正則會誤擋真車牌;髒值由 O3 gate 兜底。

- constants:NormalizePlateNumber(去空白+轉大寫)+ IsValidPlateNumber。
  正規化是 uq_drivers_plate_number(O1)的前提,否則同車以大小寫各佔一列。
- repository.UpdateVehicle:唯一索引衝突翻成 ErrPlateTaken(handler 回 409 而非 500),
  以 pgconn SQLSTATE 23505 + 約束名判斷,不比對錯誤訊息字串。
- service.SetVehicle:車種白名單+車牌驗證,驗證失敗不寫入。
- handler:回應帶 has_vehicle(與 O3 gate 同一條件),400/409/404 分流。

驗收:build/vet/gofmt 綠;constants 單元測試、handler 授權與參數驗證測試、
service+repository 真 PostGIS 整合測試全綠。反向驗證:拿掉衝突翻譯或
正規化,對應測試皆 FAIL。

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
兩道都在後端,以 model.Driver.HasVehicle() 為單一判準(與 O2 回應的
has_vehicle 同源)。只靠 App 端跳轉擋不住——API 可被直接呼叫。

- dispatchRound:候選司機迴圈跳過未填車輛者(與既有「已派過/已拒接/
  非待命」同層)。
- AcceptRide:回 ErrDriverNoVehicle。handler 無需改動——statusForErr 對非
  ErrForbidden 一律 409;LINE webhook 既有的 err.Error() 回覆會把
  「請先填寫車種與車牌才能接單」原樣送給司機。
- gate 排在「非待命狀態」檢查之前:沒填車輛卻被告知「非待命狀態」,
  司機不會知道要去填車輛。

驗收:build/vet/gofmt 綠;service 全套通過(781s)。新增真 PostGIS+Redis
整合測試:未填車輛者不進派單候選、接單回 ErrDriverNoVehicle 且無副作用、
有車司機隨後仍能接走該單(釘住 gate 早退時有釋放搶單鎖)。反向驗證:
停用派單過濾 → 兩台都收到派單;停用接單 gate → AcceptRide 回 nil,皆 FAIL。

註:本次之前沒有任何測試走過 service.AcceptRide/Dispatch(既有測試都用
repository.AcceptRide 直接改狀態),這兩條路徑的覆蓋來自本次新增的測試。

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
@thothawei thothawei changed the title feat(O2): 司機車輛資訊 API(GET/PUT /api/driver/vehicle) feat(O2+O3): 司機車輛資訊 API + 接單前置 gate Jul 17, 2026
P1 migration 000018:rides 加 required_vehicle_type + CHECK。沿用 O1 慣例
TEXT NOT NULL DEFAULT '',不用 NULL——否則「未指定」有 NULL 與 '' 兩種表示法,
每個過濾條件都要處理兩者,遲早漏一條。

P2 建單 API 帶車種:handler → CustomerCreateRequest → CreateByCustomer →
RideRepository.Create 的 raw INSERT(兩條分支都要補;raw SQL 不是 GORM 自動
映射,漏帶會靜靜存成 '',回傳的 struct 卻是對的)。非白名單在 service 擋成
400,不讓它撞 DB CHECK 變 500。

P3 派單過濾:指定車種時只派同車種,排在 O3 的 HasVehicle gate 之後。

P4 取消原因明確化:giveUpCancelInfo() 同時產生「機器可讀原因/乘客文案/WS
payload」,三者同源不漂移。指定車種找不到 → cancel_reason=no_vehicle_of_type
+ required_vehicle_type +「附近暫無寵物用車」;未指定 → no_driver_available
且不帶車種鍵(帶了 App 會誤以為乘客指定過)。
註:目前只有逾時取消這條路徑帶 cancel_reason,App 端須容忍缺席。

順帶修:O1 的可逆性測試用 Steps(-1),隱含「O1 是最後一個 migration」。P1 一加
就變成驗 P1 的 down,O1 反而失去覆蓋。改為版本導向(Migrate(17) 再 Steps(-1))。

驗收:build/vet/gofmt 綠;repository 568s、service 967s、handler 51s、constants
全套通過。反向驗證 6 項皆確認對應測試 FAIL:CHECK、O1 測試修正、P2 無目的地分支
漏帶值、P3 過濾、P4 車種分支。

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
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