Skip to content

Latest commit

 

History

History
1474 lines (1230 loc) · 118 KB

TODO.md

File metadata and controls

1474 lines (1230 loc) · 118 KB

line-fleet-dispatch — 補強清單(後端)

建立:2026-07-11。以程式碼實測為準。 本檔專收「後端待辦」;總體階段規劃見 roadmap.md、API 缺口見 backend-api-gaps.md。 每完成一項:實跑驗收 → 勾選回填 → 走 PR(main 受保護,enforce_admins: true,不可直推)。


F. 手續費/會費/營運報表(2026-07-11 規劃)

需求:後台可設「手續費%數」,並在報表顯示司機營業狀況(營業額)、應付總公司金額, 以及車隊會費的計算與收取。跨三專案,本區塊為後端地基,admin/app 依賴這裡。

前置事實(2026-07-11 盤點):目前 rides 表沒有任何金額欄位,只有實際里程 distance_m(tracking.go:228 完成時由 TrackDistanceM() 以 GPS 軌跡連線計算, = 行程實際里程,可直接拿來計費)。日報表 DailyDriverStats(repository.go:445) 只統計趟數/里程/平均接客秒數,完全沒有錢。所以整條「營業額→手續費→付總公司」 都要從零建。roadmap.md「資料模型新增彙總」已預留 fares/fare_rules(C1)、 payments(C3),本區塊將其具體化。

已定案設計決策

決策 結論 理由
車資來源 距離自動計費:起步價 + 每公里費率 × (distance_m/1000) 已有實際里程
收費模式 手續費 + 會費並存 每趟抽成 + 每月固定會費,兩筆都算「應付總公司」
會費週期 月費(固定金額) 每位司機每月一筆
費率快照 車資、手續費在完成當下算好寫進該筆 ride,不從當前設定回推 費率日後會調,歷史報表必須用當時費率
金額單位 全系統統一整數(建議存「分」,顯示除 100) 避免浮點誤差
權限 費率/會費設定僅 superadmin 可改(沿用既有 RBAC) 金額設定屬敏感操作

施作項目(嚴格相依,由上而下)

實作進度(2026-07-11):F1–F7、F9-1、F9-2 已完成並過測試(build/vet 綠、 費率單元測試 6 案、testcontainers 整合測試 TestBillingReports/TestCompleteRideSnapshotsFare 對真 Postgres 跑全 migration 通過)。命名實作採 *_cents(金額存分)、commission_bps (手續費存基點,避免浮點)。F3 的 OSRM 里程退路已於 2026-07-12 補上(見下)。

  • F1. 費率設定表 fleet_settings(migration 000011)✅ 單列表(id 固定 1),欄位 base_fare_cents/per_km_fare_cents/min_fare_cents/ commission_bps(1500=15%)/monthly_membership_fee_cents/updated_by/updated_at, 含非負與 bps≤10000 的 CHECK,seed 一列預設。model:model.FleetSettings。

  • F2. rides 加計費欄位(migration 000012)✅ fare_amount_cents/commission_amount_cents/driver_net_amount_cents(BIGINT,nullable, 完成時定格)。model.Ride 已加對應 *int64 欄位 + snake_case json tag。

  • F3. 完成時計算車資(internal/service/tracking.go 的 Complete)✅ 里程 → FeeSettings.Quote()(internal/service/fee_settings.go,全整數運算)→ 定格寫進 ride;同時把 fare_amount_cents 塞進乘客 ride.completed 事件(為 E2 鋪路)。 只有 COMPLETED 計費。 OSRM 里程退路(2026-07-12)✅:TrackingService 注入 OSRM client(SetOSRM), 完成時計費里程=max(GPS 軌跡里程, OSRM pickup→dropoff 路線里程)(billableDistanceM)—— 軌跡真的長於路線=司機繞路照實計;軌跡 0/稀疏偏低則用路線里程補回。存進 distance_m 讓報表與車資一致。 需有 dropoff 座標才觸發退路(LINE 建的無目的地訂單維持軌跡里程)。OSRM 不可用時 client 內建 haversine×1.4 退路。 驗收:單元測試 TestBillableDistanceM(8 案 max 邏輯)+ docker E2E(稀疏軌跡 track_m=0 → route_m=6263 → fare 21026 分=NT$210.26,非 min_fare 8500)。

  • F4. 費率設定 API(superadmin)✅ GET/PUT /api/admin/settings/fees(AdminHandler.GetFeeSettings/PutFeeSettings), 掛在 superadmin 路由。費率採 DB 持久化 + 記憶體快取(刻意不同於 DispatchSettings 的 env-記憶體式),重啟不還原、避免算錯帳。

  • F5. 日報表金額擴充(ReportRepository.DailyDriverStats)✅ 加 total_revenue_cents/total_commission_cents/driver_net_cents; 同時修掉大資料量兩坑(見 F9-1/F9-2)。

  • F6. 月營運報表 API(新端點)✅ GET /api/admin/reports/monthly?month=YYYY-MM(viewer 唯讀):每司機趟數/營業額/手續費/ 司機實得(repo 聚合),handler 補月會費與 應付總公司=手續費+月會費(當月有完成行程者計會費)。

  • F7. 司機收入 API(app 司機端用)✅ GET /api/driver/earnings?month=YYYY-MM(driver JWT,DriverHandler.Earnings): 回傳趟數/營業額/手續費/實得/本月會費/應付總公司;無趟數則不收會費。

  • F8. 會費落帳 membership_invoices ✅(migration 000013) 表:driver_id、period(YYYY-MM)、amount_cents(產生時定格快照)、 status(unpaid/paid)、paid_at。MembershipInvoiceRepository: GenerateForMonth(對當月有完成行程的司機各開一張,ON CONFLICT DO NOTHING 冪等)、 List(period,status)、SetPaid。API:POST /api/admin/membership-invoices/generate 與 PATCH /api/admin/membership-invoices/:id(superadmin)、GET /api/admin/membership-invoices(viewer)。 語意:只對「當月有完成行程」的司機開帳單,與 F6/F7「無跑車不收會費」一致;金額為產生當下快照, 日後改月會費不影響歷史帳單。 單一真源(2026-07-13 修正):F6 月報表與 F7 司機收入原本用「即時費率」算會費,與已落帳 invoice 是兩個視角—— 調費率會追溯竄改已結清月份、對從未產生帳單的月份也照收、且無視繳款。已改為 F6/F7 的會費/應付總公司 一律 LEFT JOIN membership_invoices 讀帳本快照(repository.go MonthlyDriverStats/DriverMonthlyEarnings), 未產生帳單者會費為 0(尚未入帳=尚未應付)。與車資/手續費的快照心智模型一致,三端(F6=F7=帳本)恆等、不受費率調整影響。

大資料量預防措施(DB scale,2026-07-11 納入)

