Skip to content

feat(N1-N3): 多乘客/多停靠點——ride_stops 表、配對驗證、建單 API - #33

Merged
thothawei merged 1 commit into
mainfrom
claude/n1-n3-ride-stops
Jul 17, 2026
Merged

thothawei merged 1 commit into
mainfrom
claude/n1-n3-ride-stops

Conversation

@thothawei

Copy link
Copy Markdown
Owner

Stacked PR:base 是 #32。合併順序:#30 → #31 → #32 → 本 PR。

N 章節(多乘客/多停靠點)第一批。全章分三批:N1-N3(本 PR) → N4/N6/N7(payload 帶 stops、到站與跳過標記)→ N5(OSRM 多 waypoint 計費)。

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

相容性是這批的重點

既有單點訂單不產生任何 ride_stops 列;多停靠點訂單也照樣寫 rides.pickup_point(第一個上車點)與 dropoff_point(最終目的地)。

→ 派單找最近司機、司機導航、地圖、F3 路線里程退路、報表,全部照原樣讀 rides,一行都不用改。ride_stops 是額外資訊,不是替代品。兩條都有測試釘住。

N1 migration 000021

ride_stops: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 已隱含索引,不另建)

狀態用兩個時間欄(arrived_at/skipped_at)而非 status 字串:兩者天然互斥、且都需要「何時發生」——時間欄一次回答「是否發生」與「何時」,不必另外維護狀態機。皆 NULL = 尚未處理。skipped_at 對應 2026-07-17 拍板的「司機可跳過缺席乘客」。

passenger_label 不做值域 CHECK(不同於車種):純粹給司機辨識,不參與邏輯判斷,值髒掉不會算錯錢。

N2 驗證

上限放 internal/constants/ride_stop.go(MaxRidePassengers=5/MaxRideStops=10),不放 fleet_settings——TODO 寫「實作時定」:它是產品規則不是營運費率,沒有後台隨時要調的需求,放常數才能被編譯期引用。

規則(全部回 400):停靠點數 ≤10、乘客數 ≤5、kind 白名單、座標合法、seq 不得重複、每位乘客成對 pickup+dropoff、dropoff.seq > pickup.seq(不能叫司機先送再接)。

錯誤刻意分成多個而非一個籠統的 ErrInvalidStops——乘客填錯時要知道錯在哪。

N3 建單 API

POST /api/rides body 加選填 stops: [{seq, kind, lat, lng, address, passenger_label}]。

  • 無 stops = 完全維持現行行為
  • 有 stops → pickup/dropoff 由 stops 推導並覆蓋 body 的 pickup_lat/lng
  • 落庫順序:停靠點寫在 rides.Create 之後、派單之前(派單一發出,司機就該看得到全程)。寫失敗則整筆建單失敗——「只有第一個上車點、少載其餘乘客」的行程比沒建成更糟
  • 未注入 stops repo 卻收到 stops → ErrStopsUnavailable → 503(不是 400:伺服器沒接好,不該讓乘客以為自己填錯,更不能默默當單點訂單建出去)

驗收(實際跑過)

  • go build / go vet / gofmt 綠;service 1274s、repository 604s、handler 47s、constants 全套通過。
  • 14 個驗證單元案:合法(空 stops/兩人四停交錯/5 人 10 停上限/客戶端未依序送);非法(超上限/未成對/先下後上/同人兩個上車點/seq 重複/seq=0/kind 非白名單/無標籤/座標非法)。
  • 5 個整合案(真 PostGIS + Redis):多停靠點落庫(含座標經緯度正確、rides 推導正確、新停靠點為未處理)、未依序送仍依 seq 落庫、單點訂單不建 stops、驗證失敗不留孤兒訂單、未注入時明確失敗。
  • 反向驗證:ST_MakePoint 經緯度對調 → 台北車站跑到 lat=58.48(愛沙尼亞),FAIL;拿掉「由 stops 推導」→ 建單以「無效的上車座標」FAIL。

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

本批未做(後續兩批)

  • N4/N6/N7:ride.assigned/司機 active 帶 stops;到站與跳過標記 API。
  • N5:OSRM 多 waypoint 計費(現行 client 介面寫死兩點)+ haversine 逐段累加;排除已跳過的停靠點——沒去就沒開那段路,計入等於收乘客沒走的路的錢。

🤖 Generated with Claude Code

@thothawei
thothawei force-pushed the claude/o4-o7-vehicle-visibility branch 2 times, most recently from 5671332 to 972003a Compare July 17, 2026 06:32
@thothawei
thothawei force-pushed the claude/n1-n3-ride-stops branch from 03237ec to f99cd71 Compare July 17, 2026 06:34
@thothawei
thothawei changed the base branch from claude/o4-o7-vehicle-visibility to main July 17, 2026 06:34
N 章節第一批(共三批:N1-N3 → N4/N6/N7 → N5)。

N1 migration 000021:ride_stops(ride_id FK CASCADE、seq、kind、point、address、
passenger_label、arrived_at、skipped_at)。CHECK seq>=1 與 kind 白名單;
UNIQUE(ride_id, seq)——seq=「第幾站」,重複的話「下一站是誰」沒有答案。

狀態用兩個時間欄而非 status 字串:天然互斥且都需要「何時發生」,時間欄一次回答
「是否」與「何時」,不必另維護狀態機。skipped_at 對應 2026-07-17 拍板的「司機可
跳過缺席乘客」。passenger_label 不做值域 CHECK——不參與邏輯判斷,髒了不會算錯錢。

N2 驗證(純函式 validateStops):上限 5 位/10 停放 constants 而非 fleet_settings
(產品規則不是營運費率,放常數才能被編譯期引用)。規則:seq 不重複、每位乘客成對
pickup+dropoff、dropoff.seq > pickup.seq(不能先送再接)。錯誤分成多個而非一個籠統
的 ErrInvalidStops——乘客填錯要知道錯在哪。全部回 400。

N3 建單 API:body 加選填 stops。無 stops=完全維持現行行為(測試釘住:單點訂單不
產生任何 ride_stops 列)。有 stops 時 pickup/dropoff 由 stops 推導(第一個 pickup/
seq 最大的 dropoff)→ rides 照樣有值,派單、導航、地圖、F3 退路、報表一行都不用改。
ride_stops 是額外資訊不是替代品。

停靠點寫在 rides.Create 之後、派單之前(派單一發出司機就該看得到全程),寫失敗則整筆
建單失敗——「只有第一個上車點、少載其餘乘客」比沒建成更糟。未注入 repo 卻收到 stops
→ 503 而非 400(伺服器沒接好,不是乘客填錯)。

驗收:build/vet/gofmt 綠;service 1274s、repository 604s、handler 47s、constants
全套通過。14 個驗證單元案+5 個整合案。反向驗證:ST_MakePoint 經緯度對調 → 座標跑到
lat=58.48(愛沙尼亞)FAIL;拿掉推導 → 建單以「無效的上車座標」FAIL。

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
@thothawei
thothawei force-pushed the claude/n1-n3-ride-stops branch from f99cd71 to 281d3f1 Compare July 17, 2026 06:34
@thothawei
thothawei merged commit d292461 into main Jul 17, 2026
1 check passed
@thothawei
thothawei deleted the claude/n1-n3-ride-stops branch July 28, 2026 00:55
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant