From 3d48786a9efb6112bf93cbf549978c0d3bcaac8e Mon Sep 17 00:00:00 2001 From: awei Date: Fri, 17 Jul 2026 13:29:20 +0800 Subject: [PATCH] =?UTF-8?q?feat(N4+N6+N7):=20=E5=8F=B8=E6=A9=9F=E7=AB=AF?= =?UTF-8?q?=E7=9C=8B=E5=BE=97=E5=88=B0=E5=85=A8=E7=A8=8B=E5=81=9C=E9=9D=A0?= =?UTF-8?q?=E9=BB=9E=EF=BC=8B=E5=88=B0=E7=AB=99=EF=BC=8F=E8=B7=B3=E9=81=8E?= =?UTF-8?q?=E6=A8=99=E8=A8=98?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit N 章節第二批(第三批 N5 計費)。 N4 派單:邏輯完全沒動——仍以 rides.pickup_point(=第一個上車點,N3 已推導)找最近 司機。ride.assigned 與司機端 ride.accepted 加 stops,司機接單前就看得到「A 在哪上、 B 在哪下、最終到哪」。單點訂單不放 stops 鍵。座標攤平成 lat/lng,與既有 pickup_lat/lng 一致,App 端不必另寫解析。讀停靠點失敗不擋派單,退化成看不到全程但仍可執行。 FCM 註記修正:TODO 原提醒「FCM data 要 JSON 字串化」,但盤點後發現後端根本還沒送 data——notify.SendRideOffer 只送 title/body/ride_id 且實作是 stub(真 FCM 是 A2)。 stops 目前只走 WS;提醒移到 rideAssignedPayload 註解留給日後做真 FCM 的人。 N6 司機 active:DriverRideView 內嵌 *model.Ride(JSON 攤平,既有欄位一個不少), 單點訂單 omitempty 不會多出空陣列。停靠點含 arrived_at/skipped_at,只在真的發生時帶。 N7 到站/跳過標記:POST /api/rides/:id/stops/:stop_id/arrive 與 /skip。 授權是重點:stop_id 全域遞增 → 只驗 ride 歸屬不夠,必須同時驗 stop.RideID == rideID, 否則司機可拿自己的 ride_id 改別人行程的停靠點。 不覆寫既有事實:條件式更新(WHERE arrived_at IS NULL AND skipped_at IS NULL),重複 標記回 409;已到達的站不得反悔改成跳過——那會讓 N5 計費路線少算司機真的開過的路。 行程已完成/取消一律 409(計費已定格)。 測試本身踩過一個坑並修正:兩個 fixture 各起一個容器時 id 都從 1 開始,「別趟的 stop_id」會撞到自己那趟的同號 stop 而合法通過(假綠)。改為同一個 DB 建兩趟。 驗收:build/vet/gofmt 綠;service 1341s、repository 611s、handler 45s、constants 全套通過。反向驗證:拿掉 stop.RideID 檢查 → 可標記別趟停靠點,FAIL。 Co-Authored-By: Claude Opus 4.8 --- cmd/server/main.go | 6 + docs/TODO.md | 50 ++++- internal/handler/ride.go | 59 +++++ internal/repository/ride_stop.go | 33 +++ internal/service/dispatch.go | 45 +++- internal/service/dispatch_publish_test.go | 10 +- internal/service/ride.go | 23 +- internal/service/ride_stops.go | 131 +++++++++++ internal/service/ride_stops_mark_test.go | 227 ++++++++++++++++++++ internal/service/ride_stops_payload_test.go | 113 ++++++++++ 10 files changed, 675 insertions(+), 22 deletions(-) create mode 100644 internal/service/ride_stops.go create mode 100644 internal/service/ride_stops_mark_test.go create mode 100644 internal/service/ride_stops_payload_test.go diff --git a/cmd/server/main.go b/cmd/server/main.go index 09021ea..ea438e5 100644 --- a/cmd/server/main.go +++ b/cmd/server/main.go @@ -143,6 +143,8 @@ func main() { driverRegistry := service.NewDriverRegistry(driverRepo) rideQueryService := service.NewRideQueryService(trackRepo, rideRepo) rideQueryService.SetDrivers(driverRepo) // O4/O7:乘客查自己訂單時附司機姓名/電話 + rideQueryService.SetStops(rideStopRepo) // N6:司機端 active 帶全程停靠點 + rideStopService := service.NewRideStopService(rideRepo, rideStopRepo) chatService := service.NewChatService(rideRepo, rideMessageRepo, hub) lostItemService := service.NewLostItemService(rideRepo, lostItemRepo, feeSettings, hub) @@ -160,6 +162,7 @@ func main() { driverHandler := handler.NewDriverHandler(trackingService, driverRegistry, rideQueryService, cfg.JWTSecret, cfg.JWTExpiryHours) driverHandler.SetEarnings(reportRepo, feeSettings) rideHandler := handler.NewRideHandler(dispatchService, trackingService, rideQueryService, rideService) + rideHandler.SetStops(rideStopService) // N7:司機標記到達/跳過停靠點 deviceTokenHandler := handler.NewDeviceTokenHandler(deviceTokenService) wsHandler := handler.NewWSHandler(hub, cfg.JWTSecret, cfg.WSWriteWaitSec, cfg.WSPongWaitSec, cfg.WSMaxMessageBytes) chatHandler := handler.NewChatHandler(chatService) @@ -236,6 +239,9 @@ func main() { authed.DELETE("/driver/device-token", deviceTokenHandler.UnregisterByDriver) authed.POST("/rides/:id/accept", rideHandler.Accept) authed.POST("/rides/:id/pickup", rideHandler.PickUp) + // N7:多停靠點行程的到達/跳過標記(被指派司機限定) + authed.POST("/rides/:id/stops/:stop_id/arrive", rideHandler.ArriveStop) + authed.POST("/rides/:id/stops/:stop_id/skip", rideHandler.SkipStop) authed.POST("/rides/:id/complete", rideHandler.Complete) authed.POST("/rides/:id/cancel", rideHandler.Cancel) authed.POST("/rides/:id/decline", rideHandler.Decline) diff --git a/docs/TODO.md b/docs/TODO.md index 17abf7b..00cd7b8 100644 --- a/docs/TODO.md +++ b/docs/TODO.md @@ -304,10 +304,17 @@ 拿掉「由 stops 推導 pickup/dropoff」→ 建單以 `無效的上車座標` FAIL。 **未驗**:docker compose 全服務 live E2E。 -- [ ] **N4. 派單與 ETA**(`dispatch.go`) - 派單仍以「第一個上車點」找最近司機(現行邏輯不變)。 - `ride.assigned` payload 加 `stops`(司機接單前就能看到全程)——注意 FCM data 值一律是字串, - 複雜結構要 JSON 字串化,App 端解析要防禦(見 pitfall-fcm-data-all-strings)。 +- [x] **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-16 使用者拍板)** (`internal/osrm/client.go` + `tracking.go` `Complete`) @@ -335,13 +342,36 @@ 車資公式本身(起步+每公里、整數元、快照制、`min_fare` 地板)**完全不變**。 -- [ ] **N6. 司機端行程 API 帶 stops** - `GET /api/driver/rides/active`、`ride.accepted` 等回傳 `stops`(含順序與乘客標籤), - 司機才知道下一站是誰、在哪。 +- [x] **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`(**只在真的發生時帶**,兩者皆無=待處理)—— + 司機據此知道「下一站是誰、在哪、處理了沒」。 + +- [x] **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(計費已定格,改了也不會重算)。 -- [ ] **N7. 到站標記(可選)** - 司機標記「A 已上車/B 已下車」→ 更新 `ride_stops.arrived_at`。 - 決定是否需要(會影響司機端 UI 複雜度與 picked_up/completed 的語意)。 + **驗收**:`go build`/`vet`/`gofmt` 綠。 + 單元:`stopViews`(座標攤平、狀態鍵只在發生時帶、空回 nil)、`rideAssignedPayload`/ + `rideAcceptedDriverPayload` 帶/不帶 stops。 + 整合(真 PostGIS):到達與跳過、不覆寫既有事實(重複標記/已到達改跳過皆 409)、 + **授權邊界三案**(別的司機/別趟的 stop_id/行程不存在)、行程已完成不得標記、`ListForDriver`。 + **反向驗證**:拿掉 `stop.RideID != rideID` 檢查 → 可標記別趟的停靠點,FAIL。 + **未驗**:docker compose 全服務 live E2E。 ### 風險與待拍板 diff --git a/internal/handler/ride.go b/internal/handler/ride.go index b3f53de..8a13eae 100644 --- a/internal/handler/ride.go +++ b/internal/handler/ride.go @@ -17,6 +17,7 @@ type RideHandler struct { tracking *service.TrackingService rides *service.RideQueryService rideService *service.RideService + stops *service.RideStopService } func NewRideHandler( @@ -28,6 +29,64 @@ func NewRideHandler( return &RideHandler{dispatch: dispatch, tracking: tracking, rides: rides, rideService: rideService} } +// SetStops 注入停靠點服務(供 N7 的到達/跳過標記);可選。 +func (h *RideHandler) SetStops(stops *service.RideStopService) { + h.stops = stops +} + +// stopStatusForErr 停靠點標記的錯誤對應。 +func stopStatusForErr(err error) int { + switch { + case errors.Is(err, service.ErrForbidden): + return http.StatusForbidden + case errors.Is(err, service.ErrNotFound): + return http.StatusNotFound + case errors.Is(err, service.ErrStopAlreadyHandled), errors.Is(err, service.ErrBadStopState): + return http.StatusConflict + default: + return http.StatusInternalServerError + } +} + +// ArriveStop POST /api/rides/:id/stops/:stop_id/arrive — 司機標記已到達該停靠點(N7)。 +// 重複標記或該站已跳過回 409(到達時間是計費與稽核的原始資料,不覆寫)。 +func (h *RideHandler) ArriveStop(c *gin.Context) { + h.markStop(c, func(driverID, rideID, stopID int64) error { + return h.stops.MarkArrived(driverID, rideID, stopID) + }) +} + +// SkipStop POST /api/rides/:id/stops/:stop_id/skip — 乘客未出現,司機跳過該停靠點(N7)。 +// 被跳過的站不計入 N5 的計費路線——沒去就沒開那段路。 +func (h *RideHandler) SkipStop(c *gin.Context) { + h.markStop(c, func(driverID, rideID, stopID int64) error { + return h.stops.MarkSkipped(driverID, rideID, stopID) + }) +} + +func (h *RideHandler) markStop(c *gin.Context, do func(driverID, rideID, stopID int64) error) { + if h.stops == nil { + c.JSON(http.StatusServiceUnavailable, gin.H{"error": "多停靠點行程未啟用"}) + return + } + rideID, err := strconv.ParseInt(c.Param("id"), 10, 64) + if err != nil { + c.JSON(http.StatusBadRequest, gin.H{"error": "id 格式錯誤"}) + return + } + stopID, err := strconv.ParseInt(c.Param("stop_id"), 10, 64) + if err != nil { + c.JSON(http.StatusBadRequest, gin.H{"error": "stop_id 格式錯誤"}) + return + } + driverID := middleware.DriverIDFromCtx(c) + if err := do(driverID, rideID, stopID); err != nil { + c.JSON(stopStatusForErr(err), gin.H{"error": err.Error()}) + return + } + c.JSON(http.StatusOK, gin.H{"ok": true}) +} + // statusForErr 擁有權錯誤回 403,其餘狀態衝突回 409 func statusForErr(err error) int { if errors.Is(err, service.ErrForbidden) { diff --git a/internal/repository/ride_stop.go b/internal/repository/ride_stop.go index 39d06f3..743115d 100644 --- a/internal/repository/ride_stop.go +++ b/internal/repository/ride_stop.go @@ -54,3 +54,36 @@ func (r *RideStopRepository) ListByRide(rideID int64) ([]model.RideStop, error) err := r.db.Where("ride_id = ?", rideID).Order("seq ASC").Find(&stops).Error return stops, err } + +// FindByID 取單一停靠點(供標記到達/跳過時驗證歸屬)。 +func (r *RideStopRepository) FindByID(stopID int64) (*model.RideStop, error) { + var s model.RideStop + if err := r.db.First(&s, stopID).Error; err != nil { + return nil, err + } + return &s, nil +} + +// MarkArrived 標記司機已到達該停靠點(N7)。 +// +// 條件式更新:只在「尚未處理」時才寫入。重複標記、或該站已被跳過時,RowsAffected 為 0, +// 呼叫端據此回 409——而不是默默覆寫既有事實(到達時間是計費與稽核的原始資料)。 +func (r *RideStopRepository) MarkArrived(stopID int64) (bool, error) { + now := time.Now() + res := r.db.Model(&model.RideStop{}). + Where("id = ? AND arrived_at IS NULL AND skipped_at IS NULL", stopID). + Updates(map[string]interface{}{"arrived_at": now, "updated_at": now}) + return res.RowsAffected > 0, res.Error +} + +// MarkSkipped 標記乘客未出現、司機跳過該停靠點(N7,2026-07-17 拍板)。 +// +// 同樣是條件式更新:**已到達的站不得反悔改成跳過**——那會讓 N5 的計費路線 +// 少算一段司機真的開過的路。 +func (r *RideStopRepository) MarkSkipped(stopID int64) (bool, error) { + now := time.Now() + res := r.db.Model(&model.RideStop{}). + Where("id = ? AND arrived_at IS NULL AND skipped_at IS NULL", stopID). + Updates(map[string]interface{}{"skipped_at": now, "updated_at": now}) + return res.RowsAffected > 0, res.Error +} diff --git a/internal/service/dispatch.go b/internal/service/dispatch.go index ff4dea1..c13dda4 100644 --- a/internal/service/dispatch.go +++ b/internal/service/dispatch.go @@ -29,6 +29,7 @@ type DispatchService struct { settings *DispatchSettings publisher events.Publisher appNotify *notify.Dispatcher + stops *repository.RideStopRepository audit rideAuditor } @@ -67,6 +68,28 @@ func (s *DispatchService) SetRideEvents(repo *repository.RideEventRepository) { s.audit = rideAuditor{events: repo} } +// SetStops 注入停靠點 repo(供 ride.assigned/ride.accepted 帶 stops,N4);可選。 +func (s *DispatchService) SetStops(stops *repository.RideStopRepository) { + s.stops = stops +} + +// rideStops 讀該趟停靠點;未注入 repo、單點訂單、或讀取失敗皆回 nil +// (呼叫端據此不放 stops 鍵)。 +// +// 讀失敗刻意不擋派單:單點訂單本來就沒有停靠點,多停靠點則退化成「司機端看不到全程」, +// 仍可依 rides.pickup_point 前往第一個上車點——比整趟派不出去好。 +func (s *DispatchService) rideStops(rideID int64) []model.RideStop { + if s.stops == nil { + return nil + } + stops, err := s.stops.ListByRide(rideID) + if err != nil { + log.Error().Err(err).Int64("ride_id", rideID).Msg("讀取停靠點失敗,本次 payload 不帶 stops") + return nil + } + return stops +} + // publish nil-safe 事件發佈(未接 Hub 時靜默略過) func (s *DispatchService) publish(rec events.Recipient, ev events.Event) { if s.publisher == nil { @@ -198,7 +221,13 @@ func rideAcceptedCustomerPayload(driver *model.Driver, etaSec int) map[string]an // rideAssignedPayload 組裝 ride.assigned WS 事件 payload(含選填目的地)。 // pickup 座標與 dropoff 對稱一併帶上:司機端接單當下就要在地圖標出上車點, // 光靠 address 字串無法定位(PickupPoint 為 not null,必定有值)。 -func rideAssignedPayload(ride *model.Ride, pickupAddress string, etaSec, distM int) map[string]any { +// stops 為多乘客/多停靠點行程的全程(N4):司機**接單前**就要看得到 +// 「A 在哪上、B 在哪下、最終到哪」,才知道要不要接。單點訂單不放這個鍵。 +// +// 注意(給日後做真 FCM 的人):目前 App 推播只送 title/body(notify.SendRideOffer 是 stub), +// stops 只走 WS。真 FCM 上線時 data 值一律是字串,stops 這種結構**必須 JSON 字串化**, +// App 端解析要防禦(見 pitfall-fcm-data-all-strings:漏掉會讓推播接單直接崩)。 +func rideAssignedPayload(ride *model.Ride, pickupAddress string, etaSec, distM int, stops []model.RideStop) map[string]any { payload := map[string]any{ "address": pickupAddress, "pickup_lat": ride.PickupPoint.Lat, @@ -207,14 +236,20 @@ func rideAssignedPayload(ride *model.Ride, pickupAddress string, etaSec, distM i "dist_m": distM, } putDropoff(payload, ride) + if v := stopViews(stops); v != nil { + payload["stops"] = v + } return payload } // rideAcceptedDriverPayload 組裝 ride.accepted 推給「司機端」的 payload; -// 司機接單後直接拿到目的地,不必等 pickup 回應。 -func rideAcceptedDriverPayload(ride *model.Ride) map[string]any { +// 司機接單後直接拿到目的地與全程停靠點,不必等 pickup 回應。 +func rideAcceptedDriverPayload(ride *model.Ride, stops []model.RideStop) map[string]any { payload := map[string]any{} putDropoff(payload, ride) + if v := stopViews(stops); v != nil { + payload["stops"] = v + } return payload } @@ -244,7 +279,7 @@ func (s *DispatchService) pushOffer(ctx context.Context, driver *model.Driver, r s.publish(events.Recipient{Role: events.RoleDriver, ID: driver.ID}, events.Event{ Type: events.TypeRideAssigned, RideID: ride.ID, - Payload: rideAssignedPayload(ride, ride.PickupAddress, etaSec, distM), + Payload: rideAssignedPayload(ride, ride.PickupAddress, etaSec, distM, s.rideStops(ride.ID)), }) } @@ -489,7 +524,7 @@ func (s *DispatchService) AcceptRide(ctx context.Context, rideID, driverID int64 s.publish(events.Recipient{Role: events.RoleDriver, ID: driverID}, events.Event{ Type: events.TypeRideAccepted, RideID: rideID, - Payload: rideAcceptedDriverPayload(ride), + Payload: rideAcceptedDriverPayload(ride, s.rideStops(rideID)), }) return "接單成功", nil diff --git a/internal/service/dispatch_publish_test.go b/internal/service/dispatch_publish_test.go index 647123a..a78aa86 100644 --- a/internal/service/dispatch_publish_test.go +++ b/internal/service/dispatch_publish_test.go @@ -59,7 +59,7 @@ func TestRideAssignedPayload_含Pickup座標(t *testing.T) { PickupAddress: "台北101", PickupPoint: model.GeoPoint{Lat: 25.033, Lng: 121.5654}, } - payload := rideAssignedPayload(ride, ride.PickupAddress, 300, 1200) + payload := rideAssignedPayload(ride, ride.PickupAddress, 300, 1200, nil) if payload["pickup_lat"] != 25.033 || payload["pickup_lng"] != 121.5654 { t.Fatalf("pickup 座標錯誤: %v", payload) } @@ -72,7 +72,7 @@ func TestRideAssignedPayload_含Dropoff(t *testing.T) { DropoffAddress: "松山機場", DropoffPoint: &model.GeoPoint{Lat: lat, Lng: lng}, } - payload := rideAssignedPayload(ride, ride.PickupAddress, 300, 1200) + payload := rideAssignedPayload(ride, ride.PickupAddress, 300, 1200, nil) if payload["address"] != "台北101" { t.Fatalf("address 錯誤: %v", payload["address"]) } @@ -86,7 +86,7 @@ func TestRideAssignedPayload_含Dropoff(t *testing.T) { func TestRideAssignedPayload_無Dropoff時省略欄位(t *testing.T) { ride := &model.Ride{PickupAddress: "台北101"} - payload := rideAssignedPayload(ride, ride.PickupAddress, 300, 1200) + payload := rideAssignedPayload(ride, ride.PickupAddress, 300, 1200, nil) if _, ok := payload["dropoff_address"]; ok { t.Fatal("不應有 dropoff_address") } @@ -101,7 +101,7 @@ func TestRideAcceptedDriverPayload_帶目的地座標(t *testing.T) { DropoffAddress: "松山機場", DropoffPoint: &model.GeoPoint{Lat: lat, Lng: lng}, } - payload := rideAcceptedDriverPayload(ride) + payload := rideAcceptedDriverPayload(ride, nil) if payload["dropoff_address"] != "松山機場" { t.Fatalf("dropoff_address 錯誤: %v", payload["dropoff_address"]) } @@ -111,7 +111,7 @@ func TestRideAcceptedDriverPayload_帶目的地座標(t *testing.T) { } func TestRideAcceptedDriverPayload_無Dropoff時為空(t *testing.T) { - payload := rideAcceptedDriverPayload(&model.Ride{}) + payload := rideAcceptedDriverPayload(&model.Ride{}, nil) if len(payload) != 0 { t.Fatalf("無目的地時 payload 應為空: %v", payload) } diff --git a/internal/service/ride.go b/internal/service/ride.go index e501d1d..d4e295e 100644 --- a/internal/service/ride.go +++ b/internal/service/ride.go @@ -252,12 +252,19 @@ type RideQueryService struct { tracks *repository.TrackRepository rides *repository.RideRepository drivers *repository.DriverRepository + stops *repository.RideStopRepository } func NewRideQueryService(tracks *repository.TrackRepository, rides *repository.RideRepository) *RideQueryService { return &RideQueryService{tracks: tracks, rides: rides} } +// SetStops 注入停靠點 repo(供司機端 active 帶 stops,N6);可選—— +// 未注入時單點與多停靠點行程皆可查,只是後者不帶 stops。 +func (s *RideQueryService) SetStops(stops *repository.RideStopRepository) { + s.stops = stops +} + // SetDrivers 注入司機 repo(供乘客端查看司機姓名/電話,O4/O7);可選—— // 未注入時查詢仍可用,只是不帶司機聯絡資訊。 func (s *RideQueryService) SetDrivers(drivers *repository.DriverRepository) { @@ -315,8 +322,20 @@ func (s *RideQueryService) GetActiveRideByCustomer(customerID int64) (*CustomerR } // GetActiveRideByDriver 找司機目前進行中的訂單(已接/載客中),供 App 中途重啟恢復行程;無則回 (nil, nil) -func (s *RideQueryService) GetActiveRideByDriver(driverID int64) (*model.Ride, error) { - return s.rides.FindActiveByDriver(driverID) +func (s *RideQueryService) GetActiveRideByDriver(driverID int64) (*DriverRideView, error) { + ride, err := s.rides.FindActiveByDriver(driverID) + if err != nil || ride == nil { + return nil, err + } + view := &DriverRideView{Ride: ride} + // N6:司機要知道下一站是誰、在哪。單點訂單為 nil(omitempty),形狀不變。 + // 讀失敗不擋——司機仍能依 rides.pickup_point/dropoff_point 執行行程。 + if s.stops != nil { + if stops, err := s.stops.ListByRide(ride.ID); err == nil { + view.Stops = stopViews(stops) + } + } + return view, nil } // AuthorizeTrackAccess 授權軌跡端點的多角色存取:admin 全放行、本趟乘客、被指派司機皆可, diff --git a/internal/service/ride_stops.go b/internal/service/ride_stops.go new file mode 100644 index 0000000..f405b01 --- /dev/null +++ b/internal/service/ride_stops.go @@ -0,0 +1,131 @@ +package service + +import ( + "errors" + + "line-fleet-dispatch/internal/constants" + "line-fleet-dispatch/internal/model" + "line-fleet-dispatch/internal/repository" +) + +var ( + // ErrStopAlreadyHandled 該停靠點已標記過到達或跳過(N7)。 + // 到達時間是計費與稽核的原始資料,不接受覆寫。 + ErrStopAlreadyHandled = errors.New("此停靠點已標記過") + // ErrBadStopState 行程狀態不允許標記停靠點(已完成/已取消時計費已定格)。 + ErrBadStopState = errors.New("行程狀態不允許標記停靠點") +) + +const timeLayoutRFC3339 = "2006-01-02T15:04:05Z07:00" + +// stopView 送給司機端的單一停靠點(N4/N6)。 +// 座標攤平成 lat/lng——與 ride.assigned 既有的 pickup_lat/lng 一致, +// App 端不必為 stops 另寫一套座標解析。 +func stopView(s model.RideStop) map[string]any { + v := map[string]any{ + "id": s.ID, + "seq": s.Seq, + "kind": s.Kind, + "lat": s.Point.Lat, + "lng": s.Point.Lng, + "passenger_label": s.PassengerLabel, + } + if s.Address != "" { + v["address"] = s.Address + } + // 只在真的發生時帶——司機端據此顯示「已到達/已跳過」,兩者皆無=待處理。 + if s.ArrivedAt != nil { + v["arrived_at"] = s.ArrivedAt.Format(timeLayoutRFC3339) + } + if s.SkippedAt != nil { + v["skipped_at"] = s.SkippedAt.Format(timeLayoutRFC3339) + } + return v +} + +// stopViews 轉整趟停靠點;空 slice 回 nil,讓呼叫端可以「沒有就不放這個鍵」 +// (單點訂單的 payload 不該多一個空 stops 陣列)。 +func stopViews(stops []model.RideStop) []map[string]any { + if len(stops) == 0 { + return nil + } + out := make([]map[string]any, 0, len(stops)) + for _, s := range stops { + out = append(out, stopView(s)) + } + return out +} + +// DriverRideView 司機視角的進行中訂單:ride 全欄位 + 全程停靠點(N6)。 +// 內嵌 *model.Ride 讓 JSON 攤平,既有欄位一個不少——App 讀到的形狀只多不變。 +// 單點訂單的 Stops 為 nil(omitempty),不會多出一個空陣列。 +type DriverRideView struct { + *model.Ride + Stops []map[string]any `json:"stops,omitempty"` +} + +// RideStopService 停靠點的讀取與標記(N6/N7)。 +type RideStopService struct { + rides *repository.RideRepository + stops *repository.RideStopRepository +} + +func NewRideStopService(rides *repository.RideRepository, stops *repository.RideStopRepository) *RideStopService { + return &RideStopService{rides: rides, stops: stops} +} + +// ListForDriver 司機讀取自己那趟的停靠點;非被指派司機回 ErrForbidden。 +func (s *RideStopService) ListForDriver(driverID, rideID int64) ([]model.RideStop, error) { + ride, err := s.rides.GetByID(rideID) + if err != nil { + return nil, ErrNotFound + } + if ride.DriverID == nil || *ride.DriverID != driverID { + return nil, ErrForbidden + } + return s.stops.ListByRide(rideID) +} + +// MarkArrived 司機標記已到達該停靠點(N7)。 +func (s *RideStopService) MarkArrived(driverID, rideID, stopID int64) error { + return s.mark(driverID, rideID, stopID, s.stops.MarkArrived) +} + +// MarkSkipped 司機標記乘客未出現、跳過該停靠點(N7,2026-07-17 拍板)。 +// 被跳過的站不計入 N5 的計費路線——沒去就沒開那段路。 +func (s *RideStopService) MarkSkipped(driverID, rideID, stopID int64) error { + return s.mark(driverID, rideID, stopID, s.stops.MarkSkipped) +} + +// mark 到達/跳過共用的授權與狀態檢查。 +// +// 授權在標記之前,且**同時驗 ride 歸屬與 stop 歸屬**:stop_id 是全域遞增的, +// 只驗 ride 的話,司機可以拿自己的 ride_id 去改別人行程的停靠點狀態。 +func (s *RideStopService) mark(driverID, rideID, stopID int64, do func(int64) (bool, error)) error { + ride, err := s.rides.GetByID(rideID) + if err != nil { + return ErrNotFound + } + if ride.DriverID == nil || *ride.DriverID != driverID { + return ErrForbidden + } + // 行程已完成/取消就不該再改停靠點狀態(計費已定格,改了也不會重算)。 + if ride.Status != constants.RideStatusAccepted && ride.Status != constants.RideStatusPickedUp { + return ErrBadStopState + } + stop, err := s.stops.FindByID(stopID) + if err != nil { + return ErrNotFound + } + if stop.RideID != rideID { + return ErrForbidden + } + ok, err := do(stopID) + if err != nil { + return err + } + if !ok { + return ErrStopAlreadyHandled // 已到達或已跳過,不覆寫 + } + return nil +} diff --git a/internal/service/ride_stops_mark_test.go b/internal/service/ride_stops_mark_test.go new file mode 100644 index 0000000..bcc57ad --- /dev/null +++ b/internal/service/ride_stops_mark_test.go @@ -0,0 +1,227 @@ +package service + +import ( + "errors" + "testing" + "time" + + "line-fleet-dispatch/internal/constants" + "line-fleet-dispatch/internal/model" + "line-fleet-dispatch/internal/repository" +) + +// stopsFixture 一趟已接單的兩人四停行程;**同一個 DB 裡**另有一位司機與他自己的一趟行程, +// 用來測授權邊界。 +// +// 「同一個 DB」是重點:newServiceTestDB 每次呼叫都起一個新容器,兩個 fixture 的 +// 自增 id 會各自從 1 開始而撞在一起——那樣「拿別趟的 stop_id」根本測不到跨行程, +// 反而會撞到自己那趟的同號 stop 而合法通過。 +type stopsFixture struct { + svc *RideStopService + stopsRepo *repository.RideStopRepository + rides *repository.RideRepository + rideID int64 + driverID int64 + otherID int64 + stopIDs []int64 + // otherRideID/otherStopIDs 同一個 DB 裡、屬於 otherID 司機的另一趟行程。 + otherRideID int64 + otherStopIDs []int64 +} + +func newStopsFixture(t *testing.T, prefix string) *stopsFixture { + t.Helper() + db := newServiceTestDB(t) + drivers := repository.NewDriverRepository(db) + rides := repository.NewRideRepository(db) + stopsRepo := repository.NewRideStopRepository(db) + customers := repository.NewCustomerRepository(db) + + cust, err := customers.FindOrCreateByLineUserID(prefix+"_cust", "乘客") + if err != nil { + t.Fatalf("建立乘客失敗:%v", err) + } + driver, err := drivers.FindOrCreate(prefix+"_drv", "司機") + if err != nil { + t.Fatalf("建立司機失敗:%v", err) + } + other, err := drivers.FindOrCreate(prefix+"_other", "別的司機") + if err != nil { + t.Fatalf("建立司機失敗:%v", err) + } + + // newRide 在同一個 DB 建一趟兩人四停、已被指定司機接單的行程。 + newRide := func(driverID int64) (int64, []int64) { + t.Helper() + now := time.Now() + ride := &model.Ride{ + CustomerID: cust.ID, Status: constants.RideStatusRequested, + PickupPoint: model.GeoPoint{Lat: 25.03, Lng: 121.56}, PickupAddress: "台北車站", + RequestedAt: now, CreatedAt: now, UpdatedAt: now, + } + if err := rides.Create(ride); err != nil { + t.Fatalf("建立訂單失敗:%v", err) + } + rows := []repository.StopRow{ + {Seq: 1, Kind: constants.StopKindPickup, Lat: 25.03, Lng: 121.56, Address: "台北車站", PassengerLabel: "A"}, + {Seq: 2, Kind: constants.StopKindPickup, Lat: 25.04, Lng: 121.57, Address: "市政府", PassengerLabel: "B"}, + {Seq: 3, Kind: constants.StopKindDropoff, Lat: 25.05, Lng: 121.58, Address: "松山機場", PassengerLabel: "A"}, + {Seq: 4, Kind: constants.StopKindDropoff, Lat: 25.06, Lng: 121.59, Address: "台北101", PassengerLabel: "B"}, + } + if err := stopsRepo.CreateForRide(ride.ID, rows); err != nil { + t.Fatalf("建立停靠點失敗:%v", err) + } + if err := rides.AcceptRide(ride.ID, driverID, 300); err != nil { + t.Fatalf("接單失敗:%v", err) + } + stops, err := stopsRepo.ListByRide(ride.ID) + if err != nil { + t.Fatalf("讀停靠點失敗:%v", err) + } + ids := make([]int64, 0, len(stops)) + for _, s := range stops { + ids = append(ids, s.ID) + } + return ride.ID, ids + } + + rideID, ids := newRide(driver.ID) + otherRideID, otherIDs := newRide(other.ID) // 同一個 DB,id 不會與上一趟相撞 + + return &stopsFixture{ + svc: NewRideStopService(rides, stopsRepo), + stopsRepo: stopsRepo, + rides: rides, + rideID: rideID, + driverID: driver.ID, + otherID: other.ID, + stopIDs: ids, + otherRideID: otherRideID, + otherStopIDs: otherIDs, + } +} + +// TestMarkArrived_到達與跳過 N7 的正常路徑。 +func TestMarkArrived_到達與跳過(t *testing.T) { + f := newStopsFixture(t, "U_mark_ok") + + if err := f.svc.MarkArrived(f.driverID, f.rideID, f.stopIDs[0]); err != nil { + t.Fatalf("標記到達失敗:%v", err) + } + // B 沒出現 → 司機跳過 B 的上車點(2026-07-17 拍板)。 + if err := f.svc.MarkSkipped(f.driverID, f.rideID, f.stopIDs[1]); err != nil { + t.Fatalf("標記跳過失敗:%v", err) + } + + stops, err := f.stopsRepo.ListByRide(f.rideID) + if err != nil { + t.Fatalf("讀停靠點失敗:%v", err) + } + if stops[0].ArrivedAt == nil || stops[0].SkippedAt != nil { + t.Fatalf("第 1 站應為已到達:%+v", stops[0]) + } + if !stops[1].Skipped() || stops[1].ArrivedAt != nil { + t.Fatalf("第 2 站應為已跳過:%+v", stops[1]) + } + // 未動過的站維持待處理。 + if !stops[2].Pending() || !stops[3].Pending() { + t.Fatal("未標記的站應維持待處理") + } +} + +// TestMarkStop_不覆寫既有事實 到達時間是計費與稽核的原始資料。 +func TestMarkStop_不覆寫既有事實(t *testing.T) { + f := newStopsFixture(t, "U_mark_dup") + + if err := f.svc.MarkArrived(f.driverID, f.rideID, f.stopIDs[0]); err != nil { + t.Fatalf("首次標記應成功:%v", err) + } + if err := f.svc.MarkArrived(f.driverID, f.rideID, f.stopIDs[0]); !errors.Is(err, ErrStopAlreadyHandled) { + t.Fatalf("重複標記到達預期 ErrStopAlreadyHandled,得到 %v", err) + } + // 已到達的站不得反悔改成跳過——那會讓計費路線少算已經開過的路。 + if err := f.svc.MarkSkipped(f.driverID, f.rideID, f.stopIDs[0]); !errors.Is(err, ErrStopAlreadyHandled) { + t.Fatalf("已到達的站不該能改成跳過,得到 %v", err) + } + + f.mustBeArrivedOnly(t, 0) +} + +func (f *stopsFixture) mustBeArrivedOnly(t *testing.T, idx int) { + t.Helper() + stops, err := f.stopsRepo.ListByRide(f.rideID) + if err != nil { + t.Fatalf("讀停靠點失敗:%v", err) + } + if stops[idx].ArrivedAt == nil || stops[idx].SkippedAt != nil { + t.Fatalf("狀態不該被覆寫:%+v", stops[idx]) + } +} + +// TestMarkStop_授權邊界 N7 的重點:stop_id 全域遞增,只驗 ride 歸屬是不夠的。 +func TestMarkStop_授權邊界(t *testing.T) { + f := newStopsFixture(t, "U_mark_auth") + + t.Run("別的司機不得標記", func(t *testing.T) { + if err := f.svc.MarkArrived(f.otherID, f.rideID, f.stopIDs[0]); !errors.Is(err, ErrForbidden) { + t.Fatalf("非被指派司機預期 ErrForbidden,得到 %v", err) + } + }) + + t.Run("不得拿自己的 ride_id 去標記別趟的停靠點", func(t *testing.T) { + // 用「自己有權限的 rideID」搭配「別趟的 stopID」—— + // stop_id 是全域遞增的,只驗 ride 歸屬的話這裡會過,等於任何司機 + // 都能改別人行程的停靠點狀態。 + err := f.svc.MarkArrived(f.driverID, f.rideID, f.otherStopIDs[0]) + if !errors.Is(err, ErrForbidden) { + t.Fatalf("stop 不屬於該 ride 時預期 ErrForbidden,得到 %v", err) + } + // 反面:別趟的停靠點狀態不得被動到。 + stops, err := f.stopsRepo.ListByRide(f.otherRideID) + if err != nil { + t.Fatalf("讀停靠點失敗:%v", err) + } + if !stops[0].Pending() { + t.Fatalf("別趟的停靠點不該被標記:%+v", stops[0]) + } + }) + + t.Run("行程不存在", func(t *testing.T) { + if err := f.svc.MarkArrived(f.driverID, 999999, f.stopIDs[0]); !errors.Is(err, ErrNotFound) { + t.Fatalf("預期 ErrNotFound,得到 %v", err) + } + }) +} + +// TestMarkStop_行程已完成不得標記 計費已定格,改了也不會重算。 +func TestMarkStop_行程已完成不得標記(t *testing.T) { + f := newStopsFixture(t, "U_mark_done") + + if err := f.rides.UpdateStatus(f.rideID, constants.RideStatusCompleted); err != nil { + t.Fatalf("更新狀態失敗:%v", err) + } + if err := f.svc.MarkArrived(f.driverID, f.rideID, f.stopIDs[0]); !errors.Is(err, ErrBadStopState) { + t.Fatalf("已完成的行程預期 ErrBadStopState,得到 %v", err) + } +} + +// TestListForDriver 司機讀自己那趟的停靠點;別人不行。 +func TestListForDriver(t *testing.T) { + f := newStopsFixture(t, "U_list") + + stops, err := f.svc.ListForDriver(f.driverID, f.rideID) + if err != nil { + t.Fatalf("讀取失敗:%v", err) + } + if len(stops) != 4 { + t.Fatalf("預期 4 站,得到 %d", len(stops)) + } + for i, want := range []int{1, 2, 3, 4} { + if stops[i].Seq != want { + t.Fatalf("應依 seq 排序:%+v", stops) + } + } + if _, err := f.svc.ListForDriver(f.otherID, f.rideID); !errors.Is(err, ErrForbidden) { + t.Fatalf("非被指派司機預期 ErrForbidden,得到 %v", err) + } +} diff --git a/internal/service/ride_stops_payload_test.go b/internal/service/ride_stops_payload_test.go new file mode 100644 index 0000000..567d768 --- /dev/null +++ b/internal/service/ride_stops_payload_test.go @@ -0,0 +1,113 @@ +package service + +import ( + "testing" + "time" + + "line-fleet-dispatch/internal/constants" + "line-fleet-dispatch/internal/model" +) + +func sampleStops() []model.RideStop { + arrived := time.Date(2026, 7, 17, 10, 0, 0, 0, time.UTC) + return []model.RideStop{ + { + ID: 11, RideID: 5, Seq: 1, Kind: constants.StopKindPickup, + Point: model.GeoPoint{Lat: 25.0478, Lng: 121.5170}, + Address: "台北車站", PassengerLabel: "A", ArrivedAt: &arrived, + }, + { + ID: 12, RideID: 5, Seq: 2, Kind: constants.StopKindDropoff, + Point: model.GeoPoint{Lat: 25.0697, Lng: 121.5522}, + Address: "松山機場", PassengerLabel: "A", + }, + } +} + +// TestStopViews N4/N6:司機端要知道「第幾站、是誰、上車還下車、在哪」。 +func TestStopViews(t *testing.T) { + views := stopViews(sampleStops()) + if len(views) != 2 { + t.Fatalf("預期 2 站,得到 %d", len(views)) + } + + first := views[0] + if first["seq"] != 1 || first["kind"] != constants.StopKindPickup || first["passenger_label"] != "A" { + t.Fatalf("第 1 站內容錯誤:%v", first) + } + // 座標攤平成 lat/lng,與 ride.assigned 既有的 pickup_lat/lng 一致, + // App 端不必為 stops 另寫一套解析。 + if first["lat"] != 25.0478 || first["lng"] != 121.5170 { + t.Fatalf("座標應攤平成 lat/lng:%v", first) + } + if first["address"] != "台北車站" { + t.Fatalf("地址錯誤:%v", first) + } + // 已到達的站要帶時間,司機端據此顯示狀態。 + if _, ok := first["arrived_at"]; !ok { + t.Fatalf("已到達的站應帶 arrived_at:%v", first) + } + // 未跳過就不帶該鍵。 + if _, ok := first["skipped_at"]; ok { + t.Fatalf("未跳過不該帶 skipped_at:%v", first) + } + + // 待處理的站兩個時間鍵都不帶。 + second := views[1] + for _, k := range []string{"arrived_at", "skipped_at"} { + if _, ok := second[k]; ok { + t.Fatalf("待處理的站不該帶 %q:%v", k, second) + } + } +} + +// TestStopViews_空回nil 單點訂單的 payload 不該多一個空 stops 陣列。 +func TestStopViews_空回nil(t *testing.T) { + if stopViews(nil) != nil { + t.Fatal("nil 應回 nil") + } + if stopViews([]model.RideStop{}) != nil { + t.Fatal("空 slice 應回 nil") + } +} + +// TestRideAssignedPayload_帶stops N4:司機**接單前**就要看得到全程,才知道要不要接。 +func TestRideAssignedPayload_帶stops(t *testing.T) { + ride := &model.Ride{ + PickupAddress: "台北車站", + PickupPoint: model.GeoPoint{Lat: 25.0478, Lng: 121.5170}, + } + + t.Run("多停靠點帶 stops", func(t *testing.T) { + p := rideAssignedPayload(ride, ride.PickupAddress, 300, 1200, sampleStops()) + stops, ok := p["stops"].([]map[string]any) + if !ok || len(stops) != 2 { + t.Fatalf("應帶 2 站:%v", p["stops"]) + } + // 既有欄位不得因為加了 stops 而變動。 + if p["pickup_lat"] != 25.0478 || p["eta_sec"] != 300 { + t.Fatalf("既有欄位不該變:%v", p) + } + }) + + t.Run("單點訂單不帶 stops 鍵", func(t *testing.T) { + p := rideAssignedPayload(ride, ride.PickupAddress, 300, 1200, nil) + if _, ok := p["stops"]; ok { + t.Fatalf("單點訂單不該有 stops 鍵:%v", p) + } + }) +} + +// TestRideAcceptedDriverPayload_帶stops N6:接單後司機拿到全程,不必等 pickup 回應。 +func TestRideAcceptedDriverPayload_帶stops(t *testing.T) { + ride := &model.Ride{} + + p := rideAcceptedDriverPayload(ride, sampleStops()) + if stops, ok := p["stops"].([]map[string]any); !ok || len(stops) != 2 { + t.Fatalf("應帶 2 站:%v", p["stops"]) + } + + if p := rideAcceptedDriverPayload(ride, nil); len(p) != 0 { + t.Fatalf("單點無目的地訂單的 payload 應為空:%v", p) + } +}