建立:2026-07-11。以程式碼實測為準。 本檔專收「後端待辦」;總體階段規劃見 roadmap.md、API 缺口見 backend-api-gaps.md。 每完成一項:實跑驗收 → 勾選回填 → 走 PR(main 受保護,
enforce_admins: true,不可直推)。
需求:後台可設「手續費%數」,並在報表顯示司機營業狀況(營業額)、應付總公司金額, 以及車隊會費的計算與收取。跨三專案,本區塊為後端地基,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(migration000011)✅ 單列表(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✅(migration000013) 表: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 JOINmembership_invoices讀帳本快照(repository.goMonthlyDriverStats/DriverMonthlyEarnings), 未產生帳單者會費為 0(尚未入帳=尚未應付)。與車資/手續費的快照心智模型一致,三端(F6=F7=帳本)恆等、不受費率調整影響。
報表是全表聚合(
SUM/GROUP BYoverrides),是最先被資料量拖垮的地方。 前置盤點: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轉型); migration000012建idx_rides_status_completed(status, completed_at)與idx_rides_driver_completed(driver_id, completed_at)。 > 待補:以造數腳本灌 50~100 萬筆做EXPLAIN ANALYZE,確認實走索引範圍掃描(見驗收)。 -
F9-2. 加總型別防溢位 ✅ 報表金額加總與里程加總一律
::bigint/Goint64; 金額欄位本身BIGINT(存分)。DailyDriverReport.TotalDistanceM由int改int64。 -
F9-3. 預聚合彙總表
daily_driver_earnings✅(2026-07-13) 表(migration000014):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.Completebest-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_timeoutruntime 參數 (pgx 於每條連線建立時套用;migrations 走MigrateDSN不受影響),啟動時SHOW statement_timeout記 log 確認。 驗收:單元測試(parseRideListFilter 區間上限/邊界、config DSN 含/不含 timeout、MigrateDSN 不受影響); docker E2E:啟動 logstatement_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_settingsseed 一筆。 - 大資料量:以造數腳本灌入
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)逐欄渲染相同 → 三端金額對齊。
- 里程準確度:計費綁 GPS 軌跡里程,軌跡稀疏會少算——已補 OSRM pickup→dropoff 路線里程退路(F3,2026-07-12),
計費里程取軌跡與路線大者;
min_fare仍是最後地板。是否再加「後台可手動校正單筆車資」待定。 - 費率調整時機:快照制 → 改費率只影響之後的行程,歷史不變(刻意)。
- 會費落帳:F6 先即時算,不管已繳/未繳;要狀態管理再開 F8。
- 取消行程不計費:只有
COMPLETED計車資與手續費。 - 大資料量:報表聚合是最先被拖垮處,預防措施見上「大資料量預防措施(DB scale)」
F9-1~F9-7;
daily_driver_earnings彙總表與 rides 月分割屬「量體上升後」啟用,勿過早最佳化。
需求:會員(乘客)與司機即時對話(WebSocket 推播,非留言板);乘客弄丟東西可對 已完成行程建協尋單聯絡司機,並支付「找回處理費」——費用=該趟車資 × 處理費%, % 由後台費率設定頁調整(
lost_item_fee_bps),金額於建單當下快照(同車資快照制)。
- H1. 行程內對話(migration
000015ride_messages)ChatService:訊息持久化後經 WS Hub 即時推chat.message給行程雙方;GET/POST /api/rides/:id/messages(MultiAuth——本趟乘客/司機可發話、admin 唯讀稽核;after參數供斷線重連補漏)。長度限制 500 rune(DB CHECK ≤1000 為最後防線)。 - H2. 遺失物協尋(migration
000016lost_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.ListAllJOIN 司機/乘客姓名、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總覽頁+訂單詳情對話稽核卡)。
使用者回報(2026-07-15):台幣沒有小數點,支付無法用小數。曾出現
NT$21.03、NT$17.96這種不可支付金額。 已定案並實作:採 A 模型(維持存「分」但金額一律落在整數元,分為 100 的倍數);手續費無條件捨去、 車資與遺失物處理費四捨五入。 三端全鏈路已改(後端計算+前端顯示),詳見下方「實作結果」。
問題根源(現況):
fee_settings.goQuote():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、applib/core/util/money.dart都做「分→NT$XX.XX(兩位小數)」。
已定案的決策(2026-07-15,使用者拍板):
- 金額模型 → A:維持存「分」但所有計算/收費/顯示一律落在整數元(金額恆為 100 的倍數,schema 不動)。
- 進位規則:手續費無條件捨去(利司機)、車資與遺失物處理費四捨五入。
- 快照一致性:費率快照制已保護歷史;改規則只影響日後新行程/新帳單,未回算歷史(沿用既有心智模型)。
影響範圍(三端全鏈路):
- 後端(dispatch):
fee_settings.goQuote()/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/TestLostItemFlowfixture 改整數元、皆綠。 會費(固定設定值)與報表(加總已定格的整數元)本就整數,無需改。 - 前端:admin
money.ts、appmoney.dart顯示改整數元、不帶小數點(防禦性四捨五入);admin 費率頁金額欄位precision=0(%欄位維持 2 位)。相關測試斷言全部改整數元。admin 102 tests、app 73 tests 綠。 - 待做(未涵蓋):真金流付款目前仍是記帳式確認(無金流),金額已是整數元、可直接收;若日後接金流沿用即可。
對應前端:line-fleet-admin/docs/TODO.md、line-fleet-app/docs/TODO.md。
需求(使用者 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,migration000021)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.acceptedpayload 加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.goComplete)**實作內容**: 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。
車資算法✅ 已拍板(2026-07-16):採全程實際路線(含繞路),見 N5。 衍生風險:乘客建單時看不到預估車資,繞路越多車資越高 → 若日後要「先報價」, 需要一支報價 API(以全程路線試算),目前沒有(後端只在完成時定格計費)。狀態機✅ 已拍板(2026-07-17):維持單一picked_up=第一位乘客上車, 其餘乘客不另計行程狀態。理由:F 系列報表、tracking 里程起點、已打通的三端對帳全部不受影響;ride_stops.arrived_at(N1 已含)保留為日後要精確化時的升級路徑。 已知取捨:「行程中」會涵蓋「尚未接到後續乘客」的區段。上限 5 位✅ 已拍板(2026-07-16):5 位「乘客」,各自上下車 → 最多 10 個停靠點。取消/缺席✅ 已拍板(2026-07-17):司機可標記跳過(乘客沒出現時)。 → N7 因此從「可選」變成必要:ride_stops需要狀態欄(arrived_at/skipped_at) 與司機端標記 API。 對車資的影響(實作推論,非另行拍板):跳過的停靠點不計入 N5 的計費路線—— N5 的精神是「司機真的開了那些路,繞路不該做白工」;沒去的站就沒開那段路, 計入等於收乘客沒走的路的錢。軌跡那側本來就自然反映(沒去就沒軌跡),billableDistanceM取大者的邏輯不變。- admin 呈現:訂單詳情要顯示多個 stops 與軌跡(
line-fleet-admin對應項)。
需求(使用者 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,migration000017)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.acceptedpayload(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(改車一律重審); adminPOST /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)本來就共用同一條對話。 需確認:行程完成很久之後乘客仍能發話(目前授權是「本趟乘客/司機」,看起來可以, **實作前要寫一個測試釘住這個行為**)。
-
車種自由文字 vs 選單✅ 已拍板:選單(轎車/休旅/七人座/無障礙/寵物用車),見 O1。 -
車牌格式驗證(O2 要面對,O1 不管格式):台灣車牌格式多樣(舊式/新式/機車/電動車), 過嚴會擋到真司機。建議寬鬆格式 + 後台可修正。O1 的 DB 層只保證唯一性,不驗格式。
-
既有司機資料✅ 已拍板:強制填寫、不設寬限期,App 端強制跳轉引導,見 O3。 營運提醒:上線當下所有司機都會無法接單,需事前通知。 -
車輛異動✅ 已拍板:rides 落車輛快照+開放司機聯絡方式+沿用既有 chat 當留言板,見 O7。 -
寵物車加收的觸發條件✅ 已拍板(2026-07-16):(b) 乘客叫車時指定車種 → 衍生出一整塊新功能,獨立成 P. 乘客指定車種(叫車帶車種、派單依車種過濾、乘客端選擇 UI)。 清潔費依rides.required_vehicle_type == 'pet'觸發,與司機車種無關。 -
手續費/營業額基準✅ 已拍板(2026-07-16):清潔費不計入抽成, 全額歸司機;報表分項顯示、營業額不含清潔費,見 O6 計算段。 -
司機電話的隱私✅ 已拍板(2026-07-16):明碼、僅該趟乘客可見(沿用 MultiAuth), 見 O7。已知取捨:行程結束後仍可撥打;出現騷擾案例再升級遮罩/轉接(只動呈現層)。
由 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,migration000018) 值域同 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%)」。
降級策略✅ 已拍板(2026-07-16):不降級——找不到指定車種就明確取消並說明原因,見 P4。- 車種供給:若車隊裡沒有任何寵物車司機,這個選項在乘客端要不要隱藏/停用? 需要「有哪些車種目前可用」的查詢(可由 redis 在線司機 + 車種聚合,但會增加派單前的查詢成本)。
乘客可讀的費率 API✅ 已拍板(2026-07-16):做GET /api/customer/fees, 白名單輸出(handler 另建 struct,非過濾 admin response),見 P5。- 與 N(多停靠點)的交互:多乘客行程若指定寵物車,清潔費仍只加一次(依 ride 而非依乘客)—— 實作時要釘住這個語意。
起因:盤點三端程式碼(不只看勾選)發現後端有三個洞——兩個讓 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 同批)。
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.go8 案(單點/多停靠點全程入路線/寵物清潔費/ 缺目的地 400/非法車種/min_fare 下限/未成對停靠點/未就緒)+internal/handler/estimate_test.go2 案(授權 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(軌跡, 路線),故「實際依行駛路線可能不同」的免責成立。
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-27ride_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-27service.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 JOINride_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.go3 案(主流程+四道守門與 trim/平均分含無評分 (0,0)/ 訂單視圖與歷史列表讀回,真 PostGIS 跑全部 migration,順帶驗證 000023 本身可套用)+internal/handler/rating_test.go2 案(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 取消文案兩態:乘客主動取消 →「行程已取消。」;派單逾時無人接 → 「抱歉,附近暫無可用司機,請稍後再試。」
RateByCustomer 重用了 lost_item.go 的 ErrRideNotCompleted,其文案是
「僅已完成的行程可申請遺失物協尋」——而它會原樣顯示在乘客的評分對話框上。
兩個功能的條件恰好相同(只有已完成且有司機的行程才適用),所以重用 sentinel
看起來很合理,但面向使用者的文案不是共用的。
修法:新增 ErrRideNotRatable(「僅已完成的行程可以評分」),handler 的 409 對應同步改,
遺失物那條路徑一行不動。測試補「錯誤訊息不得提到遺失物」的斷言,
反向確認改回舊 sentinel 會讓 TestRatingFlow FAIL。
部署到本機 docker compose 後實打複驗:評分回「僅已完成的行程可以評分」、
遺失物端點仍回原本的文案。
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(司機管理頁評價欄、訂單詳情評分卡)。
來源: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 端片面實作。
來源: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),
但手機不會真的響。憑證到位後不必再改程式碼。
這是 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 補齊)。
協尋的節奏是小時級(司機要回車上翻、乘客要等),雙方幾乎都不在 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 沒有協尋單本體;乘客端也不走「重讀行程」那條——協尋單變了不代表行程變了)。
接完三批推播後回頭問一句「推播會不會送錯人」,查出來的洞。
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。
U/U2/U3 的證據原本都只到 service 層(單元+整合測試)。這一節補的是 整條 HTTP 路徑真的會呼叫送出——沒有憑證時走
LogPusherstub, 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「正在重新為您派車」給乘客。
踩到的坑(留給下次跑的人):
- 本機 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 映像本機已有。 PUT /api/driver/vehicle的車牌有長度上限,拿 epoch 當後綴會被 400「車牌格式錯誤」擋下。POST /api/admin/drivers/:id/vehicle-review的參數是{"approve":true},不是{"status":"approved"}。POST /api/rides回的是ride_id不是id。
仍未做:真 Firebase 憑證下的端到端(手機真的響),那是 A2 的同一個卡點。
起因: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(沒有連帶改壞)。
需求:乘客可預約未來的用車,以及存下住家/公司等常去的地點供叫車與預約一鍵帶入。 App 端對應 line-fleet-app PR #95。
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 訂單列表——多塞一個「還不該被派單」
的狀態進去,得逐一稽核每支查詢有沒有排除它,漏一支就是「司機看到一張三天後的單」。
獨立表對既有路徑是純新增、零風險。
每 30 秒掃一次,把約定時間前 15 分鐘(ScheduledRideLeadMinutes)內的 pending 轉成真訂單。
轉單走的是與手動叫車完全同一支 RideService.CreateByCustomer——派單、審計、車種驗證、
「同時只能有一張進行中訂單」全部自動沿用。另寫一份建單邏輯的話,兩條路徑遲早長歪,
而且是預約那條先歪(沒人在旁邊看著)。
| 機制 | 防的是什麼 |
|---|---|
認領帶 attempt_count 樂觀鎖 |
多副本同時掃到同一筆 → 建出兩張要付錢的訂單 |
| 暫時性失敗維持 pending(上限 10 次) | 乘客當下還在另一趟行程上,那是「等下一輪」不是「永久失敗」 |
| 永久性失敗立刻判死 | 座標/車種無效重試幾次都一樣,佔著額度只會讓乘客到約定時間才發現沒車 |
過期 30 分鐘就作廢(ScheduledRideExpiryGraceMinutes) |
停機後重啟會把積壓的過期預約全部派車(見 W4) |
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 端抓過一次)。
FindDue 原本只有上界沒有下界。部署/當機/DB 不可用停了一段時間,重啟時
昨天早上的預約會今天下午開一台車到乘客家樓下,而且他還得付那趟錢。
修法是超過約定時間 30 分鐘就標 failed 並寫原因——標 failed 而不是留在 pending,
是因為留著它會永遠掛在乘客的「即將到來」,而那台車永遠不會來。
先寫 TestDispatcherSkipsLongExpiredSchedules 取證看到它真的被轉單,才動手修。
scripts/seed_demo_data.sh(示範乘客 demo-customer-1/demo123456)。
主路徑刻意走真實 HTTP API 而不是直接寫 DB——塞資料的同時就端到端驗過了那些端點,
不會塞出一份「只有 SQL 造得出來、API 其實不接受」的資料。
只有 dispatched/failed 非走 SQL 不可(排程器到點後才會產生,沒有 API 建得出來)。
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 才造得出真重疊 ✅。
不只有測試,整條在跑著的服務上驗過一次。塞一筆 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(服務起得來),那是單元測試照樣全綠的失敗模式。
- 預約不支援多停靠點:需要另一張 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 章。
這一輪學到的兩條:
- 綠燈的測試不等於守得住的測試。名字叫
TestDispatcherIsIdempotent的那支, 把認領的樂觀鎖整個拔掉照樣綠(它守的是循序重跑,壓根沒走到認領那行); 補的併發測試第一版也是假的(兩個 goroutine 沒真重疊)。 判準:把防線拔掉,測試會不會紅——不會紅的那支,它的名字在說謊。 競態測試還要多問:重疊是造出來的,還是碰運氣?- 本機跑
go test ./...跑不完(internal/service有 172 支、每支起一個 PostGIS 容器,約一小時)。要驗改動請跑受影響的 package,別跑全部—— 這條先前記在坑卡上,這一輪再次踩到(等了 90 分鐘才發現它只是慢不是卡)。 CI 那支build-and-unit-test只花 1 分鐘,是因為 CI 環境跳過 testcontainers, 它綠不代表整合測試綠。➡️ 下一輪候選(都寫明了條件,別提前做):
- 預約的通知缺口——轉單後走既有 ride 推播鏈路(「司機接單了」會通知), 但「你的預約已轉為訂單」與「預約失敗」這兩則本身沒有。 條件:等
failed真的在生產環境發生過。- admin 端看不到預約——表與 API 都在,UI 沒做。 條件:等營運說得出要對預約做什麼(強制取消?改時間?)。
- 司機端不知道自己接的是預約單(自審發現)——見 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)。 憑證放進來後不需要再改任何程式碼——沒有憑證時走LogPusherstub, 送出路徑已用真服務逐則驗過(見 U4 的表)。憑證到位那天要驗的是: 司機端「App 被殺 → 點推播 → 接單卡」、乘客端「App 被殺 → 點推播 → 畫面已是最新狀態」。想繼續推進、又不解憑證卡點的話,剩下的候選(依價值排序):
- T4 多裝置同帳號(產品決策:要不要一個帳號只能一台上線)——需要你拍板。
/metrics(P4 #20):目前沒有任何可觀測性;上線前遲早要做,但沒有使用者可見價值。GET /api/driver/rides(P4 #18):司機歷史逐趟明細(收入面已由 earnings 涵蓋)。- 對話/協尋的推播節流:目前每則訊息都推一次。等真的有量再說—— 現在做只是猜。
這一輪學到、值得記住的兩條:
- 通道清單要問的不是「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,目前沒有。**
- admin:費率頁
計費地基 F1–F8+F3 里程退路+F9-1~F9-6+M 整數台幣 已全數合併進 main,三端對帳與 F3/F9-3/F9-4 皆 docker E2E 驗過。 其餘皆屬「量體上升後才需」的大資料量最佳化,勿過早做:
- 協尋/對話 Phase 2 剩餘:遺失物處理費真金流(目前記帳式確認)。
聊天訊息 FCM 推播(App 被殺時)✅ 2026-07-30 完成,見 U2。admin 協尋單總覽+對話稽核 UI✅ 2026-07-15 (後端 H4GET /api/admin/lost-items+前端 fleet-frontEnd#11)。 - F9-7 rides 月分割:量體達千萬級時依
completed_at做 declarative partitioning。 - drivers/membership 真分頁:逼近
MaxListRows=5000上限時,比照 rides 改 offset/keyset 伺服器端分頁(含前端)。 - F3 強化(可選):軌跡稀疏偵測目前用「軌跡 vs 路線取大者」,是否再加「後台手動校正單筆車資」待產品定。
驗收前先 EXPLAIN ANALYZE 灌 50~100 萬筆確認走索引範圍掃描(見上「驗收方式」)。Git 走 PR(main 受保護 enforce_admins: true)。
- 總體階段規劃:roadmap.md(資料模型彙總已預留
fares/fare_rules/payments) - 後端 API 缺口:backend-api-gaps.md
- 前台對應:line-fleet-admin/docs/TODO.md「手續費/會費/營運報表」
- App 對應:line-fleet-app/docs/TODO.md「手續費/會費/司機收入」