報表是全表聚合(SUM/GROUP BY over rides),是最先被資料量拖垮的地方。 前置盤點:rides 目前只有 idx_rides_status 與 pickup GiST 索引,無 completed_at 索引; 現行日報表用 WHERE r.completed_at::date = ?::date(函式轉型 → 索引失效、全表掃); 投影 TotalDistanceM int(repository.go:441)在大量加總下會溢位。這些在建計費/報表時一併修。

  • F9-1. sargable 範圍查詢 + 複合索引 ✅ 日/月/司機收入查詢都改半開區間(completed_at >= start AND < end,移除 ::date 轉型); migration 000012 建 idx_rides_status_completed(status, completed_at)與 idx_rides_driver_completed(driver_id, completed_at)。 > 待補:以造數腳本灌 50~100 萬筆做 EXPLAIN ANALYZE,確認實走索引範圍掃描(見驗收)。

  • F9-2. 加總型別防溢位 ✅ 報表金額加總與里程加總一律 ::bigint/Go int64; 金額欄位本身 BIGINT(存分)。DailyDriverReport.TotalDistanceM 由 int 改 int64。

  • F9-3. 預聚合彙總表 daily_driver_earnings ✅(2026-07-13) 表(migration 000014):driver_id, day, trip_count, revenue_cents, commission_cents, net_cents, PK (driver_id, day) + day 索引;day 以 Asia/Taipei 日界(與報表月界一致)。 重算式 rollup(非 +1 增量):ReportRepository.RollupRideDay(rideID) 於完成時 INSERT…SELECT…GROUP BY…ON CONFLICT DO UPDATE 覆寫該 (司機,日) 桶——冪等、永遠等於 rides 即時聚合、 可安全重跑/自我修復;TrackingService.Complete best-effort 呼叫(失敗不擋完成,rides 為真源)。 月報表(F6)/司機收入(F7)改讀彙總表(每司機 ≤31 列),不再即時 GROUP BY 全表 rides; 日報表維持 live(含 distance/pickup,單日有界)。migration 回填既有已完成行程。 驗收:整合測試 TestBillingReports(讀彙總 + rollup + 冪等)通過;docker E2E——回填 3 司機值正確、 月報表(彙總)==live GROUP BY rides 逐欄相同、完成新行程觸發 rollup 新增當日桶、F6==F7 跨日加總正確。

  • F9-4. 查詢範圍上限 + 逾時保護 ✅(2026-07-13) 查詢跨度上限:parseRideListFilter 對 from~to 自訂區間加 rideListMaxRangeDays=31(含頭尾)上限, 超過回 400 查詢區間不可超過 31 天(日/月報表本就單日/單月有界,不受此限)。 逾時保護:config 加 DB_STATEMENT_TIMEOUT_MS(預設 10000),DSN() 附 statement_timeout runtime 參數 (pgx 於每條連線建立時套用;migrations 走 MigrateDSN 不受影響),啟動時 SHOW statement_timeout 記 log 確認。 驗收:單元測試(parseRideListFilter 區間上限/邊界、config DSN 含/不含 timeout、MigrateDSN 不受影響); docker E2E:啟動 log statement_timeout=10s;?from=2026-06-01&to=2026-08-01→400、剛好 31 天→200。

  • F9-5. 分頁與有界回傳 ✅(2026-07-13) 訂單列表 GET /api/admin/rides 伺服器端分頁(offset/日期/q/total,dispatch#2)。 禁無上限回傳通盤檢查:所有「逐筆」列表查詢加共用硬上限 MaxListRows=5000 (DriverRepository.ListAll/ListIdle、AdminRepository.ListAll、MembershipInvoiceRepository.List、 DeviceTokenRepository.ListBySubject、RideEventRepository.ListByRideID),任何清單不再無上限回傳。 報表 API 只回聚合列(每司機一列,隨 drivers 上限間接有界);track 回單一 LineString(受行程長度自然有界)。 後續(量體上升後):drivers/membership 逼近 MaxListRows 時改真 offset/keyset 分頁(比照 rides,含前端)。

  • F9-6. 會費表防重複入帳 ✅(隨 F8 migration 000013) membership_invoices 加 UNIQUE(driver_id, period)(uq_membership_driver_period)+ (period, status) 索引;GenerateForMonth 以 ON CONFLICT DO NOTHING 保證月結重跑不重複帳。 整合測試 TestMembershipInvoices 已驗冪等與金額快照。

  • F9-7.(Phase 2)rides 月分割 量體達千萬級時,rides 依 completed_at 做 PostgreSQL declarative partitioning (按月),冷月資料可歸檔;先留規劃,勿過早最佳化。

驗收方式(後端)

  • migration up/down 可逆;fleet_settings seed 一筆。
  • 大資料量:以造數腳本灌入 50萬100萬筆已完成 rides,EXPLAIN ANALYZE 確認日/月報表 走 idx_rides_completed 範圍掃描(非 Seq Scan),且回應時間在可接受範圍; 驗證加總不溢位(金額與預期一致)。
  • 單元/整合測試:給定里程 + 設定,CompleteRide 後 ride 的 fare_amount/commission_amount 數值正確;distance_m == 0 走退路;改費率後舊 ride 金額不變(驗證快照制)。
  • 報表 API:以 docker 起後端造 2~3 筆已完成行程,reports/daily 與 reports/monthly 的營業額/手續費/應付總公司加總正確。

跨端對帳 ✅(2026-07-11,docker 後端 + admin 真瀏覽器):造司機#2 一筆完成行程(min_fare 樓地板 8500), GET /api/driver/earnings(F7)與 GET /api/admin/reports/monthly(F6)對該司機逐欄相同—— 趟數 1、營業額 8500、手續費 1275、實得 7225、月會費 300000、應付總公司 301275(分); 日報表(F5)金額欄亦一致。快照制:透過 admin 費率頁把每公里 2000→2500 再改回, 既有 ride #5 金額保持凍結 8500 未受影響。admin UI(G2/G3)逐欄渲染相同 → 三端金額對齊。

風險與待拍板細項

  1. 里程準確度:計費綁 GPS 軌跡里程,軌跡稀疏會少算——已補 OSRM pickup→dropoff 路線里程退路(F3,2026-07-12), 計費里程取軌跡與路線大者;min_fare 仍是最後地板。是否再加「後台可手動校正單筆車資」待定。
  2. 費率調整時機:快照制 → 改費率只影響之後的行程,歷史不變(刻意)。
  3. 會費落帳:F6 先即時算,不管已繳/未繳;要狀態管理再開 F8。
  4. 取消行程不計費:只有 COMPLETED 計車資與手續費。
  5. 大資料量:報表聚合是最先被拖垮處,預防措施見上「大資料量預防措施(DB scale)」 F9-1~F9-7;daily_driver_earnings 彙總表與 rides 月分割屬「量體上升後」啟用,勿過早最佳化。

H. 對話與遺失物協尋(2026-07-13 實作)

需求:會員(乘客)與司機即時對話(WebSocket 推播,非留言板);乘客弄丟東西可對 已完成行程建協尋單聯絡司機,並支付「找回處理費」——費用=該趟車資 × 處理費%, % 由後台費率設定頁調整(lost_item_fee_bps),金額於建單當下快照(同車資快照制)。

  • H1. 行程內對話(migration 000015 ride_messages) ChatService:訊息持久化後經 WS Hub 即時推 chat.message 給行程雙方; GET/POST /api/rides/:id/messages(MultiAuth——本趟乘客/司機可發話、admin 唯讀稽核; after 參數供斷線重連補漏)。長度限制 500 rune(DB CHECK ≤1000 為最後防線)。
  • H2. 遺失物協尋(migration 000016 lost_item_requests + fleet_settings.lost_item_fee_bps) LostItemService:乘客對已完成行程建單(fee_cents = round(車資 × bps / 10000) 快照); 狀態機 open→found(司機尋獲)→paid(乘客付處理費,記帳式)→returned(歸還結案), open/found 可 closed(未尋獲/取消);守門式 UPDATE 防競態;部分唯一索引 uq_lost_item_ride_active 擋同行程重複未結案單(結案後可再開)。 lost_item.created/lost_item.updated 即時推播行程雙方。
  • H3. 處理費%設定:GET/PUT /api/admin/settings/fees 帶 lost_item_fee_bps (superadmin;預設 1000=10%,0~10000 驗證)。
  • 驗收:整合測試 TestChatSendAndList、TestLostItemFlow(testcontainers 真 Postgres); live E2E 30/30 ✅(2026-07-13,docker db/redis + 本機 server + gorilla/websocket 雙連線): 完整行程中乘客↔司機互傳訊息,對方 WS 於微秒級收到 chat.message(非輪詢); 歷史 2 則、after 增量補讀 1 則;路人發話/讀史/查協尋皆 403; 協尋單 fee=車資×10% 快照、admin 調成 20% 後既有單凍結、新單吃新費率; 重複建單 409、open 付款 409、paid 後 close 409;found→paid(帶 paid_at)→returned 全鏈路; 司機工作清單即時反映。驗畢費率還原、環境清除。 另注意:本機 go test ./... 因 service 套件整合測試逾 10 分鐘,需 -timeout 30m (CI 只跑非 Docker 白名單,不受影響)。
  • Phase 2(部分完成):付款目前為記帳式確認(無金流);聊天訊息的推播通知(FCM,App 被殺時)仍未做。
  • H4. admin 協尋單總覽 API(2026-07-15):GET /api/admin/lost-items?status=(viewer 唯讀, 掛 admin read 群組)——LostItemRepository.ListAll JOIN 司機/乘客姓名、status 白名單驗證(非法 400)、 新的在前、LIMIT MaxListRows。比照 membership-invoices 的 setter 注入。 驗收:整合測試 TestLostItemAdminList(JOIN 姓名/篩選/排序)+ handler 測試(400/503/空庫 200 空陣列); docker E2E——smoke_test 造完成行程→互傳訊息→建協尋單(fee 快照 850)→標記尋獲→admin 總覽含姓名/狀態/快照、 status=found 有 open 空、非法 status 400、未帶 token 401、admin 讀 /rides/:id/messages 稽核 OK。 前端頁面:fleet-frontEnd#11(/lost-items 總覽頁+訂單詳情對話稽核卡)。

💰 M. 金額改用整數台幣(無小數)— ✅ 已實作(2026-07-15)

使用者回報(2026-07-15):台幣沒有小數點,支付無法用小數。曾出現 NT$21.03、NT$17.96 這種不可支付金額。 已定案並實作:採 A 模型(維持存「分」但金額一律落在整數元,分為 100 的倍數);手續費無條件捨去、 車資與遺失物處理費四捨五入。 三端全鏈路已改(後端計算+前端顯示),詳見下方「實作結果」。

問題根源(現況):

  • fee_settings.go Quote():fare = max(min_fare, base + roundDiv(per_km × 公尺/1000))、 commission = roundDiv(fare × bps/10000)——roundDiv 只四捨五入到「分」,fare × 15%、 fare × 里程 都會落在非整數元(例:2103 分=NT$21.03)。
  • 遺失物處理費 lost_item.go:fee_cents = round(車資 × lost_item_fee_bps/10000),同樣產生 NT$17.96 這種。
  • 顯示層:admin src/utils/money.ts、app lib/core/util/money.dart 都做「分→NT$XX.XX(兩位小數)」。

已定案的決策(2026-07-15,使用者拍板):

  1. 金額模型 → A:維持存「分」但所有計算/收費/顯示一律落在整數元(金額恆為 100 的倍數,schema 不動)。
  2. 進位規則:手續費無條件捨去(利司機)、車資與遺失物處理費四捨五入。
  3. 快照一致性:費率快照制已保護歷史;改規則只影響日後新行程/新帳單,未回算歷史(沿用既有心智模型)。

影響範圍(三端全鏈路):

  • 後端(dispatch):fee_settings.go Quote()/roundDiv、tracking.go 完成計費、lost_item.go 處理費、 會費金額、報表聚合(daily/monthly、daily_driver_earnings)、司機收入 API(值本身要是整數元)。 費率設定的輸入單位也要想清楚(目前存 *_cents;若改整數元要一併調 API/migration/驗證)。
  • 後台(admin):src/utils/money.ts 顯示與 CSV、費率設定頁輸入(元/%)、日/月報表、會費帳單、協尋處理費顯示。
  • App:lib/core/util/money.dart 顯示、司機收入頁、乘客完成卡車資、遺失物處理費與支付金額。

實作結果(2026-07-15):

  • 後端:fee_settings.go 加 roundNtd(四捨五入到整數元)、floorNtd(捨去到整數元);Quote() 改 fare = max(min_fare, roundNtd(base + round(per_km × 公尺/1000)))、commission = floorNtd(fare × bps/10000)、 driver_net = fare − commission。lost_item.go 處理費 FeeCents = roundNtd(車資 × bps/10000)。 三金額皆為 100 的倍數。單元測試 TestQuote 加「三值皆整數元」斷言+車資四捨五入案(1348m→NT$112); 整合測試 TestBillingReports/TestCompleteRideSnapshotsFare/TestLostItemFlow fixture 改整數元、皆綠。 會費(固定設定值)與報表(加總已定格的整數元)本就整數,無需改。
  • 前端:admin money.ts、app money.dart 顯示改整數元、不帶小數點(防禦性四捨五入);admin 費率頁金額欄位 precision=0(%欄位維持 2 位)。相關測試斷言全部改整數元。admin 102 tests、app 73 tests 綠。
  • 待做(未涵蓋):真金流付款目前仍是記帳式確認(無金流),金額已是整數元、可直接收;若日後接金流沿用即可。

對應前端:line-fleet-admin/docs/TODO.md、line-fleet-app/docs/TODO.md。


🧍‍♂️🧍‍♀️ N. 多乘客/多停靠點行程(2026-07-16 規劃,未實作)

需求(使用者 2026-07-16):乘客端可在一張訂單裡安排多位客人各自的上車/下車點, 中途可設中斷點(停靠點),最多 5 位;司機端要同步收到「客人 A/B/C/D 分別在哪上車、 哪下車、最終目的地在哪」,並依最終目的地計算車資。

這不是陌生人拼車(carpool)配對,而是同一張訂單、同行的多位乘客、依序停靠 (車隊包車情境)。不需要配對演算法、不需要跨訂單分帳。

前置事實(2026-07-16 盤點):rides 目前是單點對單點——pickup_point(not null)+ dropoff_point(nullable)各一個,計費吃 distance_m(GPS 軌跡 vs OSRM 路線取大者,見 F3)。 多停靠點無處可存,必須新建資料表。

施作項目(嚴格相依,由上而下)

  • N1. ride_stops 資料表 ✅ 已實作(2026-07-17,migration 000021) ride_id(FK ON DELETE CASCADE)、seq、kind、point、address、passenger_label、 arrived_at、skipped_at。CHECK:seq >= 1、kind IN ('pickup','dropoff'); UNIQUE (ride_id, seq)——seq =「第幾站」,重複的話「下一站是誰」沒有答案。 (UNIQUE 已隱含建立 (ride_id, seq) 索引,不另建。)

    **實作時定的三件事**:
    1. **狀態用兩個時間欄(`arrived_at`/`skipped_at`)而非 status 字串**:兩者天然互斥、
       且都需要「何時發生」——時間欄同時回答「是否發生」與「何時」,不必另外維護狀態機。
       皆 NULL = 尚未處理。`skipped_at` 對應 2026-07-17 拍板的「司機可跳過缺席乘客」。
    2. **`passenger_label` 不做值域 CHECK**(不同於車種):純粹給司機辨識,不參與邏輯判斷,
       值髒掉不會算錯錢。
    3. **相容性已用測試釘住**:既有單點訂單**不產生任何 ride_stops 列**。
    
  • N2. 乘客數上限與驗證 ✅ 已實作(2026-07-17)(定案 2026-07-16:5 位乘客,各自上下車) 上限放 internal/constants/ride_stop.go(MaxRidePassengers=5/MaxRideStops=10), 不放 fleet_settings:它是產品規則不是營運費率,沒有「後台隨時要調」的需求, 放常數才能被編譯期引用(測試也直接讀它)。 驗證在 validateStops(純函式,internal/service/ride_stops_validate.go),全部回 400: 停靠點數 ≤10、乘客數 ≤5、kind 白名單、座標合法、seq 不得重複、 每位乘客成對 pickup+dropoff、dropoff.seq > pickup.seq(不能先送再接)。 錯誤刻意分成多個(而非一個籠統的 ErrInvalidStops)——乘客填錯時要知道錯在哪。 驗收:14 個單元案(合法:空 stops/兩人四停交錯/5 人 10 停上限/客戶端未依序送; 非法:超上限/未成對/先下後上/重複上車點/seq 重複/seq=0/kind 非白名單/無標籤/座標非法)。

  • N3. 建單 API 擴充(POST /api/rides)✅ 已實作(2026-07-17) body 加選填 stops: [{seq, kind, lat, lng, address, passenger_label}]。 無 stops =完全維持現行行為(測試釘住:單點建單不產生 ride_stops 列)。 有 stops 時 pickup/dropoff 由 stops 推導(第一個 pickup/seq 最大的 dropoff)並覆蓋 body 的 pickup_lat/lng 等欄位 → rides.pickup_point/dropoff_point 照樣有值, 派單、導航、地圖、F3 退路、報表一行都不用改。 落庫順序:停靠點寫在 rides.Create 之後、派單之前(派單一發出司機就該看得到全程), 寫失敗則整筆建單失敗——「只有第一個上車點、少載其餘乘客」的行程比沒建成更糟。 未注入 stops repo 卻收到 stops → ErrStopsUnavailable → 503(不是 400: 這是伺服器沒接好,不該讓乘客以為自己填錯)。

    **驗收**:`go build`/`vet`/`gofmt` 綠;整合測試(真 PostGIS + Redis)——
    多停靠點落庫(**含座標經緯度正確**、rides 推導正確、新停靠點為未處理狀態)、
    客戶端未依序送仍依 seq 落庫、**單點訂單不建 stops**、驗證失敗不留孤兒訂單、未注入時明確失敗。
    **反向驗證**:`ST_MakePoint` 經緯度對調 → 座標跑到 lat=58.48(愛沙尼亞),FAIL;
    拿掉「由 stops 推導 pickup/dropoff」→ 建單以 `無效的上車座標` FAIL。
    **未驗**:docker compose 全服務 live E2E。
    
  • N4. 派單與 ETA(dispatch.go)✅ 已實作(2026-07-17) 派單邏輯完全沒動——仍以 rides.pickup_point(=第一個上車點,N3 已推導)找最近司機。 ride.assigned 與司機端 ride.accepted payload 加 stops(司機接單前就看得到 「A 在哪上、B 在哪下、最終到哪」,才知道要不要接)。單點訂單不放 stops 鍵。 停靠點座標攤平成 lat/lng,與既有的 pickup_lat/pickup_lng 一致,App 端不必另寫解析。 讀停靠點失敗不擋派單:退化成「司機端看不到全程」,仍可依 pickup_point 前往第一個上車點。

    **FCM 註記(盤點後修正)**:TODO 原本提醒「FCM data 要 JSON 字串化」,
    但**現況根本還沒送 data**——`notify.SendRideOffer` 只送 title/body/ride_id,且實作是 stub
    (真 FCM 是 A2 待辦)。故 stops 目前**只走 WS**。此提醒已移到
    `rideAssignedPayload` 的註解,留給日後做真 FCM 的人(見 pitfall-fcm-data-all-strings)。
    
  • N5. 計費改吃「全程實際路線」 ✅ 已實作(2026-07-17)(定案 2026-07-16) (internal/osrm/client.go + tracking.go Complete)

    **實作內容**:
    1. **`osrm.Client.RouteVia(ctx, []Point)`**:URL 依序串接所有座標(`;` 分隔,`lng,lat` 順序)。
       **既有兩點 `RouteDuration` 完全不動**——派單 ETA 與 F3 既有行為不受影響。
       `Point` 型別自訂而非用 `model.GeoPoint`:osrm 是最底層的外部服務 client,不該依賴領域模型。
    2. **`fallbackVia` 逐段累加**:OSRM 掛掉時逐段 haversine×1.4 再取和。
    3. **`TrackingService.routeDistanceM`**:有未跳過的停靠點(≥2)就走全程多點路線,
       否則退回現行兩點直達(相容單點訂單)。**`billableDistanceM` 取大者的邏輯完全不變**。
    
    **已跳過的停靠點不計入**(2026-07-17 拍板「司機可跳過」的衍生結論):
    沒去就沒開那段路,計入等於收乘客沒走的路的錢。軌跡那側本來就自然反映(沒去就沒軌跡)。
    跳過後不足兩點時退回兩點直達,不會失敗。
    
    **不必把 `ride.PickupPoint` 另外補進路線**:N3 已保證 `rides.pickup_point` = 第一個 pickup stop、
    `dropoff_point` = seq 最大的 dropoff stop,兩者本來就在 stops 裡(補了會重複計算)。
    
    **驗收**:`go build`/`vet`/`gofmt` 綠。
    單元(`internal/osrm`,無需容器):URL 依序串接所有座標且為 `lng,lat`、點數不足回 `ErrTooFewPoints`、
    **OSRM 掛掉時逐段累加**(繞路里程 > 直達,且等於手動逐段和)、nil client 走退路。
    整合(真 PostGIS + fake OSRM 伺服器,斷言實際送出的座標):多停靠點走全程路線、
    **跳過的站不計入**、單點訂單維持兩點直達、全部跳過時退回兩點。
    **反向驗證**:拿掉 `st.Skipped()` 過濾 → 已跳過的座標出現在計費路線,FAIL;
    `fallbackVia` 改成只算頭尾 → 繞路(7040) = 直達(7040),繞路被漏掉,FAIL。
    **未驗**:docker compose 全服務 live E2E(含真 OSRM)。
    
    原始定案內容如下(保留供對照):
    **定案**:車資=**全程實際路線**(起點 → 各停靠點 → 最終目的地,**含繞路**),
    不是「起點→最終目的地」的直達路線。理由:司機真的開了那些路,繞路不該做白工;
    也與現行「軌跡 vs 路線取大者」的精神一致。
    
    **現況與缺口(已盤點)**:
    - `billableDistanceM(trackM, routeM)`=取大者,**這個邏輯不變**,只有 `routeM` 的算法要改。
    - `tracking.go` `Complete` 目前呼叫 `RouteDuration(pickup → dropoff)` 兩點直達 →
      多停靠點時會**嚴重低估**(繞路全部沒算到),取大者就只會拿到軌跡里程,
      軌跡若稀疏(見 F3)就會低估車資。
    - **`osrm.Client.RouteDuration` 介面寫死兩點**:
      `RouteDuration(ctx, fromLat, fromLng, toLat, toLng)`,
      URL 是 `/route/v1/driving/{lng},{lat};{lng},{lat}`。
      OSRM 的 `/route/v1` 本身支援多座標(`;` 分隔),**是我們的 client 沒開放**。
    
    **要做**:
    1. OSRM client 加多點介面(例如 `RouteVia(ctx, points []GeoPoint)`),
       URL 串接所有座標;保留現有兩點方法給派單 ETA 用(不動 F3/dispatch 既有行為)。
    2. `fallbackETA` 目前是「兩點 haversine × 1.4」——多點時要**逐段累加**再取和,
       否則 OSRM 掛掉時多停靠點的退路里程會退化成直達距離(同樣低估)。
    3. `Complete` 算 `routeM` 時,有 `ride_stops` 就走全程多點路線,沒有則維持現行兩點(相容舊訂單)。
    
    車資公式本身(起步+每公里、整數元、快照制、`min_fare` 地板)**完全不變**。
    
  • N6. 司機端行程 API 帶 stops ✅ 已實作(2026-07-17) GET /api/driver/rides/active 回 DriverRideView(內嵌 *model.Ride → JSON 攤平, 既有欄位一個不少,只多 stops;單點訂單為 omitempty 不會多出空陣列)。 ride.accepted 司機端 payload 同步帶 stops(見 N4)。 每個停靠點含 id/seq/kind/lat/lng/passenger_label/address, 以及 arrived_at/skipped_at(只在真的發生時帶,兩者皆無=待處理)—— 司機據此知道「下一站是誰、在哪、處理了沒」。

  • N8. 乘客端行程 API 帶 stops + 進度事件 ✅ 已實作(2026-07-21) 缺口是 App 端回報的:乘客送得出 stops(建單時),卻看不到自己排的行程—— CustomerRideView 只加了司機聯絡資訊,帶 stops 的只有 DriverRideView。 乘客端因此做不出多停靠點地圖與行程進度。

    1. **`CustomerRideView` 加 `Stops`**(`omitempty`):
       `GET /api/customer/rides/active` 與 `GET /api/customer/rides/:id` 都帶,
       **形狀與 `DriverRideView.Stops` 完全相同**(實跑比對過欄位集合一致),
       App 端兩邊共用同一套解析。單筆查詢也帶,歷史行程/遺失物協尋回頭查才看得到當時全程。
       讀 stops 失敗**不擋**整筆查詢(stops 是加值資訊,不是行程本體),
       未注入 `stops` repo 時查詢照樣成功。
    2. **新事件 `ride.stop_updated`**:司機標記到達/跳過時推給**本趟乘客**。
       payload 帶**整趟 stops** 而非單一 stop——乘客端收到直接覆蓋即可,
       不必在客戶端套用差異,漏收一則事件也不會讓狀態永遠對不上。
       **標記失敗(重複標記回 409)時不推事件**,否則乘客會收到「進度更新」卻什麼都沒變。
       publisher 未注入時標記照樣成功(只是乘客要等下一次輪詢)。
    
    **➡️ 2026-07-28 補:`ride.stop_updated` 也推給司機**(app 端第六輪 debug 抓到)。
    原本只推給乘客,理由寫在程式碼註解裡:「司機端剛做完動作、會自己重讀 active」——
    **那假設了司機只有一台裝置**。同一位司機的第二台裝置(或 LINE 那條路徑)標記時,
    這台不會重讀,畫面停在舊的「下一站」,而「下一站」正是司機端唯一給操作的那一站,
    兩台會對不同的站給按鈕。動作來源那台會多收到一則自己造成的事件(多一次重讀),
    比兩台狀態不一致便宜得多。
    **模擬器實跑對照**:舊版標記後 8 分鐘司機 App 完全沒動;新版 5 秒內
    整份清單跟上(前兩站變綠勾「已完成」、下一站前移、地圖重畫)。
    
    **驗收**:`go test ./internal/service/`(新增 9 項,含反向確認——
    把乘客路徑改回 `withDriverContact` 會 FAIL)、events/handler 測試綠;
    **docker live E2E**:乘客建 2 人 4 站訂單 → 乘客 active 回 4 站 →
    司機接單 → `arrive` 第 1 站 → **乘客 WS 即時收到 `ride.stop_updated`(帶整趟+`arrived_at`)**
    → `skip` 第 2 站 → 乘客 active 顯示「已到達/已跳過/待處理/待處理」,
    與司機端 `GET /api/driver/rides/active` 欄位形狀一致。
    
  • N7. 到站/跳過標記 ✅ 已實作(2026-07-17) (原標「可選」;因 2026-07-17 拍板「司機可跳過缺席乘客」而成為必要) POST /api/rides/:id/stops/:stop_id/arrive/POST /api/rides/:id/stops/:stop_id/skip (driver JWT,被指派司機限定)。

    **授權是重點**:`stop_id` 是**全域遞增**的 → 只驗 ride 歸屬不夠,
    必須**同時驗 `stop.RideID == rideID`**,否則司機可拿自己的 ride_id 去改別人行程的停靠點。
    已用測試釘住(**測試本身也踩過坑**:兩個 fixture 各起一個容器時 id 都從 1 開始,
    「別趟的 stop_id」會撞到自己那趟的同號 stop 而合法通過 → 測試改為在**同一個 DB** 建兩趟)。
    
    **不覆寫既有事實**:`MarkArrived`/`MarkSkipped` 皆為條件式更新
    (`WHERE arrived_at IS NULL AND skipped_at IS NULL`),重複標記或狀態已定回 **409**。
    **已到達的站不得反悔改成跳過**——那會讓 N5 的計費路線少算一段司機真的開過的路。
    行程已完成/取消時一律 409(計費已定格,改了也不會重算)。
    
    **驗收**:`go build`/`vet`/`gofmt` 綠。
    單元:`stopViews`(座標攤平、狀態鍵只在發生時帶、空回 nil)、`rideAssignedPayload`/
    `rideAcceptedDriverPayload` 帶/不帶 stops。
    整合(真 PostGIS):到達與跳過、不覆寫既有事實(重複標記/已到達改跳過皆 409)、
    **授權邊界三案**(別的司機/別趟的 stop_id/行程不存在)、行程已完成不得標記、`ListForDriver`。
    **反向驗證**:拿掉 `stop.RideID != rideID` 檢查 → 可標記別趟的停靠點,FAIL。
    **未驗**:docker compose 全服務 live E2E。
    

風險與待拍板

  1. 車資算法 ✅ 已拍板(2026-07-16):採全程實際路線(含繞路),見 N5。 衍生風險:乘客建單時看不到預估車資,繞路越多車資越高 → 若日後要「先報價」, 需要一支報價 API(以全程路線試算),目前沒有(後端只在完成時定格計費)。
  2. 狀態機 ✅ 已拍板(2026-07-17):維持單一 picked_up=第一位乘客上車, 其餘乘客不另計行程狀態。理由:F 系列報表、tracking 里程起點、已打通的三端對帳全部不受影響; ride_stops.arrived_at(N1 已含)保留為日後要精確化時的升級路徑。 已知取捨:「行程中」會涵蓋「尚未接到後續乘客」的區段。
  3. 上限 5 位 ✅ 已拍板(2026-07-16):5 位「乘客」,各自上下車 → 最多 10 個停靠點。
  4. 取消/缺席 ✅ 已拍板(2026-07-17):司機可標記跳過(乘客沒出現時)。 → N7 因此從「可選」變成必要:ride_stops 需要狀態欄(arrived_at/skipped_at) 與司機端標記 API。 對車資的影響(實作推論,非另行拍板):跳過的停靠點不計入 N5 的計費路線—— N5 的精神是「司機真的開了那些路,繞路不該做白工」;沒去的站就沒開那段路, 計入等於收乘客沒走的路的錢。軌跡那側本來就自然反映(沒去就沒軌跡), billableDistanceM 取大者的邏輯不變。
  5. admin 呈現:訂單詳情要顯示多個 stops 與軌跡(line-fleet-admin 對應項)。

🚗 O. 司機車輛資訊(車種/車牌/寵物車清潔費)(2026-07-16 規劃,未實作)

需求(使用者 2026-07-16,含後續拍板):

  • 乘客端顯示司機的車種與車牌,以便知道搭什麼車;司機必須先填車種車牌才能接單(強制跳轉引導)。
  • 車種為選單:轎車/休旅/七人座/無障礙/寵物用車。
  • 寵物用車加收清潔費(比原本車資貴一些),乘客端要顯示,加收上限 30%。
  • 司機換車後,乘客仍要能查到當時的車輛與司機聯絡方式,並有留言板可聯絡(與 H 遺失物協尋相關)。

前置事實(2026-07-16 盤點):

  • drivers 表:line_user_id/name/phone(已存在,not null default '')/status/password_hash, 沒有任何車輛欄位;司機上線只檢查定位權限,不檢查車輛資訊。 → 「司機聯絡方式」的欄位已經有了,缺的是「填寫、開放給該趟乘客查詢」。
  • fleet_settings 已有 lost_item_fee_bps(遺失物處理費 bps)→ 清潔費可完全比照(bps + 快照制)。
  • 既有 H1 ride_messages 聊天(REST 歷史 + WS 即時推播)綁 ride、無時間限制, 本質上已是「留言板 + 即時通知」→ 第 5 點多半是沿用既有 chat,而非另建一套。

施作項目

  • O1. drivers 加車輛欄位 ✅ 已實作(2026-07-16,migration 000017) vehicle_type/plate_number,沿用 drivers 既有慣例 TEXT NOT NULL DEFAULT ''('' =未設定)。 vehicle_color 不做(YAGNI):需求只要求顯示車種與車牌,日後要再加。

    **實作時定的兩件事**:
    1. **車種存字串 + DB CHECK**(非 smallint):`chk_drivers_vehicle_type`
       限定 `('', 'sedan', 'suv', 'van7', 'accessible', 'pet')`。
       放資料層而不只在 API 驗證——它是清潔費(O6)與派單過濾(P3)的判斷依據,值髒掉直接影響計費。
       Go 端白名單在 `internal/constants/vehicle.go`(`IsValidVehicleType` 刻意**不接受空字串**,
       避免 API 收到空值當合法而繞過 O3 gate)。
    2. **車牌唯一性 ✅ 拍板:partial unique index**
       `uq_drivers_plate_number ON drivers(plate_number) WHERE plate_number <> ''`。
       **不可用一般 `UNIQUE`**——既有司機 `plate_number` 全是 `''`,一般唯一鍵會讓
       第二個未填車牌的司機直接插不進去。**已用測試釘住**(反向驗證:改成一般 UNIQUE 該案即 FAIL)。
    
    **驗收**:`go build`/`vet` 綠;`internal/constants` 單元測試(白名單、防禦性副本);
    整合測試(真 PostGIS 容器 + 跑完整 migration)——
    `TestDriverVehicleSchema`(多筆空車牌不衝突/車牌非空時唯一/CHECK 擋非白名單)、
    `TestDriverVehicleMigrationReversible`(up → down → 再 up,欄位/CHECK/index 正確消失與回來)。
    反向驗證:一般 UNIQUE → 空車牌案 FAIL;down 漏 `DROP COLUMN` → 可逆性測試 FAIL。
    
    **順帶記錄的 Postgres 行為**:`DROP COLUMN` 會自動連帶刪除依賴該欄位的 CHECK 與 index,
    故 down 裡的 `DROP CONSTRAINT`/`DROP INDEX` 其實冗餘——保留是為了明示意圖(`IF EXISTS`,無害)。
    
  • O2. 車輛資訊 API ✅ 已實作(2026-07-17) GET/PUT /api/driver/vehicle(driver JWT,driver_id 一律取自 token,只能改自己的)。 回應形狀 {vehicle_type, plate_number, has_vehicle}——附 has_vehicle 是為了讓 App 不必自行判斷「兩欄皆非空」,與 O3 gate 用同一條件(model.Driver.HasVehicle())。 未設定時兩欄回空字串、has_vehicle=false,非錯誤。

    **車牌格式 ✅ 拍板(2026-07-17):寬鬆驗證**
    只檢查長度(2–10)與字元集(半形 `A-Z`/`0-9`/`-`,至少一個英數字),**不綁特定樣式**。
    台灣車牌多代並存(`ABC-1234`/`1234-AB`/`AB-1234`/電動車/機車格式),
    硬綁正則會誤擋真車牌;擋不住的髒值由 O3 gate 與人工審核(O5,若做)兜底。
    實作在 `constants.IsValidPlateNumber`/`NormalizePlateNumber`(去空白+轉大寫)。
    **正規化是唯一索引的前提**:不轉大寫去空白,同一台車會以
    「abc-1234」「ABC-1234」各佔一列,`uq_drivers_plate_number`(O1)形同虛設。
    
    **狀態碼**:車種非白名單/車牌格式錯/任一為空 → 400;車牌已被他人使用 → **409**;
    司機不存在 → 404。409 的關鍵是 `repository.UpdateVehicle` 把唯一索引衝突翻成
    `ErrPlateTaken`——原樣往上丟會變 500,司機看到「伺服器錯誤」而無從修正。
    衝突判斷用 `pgconn.PgError` 的 SQLSTATE `23505` +約束名,**不比對錯誤訊息字串**
    (訊息隨 Postgres 版本/語系變動);`jackc/pgx/v5` 因此從 indirect 升為 direct 依賴。
    
    **驗收**:`go build`/`vet`/`gofmt` 綠。
    `internal/constants` 單元測試(正規化、寬鬆驗證的合法/非法各案,含全形字元不視為合法);
    `internal/handler` 測試(授權邊界:無 token/customer token 皆 401;參數驗證 8 案皆 400);
    `internal/service` 整合測試 `TestDriverSetVehicle`(真 PostGIS:正規化後才寫入、
    驗證失敗不留半套資料、大小寫不同但同一車牌仍撞 `ErrPlateTaken`、司機不存在回 `ErrNotFound`);
    `internal/repository` 整合測試 `TestDriverRepositoryUpdateVehicle`(寫入、`ErrPlateTaken`、
    同一司機沿用自己車牌換車種不算衝突)。
    **反向驗證**:拿掉衝突翻譯 → 錯誤原樣為 SQLSTATE 23505,對應測試 FAIL;
    拿掉 `NormalizePlateNumber` → 正規化與車牌衝突兩案 FAIL。
    **未驗**:docker compose 起全服務的 live E2E(單元+整合已覆蓋,留待 O3 一起跑)。
    
  • O3. 接單前置檢查(gate) ✅ 已實作(2026-07-17)(定案 2026-07-16:強制填寫,無寬限期) 兩道都在後端(model.Driver.HasVehicle() 為單一判準,與 O2 回應的 has_vehicle 同源): 1. 派單過濾:dispatch.go 的 dispatchRound 候選迴圈跳過未填車輛者 (與既有「已派過/已拒接/非待命」同一層)。 2. 接單擋下:AcceptRide 回 ErrDriverNoVehicle。 API 自動得到 409——statusForErr 對非 ErrForbidden 的錯誤一律回 409,不必改 handler; LINE 路徑自動得到文字回覆——webhook 既有的 err.Error() 回覆會把 「請先填寫車種與車牌才能接單」原樣送給司機。 不能只靠 App 端擋——API 可被直接呼叫,故 gate 長在 service 層而非 handler。 順序:gate 排在既有的「非待命狀態」檢查之前——沒填車輛卻被告知「非待命狀態」, 司機不會知道要去填車輛。 既有司機:O1 migration 後兩欄皆為 '' → 一律無法接單,直到填完(無寬限期)。 後端不需要回填 migration,但上線前要通知司機(營運事項,非工程項)。

    **驗收**:`go build`/`vet`/`gofmt` 綠;`internal/service` 整合測試(真 PostGIS + Redis)——
    `TestDispatch_未填車輛的司機不被派單`(兩台同樣待命且都在附近,只有填了車輛的收到 `ride.assigned`)、
    `TestAcceptRide_未填車輛回ErrDriverNoVehicle`(回 `ErrDriverNoVehicle`、訂單狀態與司機狀態皆無副作用、
    **且有車司機隨後仍能接走這張單**——釘住 gate 早退時有正確釋放搶單鎖)。
    **反向驗證**:停用派單過濾 → 兩台都收到派單,測試 FAIL;停用接單 gate → `AcceptRide` 回 nil,測試 FAIL。
    **回歸**:`internal/service` 全套通過(781s,無 FAIL)。
    **順帶盤到的事實**:本次之前**沒有任何測試走過 `service.AcceptRide`/`Dispatch`**
    (既有測試一律用 `repository.AcceptRide` 直接改狀態),所以回歸全綠**不代表** gate 被既有測試考驗過——
    這兩條路徑的覆蓋完全來自本次新增的測試。日後改動搶單/派單邏輯時別誤以為有既有安全網。
    **未驗**:docker compose 全服務 live E2E。
    
  • O4. 乘客端可見車輛資訊 ✅ 已實作(2026-07-17,與 O7 同批) 三條路徑都帶:ride.accepted payload(rideAcceptedCustomerPayload)、 GET /api/customer/rides/active、GET /api/customer/rides/:id(後兩者見 O7 的 CustomerRideView)。 送車種 code 而非顯示名(O1 原則:顯示名由前端對應)。 空值不帶該鍵(而非帶空字串)——寧可少一個鍵,也不要讓 App 顯示空白車牌。 隱私:ride.accepted 的收件人是 ride.CustomerID 一人;查詢類一律先授權再組資料(見 O7)。

  • O5. admin 呈現/審核 ✅ 已實作(2026-07-19,migration 000022,PR #40) 使用者 2026-07-19 拍板「先做」。O3 的 gate 條件已升級為「已審核」而非「有填」 (VehicleApproved() 取代 HasVehicle(),派單側+接單側);接單側分 ErrDriverNoVehicle(沒填)與 ErrDriverNotApproved(待審核),司機知道下一步。 UpdateVehicle 原子地把 review 重置 pending(改車一律重審); admin POST /drivers/:id/vehicle-review(ops 角色,只有 pending 可審、退回必附原因)。 三端同批上線:司機 App 四態路由(fleet-app PR #35)、admin 審核 UI(fleet-frontEnd PR #20)。

  • O6. 寵物用車清潔費 ✅ 已實作(2026-07-17,migration 000019)(定案 2026-07-16:比例加收,上限 30%)

    **計費**(`FeeSettings.Quote`):簽名改為 `Quote(distanceM int, requiredVehicleType string) RideQuote`。
    **刻意改簽名而不留舊 wrapper**——留了就是留一個「忘了帶車種=靜靜不收清潔費」的陷阱;
    改簽名讓漏改的呼叫點直接編譯不過(實測產品碼只有 `tracking.go` 一處,測試三處)。
    ```
    cleaning_fee = floorNtd(fare × pet_cleaning_fee_bps / 10000)   // 僅乘客指定 pet;捨去(利乘客)
    commission   = floorNtd(fare × commission_bps / 10000)         // 基準只有 fare,清潔費不計入抽成
    driver_net   = fare − commission + cleaning_fee                // 清潔費全額歸司機
    ```
    **判斷依據是 `rides.required_vehicle_type`,不是 `drivers.vehicle_type`**——
    `Quote` 只吃乘客指定的車種,司機車種根本傳不進去(型別層面就擋掉誤用)。
    
    **報表分項(與計費同批,不可分開上線)**:`daily_driver_earnings` 加 `cleaning_fee_cents`;
    `RollupRideDay`/`MonthlyDriverStats`/`DriverMonthlyEarnings` 三段 SQL 同步。
    營業額(`revenue_cents`)**維持只含車資**;應付總公司=手續費+月會費,**不受清潔費影響**。
    **為什麼不能分兩批**:`net_cents` 來自 `driver_net_amount_cents`,該欄已含清潔費 →
    不同步加分項欄,司機收入頁的「營業額 − 手續費」就對不上實得(差額正是清潔費),
    破壞先前打通的三端對帳。等式因此改為 **營業額 − 手續費 + 清潔費 = 實得**(測試直接釘住這條式子)。
    
    **資料**:`fleet_settings.pet_cleaning_fee_bps`(CHECK `0..3000`,上限進 DB 不只靠 API——
    這是乘客實際被收的錢,寫錯就是超收)、`rides.cleaning_fee_cents`(nullable,完成時定格)、
    `daily_driver_earnings.cleaning_fee_cents`(NOT NULL DEFAULT 0,彙總欄一律有值)。
    非寵物車行程寫 **0 而非 NULL**:「這趟沒加收」與「舊資料沒這個概念」是兩件事。
    
    **乘客端可見**:`ride.completed` payload 加 `cleaning_fee_cents`,**只在 >0 時帶**——
    帶 0 會讓 App 顯示一列「清潔費 NT$0」。
    
    **驗收**:`go build`/`vet`/`gofmt` 綠。
    單元:清潔費算式(釘住「不計入抽成」的具體數字——正確 2700、誤把清潔費計入基準則為 3300)、
    只看乘客指定車種(`''`/sedan/suv/van7/accessible 皆不加收)、費率 0 不加收、捨去到整數元、
    上限 `MaxPetCleaningFeeBps`、**P5 白名單**(`CustomerJSON` 只有一個欄位,內部費率一個都不能出現)。
    整合(真 PostGIS + Redis):`TestComplete_指定寵物車落帳清潔費`(定格寫入+payload 分項)、
    **`TestComplete_寵物車司機載到未指定的乘客不加收`**(最容易寫錯的一條)、
    `TestCleaningFeeReports`(報表分項與等式)、`TestFleetSettingsPetCleaningFeeCap`(DB CHECK 擋 3001/負值)、
    `TestPetCleaningFeeMigrationReversible`。
    **反向驗證**:清潔費計入抽成基準 → 手續費變 3300,FAIL;`CustomerJSON` 改回 `JSON()` →
    手續費/月會費整組外洩,FAIL;`Quote` 改吃司機車種 → 未指定的乘客被加收,FAIL。
    **未驗**:docker compose 全服務 live E2E。
    
    **下游待同步(本 repo 之外,兩端都會「少一個分項」而非算錯)**:
    - admin:費率設定頁加 `pet_cleaning_fee_bps`;月報表加清潔費分項欄(`total_cleaning_fee_cents`)。
    - App:完成卡分項顯示(`CompletedRideSummary` 加 `cleaningFeeCents`);
      司機收入頁改用「營業額 − 手續費 + 清潔費 = 實得」(`GET /api/driver/earnings` 已回 `total_cleaning_fee_cents`)。
    
    原始定案內容如下(保留供對照):
    **規則** ✅ 觸發條件已拍板(2026-07-16):**依「乘客指定的車種」加收,不是依司機的車種**——
    乘客叫車時指定 `pet`(寵物用車)的行程,才在車資之上加收清潔費(見 **P. 乘客指定車種**)。
    比例由後台設定,**硬上限 30%**(超過一律拒絕)。
    
    **重要**:判斷依據是 `rides.required_vehicle_type == 'pet'`,**不可寫成 `driver.vehicle_type == 'pet'`**。
    乘客沒指定寵物車、卻剛好被派到寵物車司機時(未指定=不過濾車種)**不得加收**——
    那位乘客沒有要求寵物服務。
    
    **資料**:`fleet_settings` 加 `pet_cleaning_fee_bps`(比照 `lost_item_fee_bps`),
    CHECK `>= 0 AND <= 3000`(3000 bps = 30%,**上限寫進 DB CHECK,不只靠 API 驗證**)。
    
    **計算**(`fee_settings.go` `Quote()`):
    1. 先照現行算出 `fare`(起步+每公里、`min_fare` 地板、`roundNtd` 整數元)
    2. 若 `rides.required_vehicle_type == 'pet'`:
       `cleaning_fee = floorNtd(fare × pet_cleaning_fee_bps / 10000)`(**捨去到整數元**,利乘客;
       比照 M 的整數台幣原則,金額必為 100 的倍數);否則為 0/null
    3. `total = fare + cleaning_fee`
    **手續費基準 ✅ 已拍板(2026-07-16):清潔費不計入抽成**——
    `commission = floorNtd(fare × commission_bps / 10000)`(基準只有 `fare`);
    `driver_net = fare − commission + cleaning_fee`(**清潔費全額歸司機**,是清潔成本補償、不是營收)。
    **報表歸屬(一致性延伸)**:F5/F6/F7 與 `daily_driver_earnings` 的「營業額」**不含**清潔費、
    另立 `cleaning_fee` 分項欄;「應付總公司=手續費+月會費」**不受清潔費影響**。
    快照欄位 `rides.cleaning_fee_cents` 是報表分項的資料來源。
    
    **落帳**:`rides` 加 `cleaning_fee_cents`(nullable,完成時定格,**比照費率快照制**)。
    報表(F5/F6/F7、`daily_driver_earnings`)要決定清潔費算不算「營業額」(見風險 5)。
    
    **乘客端可見**:完成卡與(若日後有)報價都要**分項顯示**「車資」與「清潔費」,
    不可只給總額——使用者明確要求「乘客端要顯示多增加清潔費」。
    
  • O7. 車輛快照 + 司機聯絡方式 + 留言板 ✅ 已實作(2026-07-17,migration 000020)(定案 2026-07-16)

    **1. 車輛快照**:`rides.driver_vehicle_type`/`driver_plate_number`,**接單時**定格
    (不是完成時——乘客在「司機前往上車點」階段就要對車)。
    **快照由 `AcceptRide` 的同一個 UPDATE 以子查詢自 drivers 複製**,不由呼叫端傳入:
    與 `driver_id` 原子性定格,不會有「接了單但快照還沒寫」的中間狀態,
    且呼叫端不可能傳錯車。副作用:`AcceptRide` 簽名不變,既有呼叫點與測試零改動。
    值域比照 O1 由 CHECK 把關;**不加車牌唯一索引**——快照是歷史紀錄,同一台車本來就會出現在很多趟。
    
    **2. 司機聯絡方式**:`CustomerRideView`(內嵌 `*model.Ride` → JSON 攤平,既有欄位一個不少)
    加 `driver_name`/`driver_phone`,用於 `rides/active` 與 `rides/:id`;`ride.accepted` payload 亦帶。
    **來源刻意不同**:車種/車牌讀 **ride 快照**(司機換車後歷史不變),
    電話讀 **drivers 即時值**(司機換號碼後,乘客要撥得通的是新號碼)。不要「順手」統一。
    **授權順序是重點**:`GetRideForCustomer` 先驗 `ride.CustomerID != customerID → 403`,
    **再**組司機資訊——顛倒過來就會連同 403 把明碼電話一起吐出去(反向驗證確認會 FAIL)。
    
    **3. 留言板**:確認沿用既有 H1 `ride_messages`,**未新增任何程式**。
    `authorizeRideParticipant` 只看「是否本趟參與者」,不看狀態也不看時間 →
    行程完成很久後仍可對話。**規格要求先寫測試釘住**,已補
    `TestChat_行程完成很久之後仍可對話`(90 天前完成的行程:乘客發話/司機回話/讀歷史皆可,
    **非參與者仍 403**——「沒有時間限制」不等於「沒有授權」)。
    
    **驗收**:`go build`/`vet`/`gofmt` 綠。
    單元:`rideAcceptedCustomerPayload`(帶車種/車牌/電話;空值不帶鍵)。
    整合(真 PostGIS):`TestAcceptRide車輛快照定格`(**司機換車後歷史快照不變**——不用 JOIN drivers 的理由)、
    `TestGetActiveRideByCustomer帶司機資訊`(含「既有 ride 欄位不得因換成 view 而消失」)、
    `TestGetRideForCustomer電話僅本人可見`、`TestChat_行程完成很久之後仍可對話`。
    **反向驗證**:移除快照寫入 → 快照為空,FAIL;授權移到組資料之後 →
    403 連同 `DriverPhone:0912345678` 一起回傳,FAIL。
    **未驗**:docker compose 全服務 live E2E。
    
    **範圍說明**:遺失物協尋詳情的司機電話**不需另做**——App 端以協尋單的 `ride_id`
    呼叫 `GET /api/customer/rides/:id` 即可取得(該路徑已帶電話且無時間限制)。
    
    原始定案內容如下(保留供對照):
    **問題**:司機換車/換手機後,乘客回頭找遺失物時,要知道「當時搭哪台車」「怎麼聯絡司機」。
    
    1. **車輛快照**:`rides` 加 `driver_vehicle_type`/`driver_plate_number`(完成或接單時定格)。
       **理由**:`drivers` 的車輛欄位會被司機改掉,歷史行程不能跟著變
       (與費率/會費/遺失物處理費的快照制一致)。
    2. **司機聯絡方式** ✅ 電話呈現已拍板(2026-07-16):**明碼、僅該趟乘客可見**。
       `drivers.phone` **欄位已存在**,缺的是
       (a) 司機填寫入口(併入 O2 車輛設定頁),
       (b) 開放**該趟乘客**查詢(`ride.accepted` payload/`rides/active`/遺失物協尋詳情),
       沿用既有 MultiAuth 授權、**絕不可公開列出**(司機列表 API 對乘客不可見)。
       已知取捨:明碼=行程結束後乘客仍可撥打;若日後出現騷擾案例,
       再升級遮罩/轉接號碼(欄位與授權面不變,只改呈現層)。
    3. **留言板**:**沿用既有 H1 `ride_messages`**(REST 歷史 + WS 即時;已綁 ride、無時間限制),
       **不另建一套**。遺失物協尋(H2)本來就共用同一條對話。
       需確認:行程完成很久之後乘客仍能發話(目前授權是「本趟乘客/司機」,看起來可以,
       **實作前要寫一個測試釘住這個行為**)。
    

風險與待拍板

  1. 車種自由文字 vs 選單 ✅ 已拍板:選單(轎車/休旅/七人座/無障礙/寵物用車),見 O1。

  2. 車牌格式驗證(O2 要面對,O1 不管格式):台灣車牌格式多樣(舊式/新式/機車/電動車), 過嚴會擋到真司機。建議寬鬆格式 + 後台可修正。O1 的 DB 層只保證唯一性,不驗格式。

  3. 既有司機資料 ✅ 已拍板:強制填寫、不設寬限期,App 端強制跳轉引導,見 O3。 營運提醒:上線當下所有司機都會無法接單,需事前通知。

  4. 車輛異動 ✅ 已拍板:rides 落車輛快照+開放司機聯絡方式+沿用既有 chat 當留言板,見 O7。

  5. 寵物車加收的觸發條件 ✅ 已拍板(2026-07-16):(b) 乘客叫車時指定車種 → 衍生出一整塊新功能,獨立成 P. 乘客指定車種(叫車帶車種、派單依車種過濾、乘客端選擇 UI)。 清潔費依 rides.required_vehicle_type == 'pet' 觸發,與司機車種無關。

  6. 手續費/營業額基準 ✅ 已拍板(2026-07-16):清潔費不計入抽成, 全額歸司機;報表分項顯示、營業額不含清潔費,見 O6 計算段。

  7. 司機電話的隱私 ✅ 已拍板(2026-07-16):明碼、僅該趟乘客可見(沿用 MultiAuth), 見 O7。已知取捨:行程結束後仍可撥打;出現騷擾案例再升級遮罩/轉接(只動呈現層)。


🐾 P. 乘客指定車種(2026-07-16 規劃,未實作)

由 O6 寵物車清潔費的拍板衍生:加收依「乘客指定的車種」而非司機車種(使用者 2026-07-16 選 (b)), 因此必須先有「乘客叫車時指定車種」的能力。

這不只服務寵物車——無障礙車、七人座同樣是「乘客有特定需求才要」的車種, 本章節做的是通用的車種需求,清潔費只是其中一種車種的計費後果。

前置事實(2026-07-16 盤點):

  • 叫車 API(internal/handler/ride.go)的 request 沒有車種欄位(只有 pickup/dropoff 座標與地址)。
  • dispatch.go 候選司機過濾只看 driver.Status != DriverStatusIdle, 完全不管車種(因為 drivers 現在也沒有車種欄位,見 O1)。
  • 找不到司機時的現行行為:擴大半徑重派 → 達 maxAttempts 仍無人接 → 自動取消並推播 「抱歉,附近暫無可用司機,請稍後再試」(giveUpIfUnaccepted)。

施作項目

  • P1. rides 加 required_vehicle_type ✅ 已實作(2026-07-17,migration 000018) 值域同 O1 的車種 code 白名單,由 chk_rides_required_vehicle_type 把關(與 O1 同理由: 這是清潔費 O6 加收與否的判斷依據,值髒掉直接影響計費,最後防線要在資料層)。 存在 ride 上(不是只當派單參數)——清潔費、報表、稽核都要回頭看「這趟乘客要的是什麼車」。

    **實作時定的一件事**:規格寫「null/空=不指定」,實作採 **`TEXT NOT NULL DEFAULT ''`**(沿用 O1 慣例),
    **不用 NULL**——否則「未指定」會有 NULL 與 `''` 兩種表示法,每個過濾條件都得同時處理兩者,
    遲早有一條路徑漏掉。既有訂單一律為 `''`(不指定),維持現行行為。
    
    **驗收**:`go build`/`vet`/`gofmt` 綠;`internal/repository` 整合測試(真 PostGIS + 跑完整 migration)——
    `TestRideRequiredVehicleTypeSchema`(**既有建單路徑預設為不指定**:`RideRepository.Create` 走 raw INSERT
    且不含新欄位,DB default 必須生效,否則既有 App/LINE 建單全掛/白名單皆可寫入/非白名單由 CHECK 擋下)、
    `TestRideRequiredVehicleMigrationReversible`(up → down 到 v17 → 再 up)。
    **反向驗證**:拿掉 CHECK → 非白名單案 FAIL。
    
    **順帶修掉一個既有測試的隱含假設**:`TestDriverVehicleMigrationReversible`(O1)用 `m.Steps(-1)`
    驗自己的 down,隱含「O1 是最後一個 migration」。P1 一加,那步卸的就變成 P1,**O1 的 down 會安靜地失去覆蓋**。
    已改為先 `m.Migrate(17)` 再 `Steps(-1)`,P1 的測試同樣以版本表達意圖。
    **反向驗證**:拿掉該修正 → O1 測試 FAIL(`down 後不應還有欄位 vehicle_type`)。
    **日後新增 migration 者注意**:可逆性測試要用版本導向,別用「往回一步」。
    
  • P2. 叫車 API 帶車種(POST /api/rides)✅ 已實作(2026-07-17) request 加選填 required_vehicle_type;未帶=不指定,維持現行行為。 非白名單值 → ErrInvalidVehicleType → 400(createStatusForErr 新增映射)。 驗證放在 service 而非仰賴 DB CHECK:撞 CHECK 會變成 500,乘客看到「伺服器錯誤」而不知道是車種填錯。

    **改動四處**(缺一不可):handler request struct → `CustomerCreateRequest` →
    `CreateByCustomer` 驗證+帶入 model → **`RideRepository.Create` 的 raw INSERT**。
    最後一項最容易漏:`Create` 走 raw SQL,**不是 GORM 自動映射**——service 設了
    `RequiredVehicleType`,SQL 沒帶就靜靜地存成 `''`,回傳的 struct 卻是對的(只有 DB 是空的)。
    且它有「帶/不帶 dropoff」**兩條 INSERT 分支,兩條都要補**。
    
    **驗收**:`go build`/`vet`/`gofmt` 綠;`internal/service` 整合測試(真 PostGIS + Redis)——
    指定車種持久化(**重讀 DB**,不只看回傳值)、**無目的地的單也要帶車種**(釘住第二條 INSERT 分支)、
    未指定維持現行行為(`''`,不破壞既有 App/LINE 建單)、非白名單被拒回 `ErrInvalidVehicleType`。
    **反向驗證**:只讓「無目的地」分支漏帶值 → 該案 FAIL(`得到 ""`)、有目的地案照樣 PASS
    ——證明兩條分支各需一個測試。
    **未驗**:docker compose 全服務 live E2E。
    
  • P3. 派單依車種過濾(dispatch.go 候選司機迴圈)✅ 已實作(2026-07-17) ride.RequiredVehicleType != "" && driver.VehicleType != ride.RequiredVehicleType → skip, 排在 O3 的 HasVehicle() gate 之後(無車輛資料者本來就不得被派單,兩者疊加)。 未指定('')時完全不過濾,既有訂單行為不變。

  • P4. 「找不到指定車種」的行為 ✅ 已實作(2026-07-17)(定案 2026-07-16:不降級+取消原因明確化) 不降級由 P3 的過濾直接達成(找不到就沒有候選 → 走現行 giveUpIfUnaccepted 自動取消)。 取消原因明確化:新增 giveUpCancelInfo(ride) 同時決定「機器可讀原因/給乘客的文案/WS payload」, 三者由同一處產生,不會各自漂移。 - 未指定車種:cancel_reason=no_driver_available + 原文案「抱歉,附近暫無可用司機,請稍後再試」。 - 指定車種:cancel_reason=no_vehicle_of_type + required_vehicle_type + 文案「抱歉,附近暫無寵物用車,請稍後再試」。 常數在 internal/constants/cancel_reason.go。 顯示名的例外:一般原則是「後端只認 code、顯示名由前端對應」(O1),但 LINE 推播文案是後端組的, 沒有前端可以對應 → 加 constants.VehicleTypeDisplayName,僅供後端自產文案使用; API/WS payload 一律只送 code。未知 code 回「可用車輛」,讓文案在資料異常時仍讀得通。 範圍限制(App 端請注意):目前只有逾時取消這條路徑帶 cancel_reason; 乘客主動取消/司機放棄等路徑不帶,App 端須容忍此欄位缺席。

    **驗收**:`go build`/`vet`/`gofmt` 綠。
    單元 `TestGiveUpCancelInfo`(未指定→泛用文案且**不帶** `required_vehicle_type` 鍵,
    否則 App 會誤以為乘客指定過/指定→原因、文案、payload 三者皆具體);
    整合(真 PostGIS + Redis)`TestDispatch_指定車種只派同車種`、
    `TestDispatch_未指定車種時所有車種都可派`(釘住「不可讓既有不指定的單變窄」)、
    `TestDispatch_找不到指定車種時取消並帶原因`(端到端:一台都不派 → 逾時自動取消 →
    `ride.cancelled` 帶 `no_vehicle_of_type`+車種、訂單狀態為已取消;
    測試把 `offerTimeout` 設 1 秒讓 `giveUpIfUnaccepted` 在測試時間內觸發)。
    **反向驗證**:停用 P3 過濾 → 兩台都收到派單、「不降級」斷言 FAIL;
    停用 P4 車種分支 → `cancel_reason` 退回 `no_driver_available`,單元與整合皆 FAIL。
    **未驗**:docker compose 全服務 live E2E。
    
    原始定案內容如下(保留供對照):
    1. **不降級**:找不到指定車種時**不改派一般車**,走現行 `giveUpIfUnaccepted` 自動取消。
       寵物車/無障礙車是硬需求,默默派來一般車=服務失敗還照收錢。
    2. **取消原因明確化**:`giveUpIfUnaccepted` 目前推播固定文案「抱歉,附近暫無可用司機,請稍後再試」;
       `ride.RequiredVehicleType != ""` 時改為帶車種的文案(例如「抱歉,附近暫無寵物用車,請稍後再試」,
       車種顯示名由 code 對應)。**LINE 推播與 WS `ride.cancelled` payload 都要帶**:
       payload 加 `cancel_reason`(機器可讀,如 `no_vehicle_of_type`)+`required_vehicle_type`,
       讓 App 端能顯示明確原因而不是只靠文案字串。
    3. 實作時機:與 P3 同一批(P3 讓「找不到」變得可能發生,兩者不可分開上線——
       只上 P3 不上 P4,乘客會收到誤導性的泛用取消訊息)。
    
  • P5. 乘客可讀的唯讀費率端點 ✅ 已實作(2026-07-17)(定案 2026-07-16:新增專用端點) GET /api/customer/fees(customer JWT,唯讀)→ 目前只回 pet_cleaning_fee_bps。 回的是 FeeSettings.CustomerJSON()——另建的白名單 map,不是把 admin 的 JSON() 過濾。 理由如定案所述:過濾式寫法日後新增內部費率欄位時容易忘了濾,白名單預設什麼都不給。 讀記憶體快取(與 F4 同源),無額外 DB 負擔。 掛既有 customerAuthed 群組(middleware.CustomerAuth)。 驗收:TestCustomerJSON白名單 逐一斷言 commission_bps/monthly_membership_fee_cents/ 起步價/每公里/最低車資/遺失物費率皆不得出現,且欄位總數為 1。 反向驗證:改成 return s.JSON() → 測試抓到 commission_bps 外洩,FAIL。

    原始定案內容如下(保留供對照):
    **`GET /api/customer/fees`**(customer JWT,唯讀):只回乘客該知道的欄位——
    `pet_cleaning_fee_bps`(寵物車清潔費%);日後乘客需要知道的費率(如起步價,若要做預估)再逐一加入。
    **白名單輸出,絕不可外洩** `commission_bps`(手續費)/`monthly_membership_fee_cents`(月會費)
    等內部費率——**不是把 admin 的 response 過濾,而是 handler 另建只含白名單欄位的 struct**
    (過濾式寫法日後加欄位容易忘了濾,新 struct 預設不洩漏)。
    掛既有 customer JWT middleware;讀 `FeeSettings` 記憶體快取(與 F4 同源),無額外 DB 負擔。
    乘客端於「選擇車種」UI 呼叫,選寵物車當下顯示「將加收清潔費 X%(上限 30%)」。
    

風險與待拍板

  1. 降級策略 ✅ 已拍板(2026-07-16):不降級——找不到指定車種就明確取消並說明原因,見 P4。
  2. 車種供給:若車隊裡沒有任何寵物車司機,這個選項在乘客端要不要隱藏/停用? 需要「有哪些車種目前可用」的查詢(可由 redis 在線司機 + 車種聚合,但會增加派單前的查詢成本)。
  3. 乘客可讀的費率 API ✅ 已拍板(2026-07-16):做 GET /api/customer/fees, 白名單輸出(handler 另建 struct,非過濾 admin response),見 P5。
  4. 與 N(多停靠點)的交互:多乘客行程若指定寵物車,清潔費仍只加一次(依 ride 而非依乘客)—— 實作時要釘住這個語意。

🔧 Q. 下游缺口回補(2026-07-22)

起因:盤點三端程式碼(不只看勾選)發現後端有三個洞——兩個讓 admin/App 顯示不出已完成的能力, 一個讓已拍板的功能實質從未生效。三項皆已實作並測過。

  • Q1. 日報表補清潔費分項(ReportRepository.DailyDriverStats) 月報表(F6)與司機收入(F7)早就有 total_cleaning_fee_cents,日報表 F5 漏了。 少了它,日報表的「營業額 − 手續費」會莫名對不上 driver_net_cents——差額正是清潔費, 而 admin 只呈現不算錢,看到的就是一組兜不攏的數字。 驗收:TestCleaningFeeReports/日報表分項與等式(testcontainers 真 Postgres); 反向確認拿掉 SQL 那行會 FAIL(實測 得到 0,預期 3700)。

  • Q2. admin 訂單詳情帶 stops(AdminHandler.RideDetail + SetRideStops 注入) 多停靠點行程(N)在後台只看得到由停靠點推導出的單一上車/下車點,中間的乘客完全消失, 客服無法回答「這趟載了誰、停了哪幾站、哪站被跳過」。 形狀共用 service.StopViews(=司機/乘客端同一份 stopView)——三端說法不一致就沒得對帳。 停靠點讀取失敗不擋整個詳情頁;單點訂單不帶 stops 鍵(不是空陣列)。 驗收:TestAdminRideDetail_帶停靠點/_未注入停靠點repo仍可用; 反向確認拿掉 main.go 的 SetRideStops 接線會 FAIL(比照 N4 踩過的漏接線坑)。

  • Q3. 司機聯絡電話寫入路徑(PUT /api/driver/profile) O7 拍板「電話明碼、乘客可直接撥打」,但 drivers.phone 從來沒有任何寫入路徑—— 註冊不收、車輛設定也不收,只能手動改 DB。結果乘客端的 tel: 撥號按鈕實質永遠不出現。 新增 DriverRegistry.SetPhone + DriverRepository.UpdatePhone(寬鬆驗證:去分隔符後 8–15 位數字,可帶 +;不綁「09 開頭」,車隊可能有市話或境外號碼)。 刻意與 PUT /driver/vehicle 分開:電話不是車輛屬性,改電話若重置 O5 審核, 司機為了更新一個號碼就會被鎖出派單池。 讀取端 GET /driver/vehicle 順帶回 phone(唯讀便利欄位,設定頁一次讀完省一支往返)。 驗收:TestDriverProfile_*(授權邊界/參數驗證/改電話不重置車輛審核 走真 DB)。 App 端對應:司機車輛設定頁加聯絡電話欄(fleet-app 同批)。

💰 R. 建單前車資預估報價 API(2026-07-23)

App 端「懸而未決 #1」拍板:投資一支報價 API,讓乘客在建單前看到預估車資, 不必到行程結束才知道多少錢——多停靠點行程(N5「車資=全程實際路線含繞路」)放大了 「先搭後知價」的痛點,這是本題主因。是預估不是定價:計費仍在完成時依實際行駛路線定格。

  • POST /api/customer/rides/estimate(customer JWT,純唯讀) ✅ 2026-07-23 新 service.EstimateService{osrm, fees}:以全程規劃路線(起點 → 各停靠點 → 終點,含繞路) 算里程,與完成計費共用同一份 FeeSettings.Quote——預估與實收落在同一套費率規則, 差異只來自「規劃路線 vs 實際行駛路線」(繞路、跳過站、GPS 軌跡)。 - 距離走既有 osrm.RouteVia(與 N5 計費同一支多點路線 API);OSRM 掛掉時內部退回逐段 haversine,故預估永遠算得出一個近似值,不因路網引擎暫時不可用就讓乘客卡住。 - 輸入形狀與建單相同,沿用 validateStops/sortStopsBySeq/座標驗證——不另造一套 驗證邏輯。目的地座標必填(沒終點無法路由);車種選填(寵物車含清潔費)。 - 多停靠點:全部停靠點都入路線(預估階段還沒有人被跳過),與計費的 billableStopPoints (排除已跳過者)刻意不同:那是實際計費,這是全程預估。 - 回傳白名單欄位:fare_cents/cleaning_fee_cents/total_cents/distance_m/ duration_sec——不回 commission/driver_net 等內部費率(比照 FeeSettings.CustomerJSON)。 - 錯誤對應:座標/車種/停靠點填錯 → 400(沿用建單 createStatusForErr); 服務未就緒(未注入 osrm/fees)→ 503。 - 驗收:internal/service/estimate_test.go 8 案(單點/多停靠點全程入路線/寵物清潔費/ 缺目的地 400/非法車種/min_fare 下限/未成對停靠點/未就緒)+ internal/handler/estimate_test.go 2 案(授權 401/403、綁定 400、未就緒 503)。 - App 端對應:叫車表單顯示預估卡(fleet-app 同批),失敗靜默不擋叫車。 - ✅ live E2E 對帳(2026-07-23,本機起服務 + m6_pixel):預估與完成共用 FeeSettings.Quote+同一 OSRM 路線 → 不繞路時實收=預估。實測: 單點 6811m 預估 fare 22100 = 完成 22100;寵物車(清潔費率 20%)預估 fare 22100+清潔費 4400 = 完成 22100+4400(車資與清潔費皆一致); App 建單 ride #24(429m)完成卡「車資 NT$94」= 同座標預估 NT$94。 繞路時走 N5 既有 max(軌跡, 路線),故「實際依行駛路線可能不同」的免責成立。

⭐ S. 乘客評分司機(B5,2026-07-27)

App 端 B5 從 2026-07-08 起就在完成卡放著 disabled 的「留下評分(即將開放)」佔位, 標註「真實 API 待 Phase C」——這是全 App 最後一個還印著「即將開放」的功能。 後端從無評分資料表與端點(grep -i rating 全 repo 零命中),本批補齊。 對應 backend-api-gaps.md P4 #16。

  • migration 000023 ride_ratings ✅ 2026-07-27 ride_id(FK rides,ON DELETE CASCADE)/customer_id/driver_id/score/comment/created_at。 - 一趟一評、不可重評(唯一索引 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) ✅ 2026-07-27 service.RatingService.RateByCustomer 驗證順序刻意是「輸入 → 歸屬 → 狀態 → 重複」: 先擋不必查 DB 的輸入錯誤,再依序回答「這趟是不是你的」「完成了沒」「你評過了沒」。 - 錯誤對應:星等越界/評論過長 → 400;非本人 → 403(訂單存在,只是不是你的); 不存在 → 404;已評過/行程未完成 → 409(狀態衝突而非輸入格式錯, App 據此知道不必請乘客改參數重送)。 - 沒司機的行程(派單前取消)沒有評分對象,與「未完成」同走 ErrRideNotCompleted。
  • 讀回路徑(沒有讀回,App 無從知道評過沒)✅ 2026-07-27 - CustomerRideView 加 rating(GET /customer/rides/:id/active);未評分時整個鍵不出現。 (App 目前從歷史列表的 rating_score 判斷評過沒;這個欄位供訂單詳情路徑使用。) - CustomerRideRow 加 rating_score(GET /customer/rides 歷史列表,LEFT JOIN ride_ratings;一趟至多一則故不會讓行程重複出現)——完成卡關掉後這是唯一的補評路徑。 - GET /api/driver/me 加 rating_avg/rating_count,司機看得到自己被評幾分。 查失敗不擋 /me(加值資訊,不該讓司機因此載不出首頁);新司機無評分回 (0, 0) 而非錯誤。 - 三處注入都是可選的 SetRating/SetRatings,未注入時既有回應形狀一個欄位不少。
  • 驗收 ✅ 2026-07-27:go build ./...+go vet ./... 乾淨; 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)。
  • App 端對應(fleet-app 同批):完成卡「留下評分」開 1–5 星+評論的 bottom sheet; 歷史清單未評給「評分」、已評顯示星等;司機收入頁顯示「服務評價 4.5 / 5.0(12 則)」。

✅ 模擬器實跑 E2E(2026-07-27,m6_pixel + docker compose 三服務,全程截圖):

  • migration 000023 真的套用:容器啟動後 \d ride_ratings 顯示表、唯一索引 uq_ride_ratings_ride_id、兩條 CHECK、FK 全部到位。
  • 全鏈路:App 叫車 → 司機 API 接單→上車→完成(ride #26,車資 8500 分)→ 完成卡「留下評分」是可按的實心按鈕(不再是 disabled 佔位)→ 4 星+評論送出 → DB 交叉驗證 ride_ratings 寫入 (26, customer 8, driver 24, score 4, "GreatDriver-B5") → 完成卡當場翻成 ★★★★☆「已評分」、評分按鈕消失。
  • 四道守門實打(直打 API,App 已不給入口):重複評分 409「此行程已評分過」且 原分數未被覆寫;星等 6 → 400;已取消的行程 → 409;他人的訂單 → 403。
  • 🐛 實跑抓到並修掉:未完成行程的 409 文案是遺失物的(見下方 fix 段)。 單元測試斷言 errors.Is 而非文案,所以測不到——這是 live E2E 的直接產出。
  • 平均分:兩趟分別評 4 星與 5 星 → GET /driver/me 回 rating_avg=4.5, rating_count=2, 司機 App 收入頁顯示「服務評價 4.5 / 5.0(2 則)」,三處(DB/API/UI)完全一致。
  • 順帶驗到 P4 取消文案兩態:乘客主動取消 →「行程已取消。」;派單逾時無人接 → 「抱歉,附近暫無可用司機,請稍後再試。」

🐛 修正:評分被拒的錯誤訊息講的是遺失物協尋(2026-07-27)

RateByCustomer 重用了 lost_item.go 的 ErrRideNotCompleted,其文案是 「僅已完成的行程可申請遺失物協尋」——而它會原樣顯示在乘客的評分對話框上。 兩個功能的條件恰好相同(只有已完成且有司機的行程才適用),所以重用 sentinel 看起來很合理,但面向使用者的文案不是共用的。

修法:新增 ErrRideNotRatable(「僅已完成的行程可以評分」),handler 的 409 對應同步改, 遺失物那條路徑一行不動。測試補「錯誤訊息不得提到遺失物」的斷言, 反向確認改回舊 sentinel 會讓 TestRatingFlow FAIL。 部署到本機 docker compose 後實打複驗:評分回「僅已完成的行程可以評分」、 遺失物端點仍回原本的文案。

⭐ admin 評分可見性(2026-07-27)

B5 上線後評分只有司機自己看得到,admin 端 grep -i rating 零命中—— 營運方看不到任何司機的評價。這與 B5 當初替司機補上「服務評價」是同一個問題的上一層: 資料寫進去了,但該用它做決策的人看不到。

  • RideRatingRepository.SummaryByDrivers ✅ 2026-07-27 一條 GROUP BY 取代逐列查詢——司機列表動輒數十列,每列各打一次 SummaryByDriver 就是 N+1。回傳的 map 只含有評分的司機,沒評分者由呼叫端以零值呈現。
  • GET /admin/drivers 帶 rating_avg/rating_count ✅ 2026-07-27 改回 adminDriverView(內嵌 *model.Driver 讓 JSON 攤平,既有欄位一個不少)。 沒評分的司機一律回 (0, 0) 而非省略欄位:前端據 rating_count 判斷要顯示 「尚無評分」還是分數,缺鍵會讓它多判一種 undefined。 評分查失敗不擋司機列表——那是營運每天在用的主畫面。
  • GET /admin/rides/:id 帶 rating ✅ 2026-07-27 未評分時整個鍵不出現(與乘客端 CustomerRideView.rating 同一約定); 讀取失敗同樣不擋詳情頁。
  • 注入走可選的 SetRatings,未注入時兩處回應形狀不變。

驗收:go build/vet/gofmt 乾淨;新增 TestRatingSummaryByDrivers(真 PostGIS, 含「沒評分的司機不出現在 map 裡」「批次結果與逐列一致」「空清單不爆」)。 docker compose 實打:司機 1 rating_avg=4.5 rating_count=2((5+4)/2)、司機 2 (0, 0); /admin/rides/1 帶評論、/admin/rides/2 空評論、/admin/rides/3(未評分)無 rating 鍵。

admin 端對應:fleet-frontEnd PR #22(司機管理頁評價欄、訂單詳情評分卡)。

🎫 T. App 端實跑回報的後端缺口(2026-07-29 記錄,只剩 T4 待產品拍板)

來源:fleet-app 的搶單/多裝置/弱網三輪 debug(app PR #62–#66)。 這些缺口都是對真後端逐則印 payload 查證出來的,但先前只寫在 App 的 TODO 裡, 後端這份清單上沒有——所以在這裡補記。App 端已各自做了防線, 下面每一項都寫明「後端不改的話,App 只能做到什麼程度」。

已修:

  • ride.stop_updated 只推給乘客(PR #53)。publishStops 的註解假設「司機剛做完動作、 會自己重讀 active」——那句話假設司機只有一台裝置。已改為乘客與司機各推一則。
  • ride.cancelled 從來沒推給司機(PR #56,2026-07-29)。cancelActiveRide 的 「通知司機」只有 line.PushText——App 司機一則 WS 事件都收不到,而司機端沒有輪詢, 行程卡會一直留著:他繼續開往上車點接一個已經取消的乘客,而後端在取消當下就已把他 放回 Idle。這是 PR #52(司機放棄只推 LINE、App 乘客收不到)在司機側的鏡像。
  • ride.picked_up 只推給乘客(PR #57,2026-07-29)。司機第二台裝置/LINE 標記上車後, 這台停在「前往上車點」階段,按鈕按下去只會被後端拒絕、「放棄此單」也已不可用。

這三個洞是同一次盤點抓到的:把 13 個事件型別的實際收件人列成矩陣 (逐一看 s.publish(...) 的 Recipient),再對照 App 兩端的 handler。 三者的共同形狀是「App 端早就寫好處理,後端卻從沒送過」——那段程式碼一直是死碼。 盤點後剩下的兩個非對稱是刻意的:ride.assigned 只給司機(乘客不需要知道派給誰)、 driver.location 只給乘客與 admin(司機不必收自己的位置)。

待處理:

  • T1. 接單/取消失敗回 HTTP 200 + 文案 → 已改成 409(2026-07-30 修)。 AcceptRide 對「已被別人接走」「非待命狀態」回的是 200+{"message":"手慢了…"}, 放棄不成時同樣。後果:App 若只看有沒有丟例外,沒搶到的司機會拿到一張 完整但假的行程卡(他會開去接一個不存在的乘客)。 App 端現行防線是「接單後一律重讀 rides/active、以後端有沒有這張單判定成敗」—— 多打一支 API 才換得到正確性,且逾時時仍要再對帳一次。 改成 409 之後 App 那條退路可以留著(無害),但錯誤處理會單純很多。 改法:新增四個 sentinel error(ErrRideTaken/ErrDriverNotIdle/ ErrRideStarted/ErrRideStateChanged),service 不再回「(訊息, nil)」; readStatusForErr 補上這四個 → 409(先前落到 default 會變 500, 而這些文案是要原樣顯示給使用者的)。文案一字未改——LINE 與 App 都直接顯示它。 LINE webhook 的客戶取消也改成回原文案,不再一律「請稍後再試」 (那會讓人一直重試一件永遠不會成功的事)。 驗收:新增 dispatch_conflict_test.go 三案(已被接走/非待命/狀態已變更)+ 更新既有「已上車不可取消」那案;go test ./internal/handler ./internal/notify 綠。 實跑驗證(本機 server,同 U4 的跑法):重複接單 → 409 {"error":"手慢了,這單已被其他司機接走"}、 已上車後乘客取消 → 409 {"error":"行程已開始,無法取消"};改之前兩者都是 200。
  • T2. 沒搶到的司機收不到任何事件(PR #59,2026-07-29)。一輪 dispatchRound 會把 同一張單同時推給半徑內每一位待命司機,但 ride.accepted 只送給接到的那位—— 其他人的全螢幕接單卡沒有任何東西收得掉,他得自己按下去拿到「手慢了」才會消失, 期間卡片蓋著整個畫面。每一趟車都會發生在所有沒搶到的司機身上。 根因:dispatchRound 的 offered 只是遞迴中的記憶體 map,接單/取消流程拿不到。 改法:Redis 加 ride:<id>:offered(比照既有的 rejected,同 30 分鐘 TTL), pushOffer 時記錄;接單時對「除了接單者以外」的人送新事件 ride.taken,送完清集合。 不能用 ride.cancelled 代替——訂單沒取消,只是不是他的了。
  • T3. 逾時取消(giveUpIfUnaccepted)只通知乘客(PR #59,同批)。 改為對所有收過 offer 的司機送 ride.cancelled(App 端既有處理就能收掉卡片); 乘客/客服在還沒人接單時取消(status=Assigned)先前同樣沒人通知,一併補上。
  • T4.(產品決策)多裝置同帳號。Hub 依 (角色, id) 扇出,每一條連線都收得到事件, 沒有踢舊 session 的機制(JWT 無狀態)。實務影響有兩個: ① 兩台同時上線時位置互相覆蓋(Redis 單一 driver:<id>:loc),派單距離以最後回報的那台為準; ② 要不要「一個帳號只能一台上線」屬產品決策,不該由 App 端片面實作。

📲 U. 乘客端 App 推播的送出路徑(2026-07-30 補上)

來源:fleet-app 第九輪盤點的「候選 1」。App 端已於 fleet-app PR #78 接完線 (登入後 POST /api/customer/device-token、推播只當對帳訊號), 但後端一則都送不出去——notify.Dispatcher 只有 NotifyDriverRideOffer 一個方法。 也就是說 /api/customer/device-token 這支端點從上線那天起,收到的 token 就沒有任何用途。

症狀(改之前):乘客把 App 收到背景 → WS 斷線 → 司機接單/抵達/完成/取消時 手機上完全沒有任何通知,要等他自己再打開 App、輪詢跑一次才知道。 LINE 那條管道有推文字訊息,但那是 LINE 官方帳號的對話,不是 App 通知。

做了什麼:

  • AppPusher 加 SendRideUpdate、Dispatcher 加 NotifyCustomerRideUpdate。 與派單邀請分兩個方法,是為了讓失敗的 log 分得出是哪一條路徑 (派單失敗記在司機那筆、行程更新失敗記在乘客那筆)。 FCMPusher 兩條共用同一段送出邏輯,同樣 Priority=high—— 「司機已抵達」晚到就沒有意義了。
  • 接上五種事件:ride.accepted(接單)、driver.arrived(進圍籬)、 ride.completed(完成)、ride.cancelled(逾時無人接單/他人取消)、 ride.redispatched(司機放棄後重派)。TrackingService 也補了 SetAppNotifier (先前只有 DispatchService 有,抵達與完成這兩則因此送不出去)。
  • 白名單與 App 端對齊(lib/core/push/push_payload.dart 的 _customerPushTypes): App 收到白名單外的 type 直接丟掉,後端多送只是白燒推播額度。 特別不送 driver.location——司機每 8 秒回報一次,拿它推播會把電池與額度燒光。
  • data 只帶 type 與 ride_id:App 把推播只當對帳訊號,醒來後重讀 rides/active。 車資、司機姓名這類會變的欄位一律不放——推播可能延遲數十秒才到, 內容早就過期,直接顯示反而會讓 App 說謊。
  • 乘客自己按的取消不推播:他人就在 App 前景、剛按下去,系統匣再跳一則只是噪音。 admin/系統(逾時)取消才推。

順手修掉的一個洞:checkGeofence 原本是 if err != nil || customerLineID == "" { return }——整個抵達通知(含 WS 事件與審計記錄) 都掛在 LINE ID 查得到與否。現行資料下每位乘客都有 line_user_id(App 註冊也用它當帳號), 所以還沒有人踩到;但這是一顆定時炸彈:哪天有一條建立乘客的路徑沒填它, 司機到了乘客端會完全無聲。已改成「LINE 只是其中一條管道,查不到就只跳過那一條」。

驗收(2026-07-30 實跑):go test ./internal/notify/ 綠; service 層四支整合測試(真 PostGIS + Redis 容器)通過——接單、進圍籬、完成、 admin 取消各驗到一則推播,乘客自己取消驗到沒有推播。 反向確認:把 notifyCustomerRide 改成永遠早退,四支全部 FAIL, 確認斷言吃的是真的送出路徑而不是別的東西。

還缺的一半(不在後端):Firebase 專案憑證(FCM_CREDENTIALS_FILE)。 沒有憑證時走 LogPusher stub——這條路徑照樣可驗(log 印得出要送給誰、送什麼 data), 但手機不會真的響。憑證到位後不必再改程式碼。

U2. 對話訊息推播(2026-07-30,接著同一條地基做)

這是 Phase 2 清單上掛了很久的「聊天訊息 FCM 推播(App 被殺時)」。 對話先前只走 WS:對方 App 一離開前景 WS 就斷了,訊息只會躺在伺服器上, 要等他自己再打開 App 才看得到——「司機到了要聯絡乘客」「乘客回報遺失物」都因此斷線。

  • Dispatcher 加 NotifyDriverRideUpdate(與 NotifyCustomerRideUpdate 共用 notifyRideUpdate,差別只在查哪個角色的裝置)。與 NotifyDriverRideOffer 分開, 是因為用途不同:那支是派單邀請(要開接單卡),這支是行程進行中的通知。
  • ChatService.Send 寫入並發 WS 後,推給收訊那一方:乘客發話推司機、司機發話推乘客。 不推給發話者自己的其他裝置——他知道自己說了什麼,系統匣跳出自己剛送出的訊息 只會讓人以為對方回話了。
  • 訊息內容放通知本文、不放 data(data 仍只有 type+ride_id): 使用者看得到的就是要看內容,但 App 醒來後仍以 REST 重讀對話拿完整歷史, 避免推播裡的那一則與伺服器狀態各說各話。本文以 rune 計截斷 60 字—— 用 byte 截會把中文切成亂碼。
  • 用 context.Background() 而非請求的 ctx:HTTP 回應一送出請求 ctx 就被取消, 推播是回應之後才完成的背景動作,掛在請求 ctx 上會被腰斬。

驗收(2026-07-30 實跑):go test ./internal/service -run TestChatSend_ 三支整合測試 (真 PostGIS + Redis)通過——推給對方而非發話者、尚未指派司機時不推、未注入 notifier 仍能發話;另有 TestPreviewText 釘住 rune 截斷。 反向確認:拿掉 pushToRecipient 呼叫,「推給對方」那支 FAIL(0 則)。

App 端同批:chat.message 進兩端推播白名單、收到時只點亮未讀角標 (推播 data 沒有訊息本體,餵給 RideMessage.fromJson 只會解析失敗被丟掉; 內容等聊天室自己以 REST 補齊)。

U3. 協尋單每一步也推播(2026-07-30)

協尋的節奏是小時級(司機要回車上翻、乘客要等),雙方幾乎都不在 App 前景。 先前每一步都只走 WS,整條流程等於要靠當事人自己想起來去開 App 看—— 建了單司機不知道、找到了乘客不知道、付了款司機不知道。

  • LostItemService 加 SetAppNotifier;建單推司機,之後每一次狀態轉換推給對方 (司機標記尋獲/歸還 → 推乘客;乘客付款/取消 → 推司機)。 動作發起者自己剛按完,系統匣再跳一則只是噪音。
  • 標題講的是「收訊者接下來要做什麼」,不是內部狀態名: found 對乘客是「司機找到你的遺失物了」(=該付處理費了)、 closed 對乘客是「協尋已結案」但對司機是「乘客取消了協尋」—— 同一個狀態對兩邊的意思不一樣,共用一句文案會有一邊看不懂。
  • data 只帶 type+ride_id,內容(物品描述)放通知本文並以 rune 截斷; App 醒來後重讀協尋清單(狀態可能又變過了)。

驗收(2026-07-30 實跑):go test ./internal/service -run 'TestLostItem' —— 整合測試走完 open→found→paid→returned 四步,逐步驗到「推給對方」的標題與 data type; TestLostItemPushTitle 釘住五種標題(含 closed 的兩種說法); 未注入 notifier 仍可建單。

App 端同批:lost_item.created/lost_item.updated 進兩端白名單,收到後只重讀協尋清單 (推播 data 沒有協尋單本體;乘客端也不走「重讀行程」那條——協尋單變了不代表行程變了)。

U5. 一支裝置 token 只能有一位主人(2026-07-30,隱私外洩)

接完三批推播後回頭問一句「推播會不會送錯人」,查出來的洞。

DeviceTokenRepository.Upsert 以 (role, subject_id, token) 為鍵——換人登入時舊列會留著。 FCM/APNs token 是「這台裝置上的這個 App」的識別,換人登入時它不會變; 而 App 在 session 失效(401)那條路徑刻意不呼叫註銷(那支 API 只會再回一次 401, 見 fleet-app 第十一輪)。於是:

A 的 token 過期 → B 在同一台手機登入 → A 的行程通知與對話推播全部送到 B 的手機。 對話推播的本文帶訊息文字,所以這不只是雜訊,是把 A 的私訊顯示在 B 的鎖定畫面上。

  • Upsert 註冊前先刪掉「同一支 token 掛在別人身上」的列(跨角色也算別人)。
  • 不影響一人多裝置:只搬「同一支 token」,其他裝置原封不動。
  • 同一人重複註冊仍是冪等的(App 每次登入都會註冊一次)。

驗收:新增 device_token_integration_test.go 四案(換人移轉/跨角色移轉/重複註冊冪等/ 多裝置不受影響),真 PostGIS 容器跑過。 反向確認:移掉那段刪除,前兩案 FAIL——舊主人身上確實還留著那支 token。

U4. 整條推播鏈路的實跑驗證(2026-07-30,不需 Firebase 憑證)

U/U2/U3 的證據原本都只到 service 層(單元+整合測試)。這一節補的是 整條 HTTP 路徑真的會呼叫送出——沒有憑證時走 LogPusher stub, log 會印出收件裝置的 token 前綴、標題與 data,足以判定「推給誰、推了什麼」。

做法(本機起 postgis+redis 容器、go run ./cmd/server; FCM_CREDENTIALS_FILE 留空 → log 出現「未設定 FCM_CREDENTIALS_FILE,App 推播使用 stub」): 註冊司機/乘客各自的 device token(DRIVER-FCM-TOKEN/CUSTOMER-FCM-TOKEN ——token 前綴就是判斷推給誰的依據),然後用 curl 走完整條鏈路。

實測結果(2026-07-30,10 則推播,收件人全部正確):

動作 推播 data.type 標題 收件裝置
派單 ride.assigned 新派單 #2 DRIVER-F…
司機接單 ride.accepted 司機已接單 CUSTOMER…
進上車圍籬 driver.arrived 司機已抵達 CUSTOMER…
乘客發話 chat.message 乘客傳來訊息 DRIVER-F…
司機發話 chat.message 司機傳來訊息 CUSTOMER…
完成行程 ride.completed 行程已完成 CUSTOMER…
乘客建協尋單 lost_item.created 乘客回報遺失物 DRIVER-F…
司機標記尋獲 lost_item.updated 司機找到你的遺失物了 CUSTOMER…
乘客付處理費 lost_item.updated 乘客已支付處理費 DRIVER-F…
司機標記歸還 lost_item.updated 遺失物已歸還 CUSTOMER…

取消那三條另跑一輪(同日):

  • 乘客自己取消 → 完全沒有推播(只有先前那則派單邀請)——負向斷言成立。
  • admin 取消 → ride.cancelled「行程已取消」給乘客。
  • 司機接單後放棄 → ride.accepted 後緊接 ride.redispatched「正在重新為您派車」給乘客。

踩到的坑(留給下次跑的人):

  1. 本機 Docker 拉不到 registry(load metadata for docker.io/library/golang:1.25-alpine 會卡死), 所以 docker compose up --build 起不來。改用 docker compose up -d postgis redis +本機 go run ./cmd/server(DB_HOST=localhost DB_PORT=5433)——postgis/redis 映像本機已有。
  2. PUT /api/driver/vehicle 的車牌有長度上限,拿 epoch 當後綴會被 400「車牌格式錯誤」擋下。
  3. POST /api/admin/drivers/:id/vehicle-review 的參數是 {"approve":true},不是 {"status":"approved"}。
  4. POST /api/rides 回的是 ride_id 不是 id。

仍未做:真 Firebase 憑證下的端到端(手機真的響),那是 A2 的同一個卡點。


🚦 V. 後台強制取消的狀態衝突回 500(2026-07-30,admin 盤點時抓到)

起因:admin 那側在盤點「寫入其實成功卻報失敗」的畫面 (見 line-fleet-admin/docs/TODO.md), 追到後端這支的錯誤分類上。

問題:AdminHandler.CancelRide 只把 ErrNotFound 判 404,其餘一律 500。 於是兩種後台每天都會遇到的正常情況都變成「伺服器錯誤」:

情境 錯誤 原本 現在
已上車的訂單(確認對話框自己就寫著這句) ErrRideStarted 500 409
上一次其實已經取消成功(回應遺失後又按一次) ErrRideStateChanged 500 409
找不到訂單 ErrNotFound 404 404(不變)

乘客端的 readStatusForErr 從 T1 起就把這一族判 409 並寫明理由,admin 這支是漏網的。

為什麼不是只換個數字:500 有兩個實際後果——監控把例行操作當成伺服器故障; 而前端無從分辨「伺服器壞了」與「這件事已經生效了,重讀一次就對了」, 後者正是 admin 該自動重新整理的訊號(admin PR 那側就是靠 409 做這件事)。

驗收:抽出 adminCancelStatus(err) 純函式 + 5 案表格測試(含「包過一層仍要成立」)。 反向確認:把 409 改回 500 → 只有那兩案 FAIL。 gofmt/go vet/go build 乾淨。 真後端實跑:已取消的 #30 再取消 → 409;已上車的 #31 → 409 行程已開始,無法取消; 不存在的 #999999 → 404(沒有連帶改壞)。


🗓️ W. 預約行程+常用地點(2026-07-31,跨端新功能)

需求:乘客可預約未來的用車,以及存下住家/公司等常去的地點供叫車與預約一鍵帶入。 App 端對應 line-fleet-app PR #95。

W1. 兩張新表(migration 000025/000026)

  • customer_saved_places:kind(home/work/custom)+label/address/point。 home/work 每人各限一筆(部分唯一索引 uq_saved_place_customer_kind),服務層為 upsert 語意——「設定住家」該把住家換成新地址,不是回一句「你已經有住家了」。
  • scheduled_rides:scheduled_at+起訖點+status(pending/dispatched/cancelled/failed) +ride_id(轉單後指向真訂單)+attempt_count/last_error。

為什麼不是在 rides 加一個 scheduled 狀態:rides 的查詢散布在派單池 (status='requested')、乘客 active、歷史、報表、admin 訂單列表——多塞一個「還不該被派單」 的狀態進去,得逐一稽核每支查詢有沒有排除它,漏一支就是「司機看到一張三天後的單」。 獨立表對既有路徑是純新增、零風險。

W2. 到點轉單(ScheduledRideDispatcher)

每 30 秒掃一次,把約定時間前 15 分鐘(ScheduledRideLeadMinutes)內的 pending 轉成真訂單。 轉單走的是與手動叫車完全同一支 RideService.CreateByCustomer——派單、審計、車種驗證、 「同時只能有一張進行中訂單」全部自動沿用。另寫一份建單邏輯的話,兩條路徑遲早長歪, 而且是預約那條先歪(沒人在旁邊看著)。

機制 防的是什麼
認領帶 attempt_count 樂觀鎖 多副本同時掃到同一筆 → 建出兩張要付錢的訂單
暫時性失敗維持 pending(上限 10 次) 乘客當下還在另一趟行程上,那是「等下一輪」不是「永久失敗」
永久性失敗立刻判死 座標/車種無效重試幾次都一樣,佔著額度只會讓乘客到約定時間才發現沒車
過期 30 分鐘就作廢(ScheduledRideExpiryGraceMinutes) 停機後重啟會把積壓的過期預約全部派車(見 W4)

W3. 端點(皆掛 customerAuthed)

GET/POST      /api/customer/places
PUT/DELETE    /api/customer/places/:id
GET/POST      /api/customer/scheduled-rides        # ?upcoming=1 只回未轉單;回應帶 lead_minutes
GET           /api/customer/scheduled-rides/:id
POST          /api/customer/scheduled-rides/:id/cancel

取消已轉單的回 409+該筆現況(不是單純的錯誤):那張真訂單已經在派單池裡, 司機可能正在開過來——App 要據此把畫面切成「已為你派車」並引導去取消訂單, 而不是顯示「取消失敗,請稍後再試」(同一個病在 V 那章的 admin 端抓過一次)。

W4. 本批 debug 抓到的:停機後會把積壓的過期預約全部派車

FindDue 原本只有上界沒有下界。部署/當機/DB 不可用停了一段時間,重啟時 昨天早上的預約會今天下午開一台車到乘客家樓下,而且他還得付那趟錢。 修法是超過約定時間 30 分鐘就標 failed 並寫原因——標 failed 而不是留在 pending, 是因為留著它會永遠掛在乘客的「即將到來」,而那台車永遠不會來。 先寫 TestDispatcherSkipsLongExpiredSchedules 取證看到它真的被轉單,才動手修。

W5. 假資料

scripts/seed_demo_data.sh(示範乘客 demo-customer-1/demo123456)。 主路徑刻意走真實 HTTP API 而不是直接寫 DB——塞資料的同時就端到端驗過了那些端點, 不會塞出一份「只有 SQL 造得出來、API 其實不接受」的資料。 只有 dispatched/failed 非走 SQL 不可(排程器到點後才會產生,沒有 API 建得出來)。

W6. 驗收

go build/go vet 乾淨;internal/service 完整套件 172 支全過、0 失敗 (ok ... 2911.952s,真 PostGIS 容器,本機跑了 48 分鐘)——那一跑含這批的 16 支。 之後又補了 2 支上限測試(TestScheduledRideLimit/TestSavedPlaceLimit,單獨跑過 PASS), 所以現在 internal/service 共 174 支、這批貢獻 18 支。 internal/handler 完整套件也綠(136s)。另加 scheduled_ride_route_shape_test.go——新路由與既有 /customer/rides/:id 同層混用 靜態段與參數段,gin 的路由衝突是註冊當下 panic:服務起不來但單元測試照樣全綠。

反向驗證做了三次,其中兩次推翻了自己的假設: 拔掉 FindDue 的時間條件 → TestDispatcherOnlyPicksDueSchedules 轉紅 ✅; 拔掉樂觀鎖 → TestDispatcherIsIdempotent 仍然綠(它守的是循序重跑,第一輪改了狀態 第二輪就撈不到,壓根沒走到認領那行);補的併發測試第一版也是假的(兩個 goroutine 各跑一次 Tick,先跑完的已改狀態,拔掉樂觀鎖連跑三次都綠), 改成餵兩份 attempt_count=0 的相同快照直接進 dispatchOne 才造得出真重疊 ✅。

W6-1. 到點轉單的真環境實跑(2026-07-31,本機後端+PostGIS)

不只有測試,整條在跑著的服務上驗過一次。塞一筆 5 分鐘後到點的預約(id=7), 排程器每 30 秒一輪,觀察到的軌跡:

輪次 attempt_count 結果
1–2 1 → 2 撈到並認領,建單被 已有進行中的訂單 擋下 → 維持 pending、寫 last_error、等下一輪
3(把擋路的示範訂單結掉之後) 3 轉單成功:status=dispatched、ride_id=39、last_error 清空

交叉驗證訂單 39:pickup_address/dropoff_address 正是預約上填的那兩個字串, status=0(requested,已進派單池)。

這一跑同時證明了三件本來只有測試層證據的事:到期條件真的撈得到、 暫時性失敗真的是「等下一輪」而不是判死、以及成功後 last_error 真的會被清掉。 順帶驗到 gin 路由沒有 panic(服務起得來),那是單元測試照樣全綠的失敗模式。

W7. 這批沒做的(寫明條件)

  • 預約不支援多停靠點:需要另一張 stops 快照表,而「預約一趟多人共乘」的需求還沒出現。
  • 預約沒有專屬推播:轉單後走既有 ride 推播鏈路(「司機接單了」照樣會通知), 缺的是「你的預約已轉為訂單」與「預約失敗」這兩則本身。 條件:等 failed 真的在生產環境發生過再決定值不值得。
  • admin 看不到預約:表與 API 都在,admin UI 沒做。等營運說得出要對預約做什麼再開。
  • 司機端不知道自己接的是預約單(自審時發現,本批刻意沒做):轉單後就是一張普通訂單, 司機看不到「約定上車時間」。提前量 15 分鐘下多半剛好,但司機若 5 分鐘就到, 乘客可能還沒下樓,而司機不知道該等。要做的話動的是 rides (帶 scheduled_at 或來源標記)+司機端顯示,屬功能擴充不是 bug,故沒夾帶進這批。 條件:等實際跑過幾趟預約單、司機真的回報「到太早不知道要不要等」再做。

下次任務

🎯 2026-07-31 這一輪(W. 預約行程+常用地點)——開工先看這段

跨端新功能,不是 debug 輪:兩張新表(migration 000025/000026)、9 支端點、 一支到點轉單的背景排程器。PR #70 + App 端 fleet-app #95。 決策理由與三次反向驗證的結果見上方 W 章。

這一輪學到的兩條:

  1. 綠燈的測試不等於守得住的測試。名字叫 TestDispatcherIsIdempotent 的那支, 把認領的樂觀鎖整個拔掉照樣綠(它守的是循序重跑,壓根沒走到認領那行); 補的併發測試第一版也是假的(兩個 goroutine 沒真重疊)。 判準:把防線拔掉,測試會不會紅——不會紅的那支,它的名字在說謊。 競態測試還要多問:重疊是造出來的,還是碰運氣?
  2. 本機跑 go test ./... 跑不完(internal/service 有 172 支、每支起一個 PostGIS 容器,約一小時)。要驗改動請跑受影響的 package,別跑全部—— 這條先前記在坑卡上,這一輪再次踩到(等了 90 分鐘才發現它只是慢不是卡)。 CI 那支 build-and-unit-test 只花 1 分鐘,是因為 CI 環境跳過 testcontainers, 它綠不代表整合測試綠。

➡️ 下一輪候選(都寫明了條件,別提前做):

  1. 預約的通知缺口——轉單後走既有 ride 推播鏈路(「司機接單了」會通知), 但「你的預約已轉為訂單」與「預約失敗」這兩則本身沒有。 條件:等 failed 真的在生產環境發生過。
  2. admin 端看不到預約——表與 API 都在,UI 沒做。 條件:等營運說得出要對預約做什麼(強制取消?改時間?)。
  3. 司機端不知道自己接的是預約單(自審發現)——見 W7。 條件:等司機真的回報「到太早不知道要不要等」。

🎯 2026-07-30 這一輪做完了什麼(開工先看這段)

主題是「推播這條通道從頭到尾打通」,五支 PR 全部合併進 main:

PR 內容 章節
#61 乘客端行程狀態推播的送出路徑(先前只有司機派單那一條) U
#62 對話訊息推播給收訊那一方 U2
#63 協尋單每一步推播給對方 U3
#64 接單/取消失敗改回 409(先前 200+文案) T1
#65 一支裝置 token 只能有一位主人(換人登入的隱私外洩) U5

App 端同批:fleet-app #79(冷啟動推播補送)/#80(對話)/#81(協尋)+三支文件 PR。

➡️ 下一步只剩一個外部卡點:Firebase 憑證(FCM_CREDENTIALS_FILE)。 憑證放進來後不需要再改任何程式碼——沒有憑證時走 LogPusher stub, 送出路徑已用真服務逐則驗過(見 U4 的表)。憑證到位那天要驗的是: 司機端「App 被殺 → 點推播 → 接單卡」、乘客端「App 被殺 → 點推播 → 畫面已是最新狀態」。

想繼續推進、又不解憑證卡點的話,剩下的候選(依價值排序):

  1. T4 多裝置同帳號(產品決策:要不要一個帳號只能一台上線)——需要你拍板。
  2. /metrics(P4 #20):目前沒有任何可觀測性;上線前遲早要做,但沒有使用者可見價值。
  3. GET /api/driver/rides(P4 #18):司機歷史逐趟明細(收入面已由 earnings 涵蓋)。
  4. 對話/協尋的推播節流:目前每則訊息都推一次。等真的有量再說—— 現在做只是猜。

這一輪學到、值得記住的兩條:

  • 通道清單要問的不是「WS 送了嗎」,而是「他現在如果沒開著 App,會知道嗎?」 (反過來也要問「這則需要吵他嗎」——driver.location 每 8 秒一則就不該推)。
  • 補完通道後要接著問「送對人了嗎」——U5 那個隱私洞就是這樣查出來的, 而且它是新功能帶進來的新風險:推播管道打通之前,那張表寫錯沒有可觀察的後果。

新需求(2026-07-16 加入,尚未實作,皆需後端地基先行):

  • N. 多乘客/多停靠點行程:一張訂單最多 5 位乘客各自上下車+中斷點;司機端同步收到全程。 車資已拍板(2026-07-16):全程實際路線含繞路(N5)——需擴充 OSRM client 支援多 waypoint (現行介面寫死兩點)並讓 haversine 退路逐段累加。

  • O. 司機車輛資訊/寵物車清潔費:車種選單(轎車/休旅/七人座/無障礙/寵物用車)+車牌; 司機沒填不得接單(後端 gate+App 強制跳轉,不設寬限期);乘客端顯示車種車牌與司機聯絡方式; rides 落車輛快照;寵物車加收清潔費(上限 30%,DB CHECK 釘住)。 寵物車加收觸發條件已拍板(2026-07-16):依乘客指定車種 → 衍生 P. 乘客指定車種 (叫車 API 帶車種、派單依車種過濾、找不到車種的行為、乘客端加價說明)。 P4/P5 已拍板(2026-07-16):不降級(取消時明確說是車種問題,payload 帶 cancel_reason)、 新增 GET /api/customer/fees(白名單輸出,不外洩手續費/月會費)。 ✅ 2026-07-16 待拍板全數定案(乘客數 5 位各自上下車/車種選單/強制填寫無寬限/車輛快照/ 清潔費依乘客指定車種、上限 30%、不計入抽成/不降級+取消原因明確化/customer fees 端點/ 電話明碼、僅該趟乘客可見)——N、O、P 規格完備,可開始實作, 建議順序:O1→O2→O3(車輛地基)→ P1→P2→P3+P4(車種)→ O6+P5(清潔費)→ O4/O7(乘客可見)→ N(多停靠點,最大塊)。 **進度:N1–N7 ✅、O1/O2/O3/O4/O6/O7 ✅、P1–P5 ✅ (O1 為 2026-07-16,其餘皆 2026-07-17) → N、O、P 三章全數完成,只剩 O5(admin 呈現/審核,可選、待拍板)。

    後端能力已到位:司機填車輛才能接單 → 乘客指定車種(可帶多乘客/多停靠點)→ 只派同車種、找不到明確取消 → 司機看得到全程、可標記到站/跳過 → 完成時依全程實際路線(排除已跳過)計費、依乘客指定車種加收清潔費、報表分項 → 乘客看得到車種車牌與司機電話、對話無時間限制。

    下一項建議:補下游 UI——後端已跑在兩端前面很遠,做完的能力在 admin 與 App 都還看不到:

    • admin:費率頁 pet_cleaning_fee_bps、月報表清潔費分項欄、(O5 若要做)車輛審核。
    • App(見 line-fleet-app/docs/TODO.md): 司機車輛設定頁+強制跳轉、乘客端車種選擇+清潔費預告、完成卡分項、 司機收入頁等式改「營業額 − 手續費 + 清潔費 = 實得」、多停靠點編輯與司機端全程顯示。

    其餘後端項目:O5(待拍板);N 的衍生風險——乘客建單時看不到預估車資 (繞路越多車資越高),若要「先報價」需要一支以全程路線試算的報價 API,目前沒有。**

計費地基 F1–F8+F3 里程退路+F9-1~F9-6+M 整數台幣 已全數合併進 main,三端對帳與 F3/F9-3/F9-4 皆 docker E2E 驗過。 其餘皆屬「量體上升後才需」的大資料量最佳化,勿過早做:

  1. 協尋/對話 Phase 2 剩餘:遺失物處理費真金流(目前記帳式確認)。 聊天訊息 FCM 推播(App 被殺時) ✅ 2026-07-30 完成,見 U2。 admin 協尋單總覽+對話稽核 UI ✅ 2026-07-15 (後端 H4 GET /api/admin/lost-items+前端 fleet-frontEnd#11)。
  2. F9-7 rides 月分割:量體達千萬級時依 completed_at 做 declarative partitioning。
  3. drivers/membership 真分頁:逼近 MaxListRows=5000 上限時,比照 rides 改 offset/keyset 伺服器端分頁(含前端)。
  4. F3 強化(可選):軌跡稀疏偵測目前用「軌跡 vs 路線取大者」,是否再加「後台手動校正單筆車資」待產品定。

驗收前先 EXPLAIN ANALYZE 灌 50~100 萬筆確認走索引範圍掃描(見上「驗收方式」)。Git 走 PR(main 受保護 enforce_admins: true)。

參考