Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
6 changes: 6 additions & 0 deletions cmd/server/main.go
Original file line number Diff line number Diff line change
Expand Up @@ -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)

Expand All @@ -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)
Expand Down Expand Up @@ -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)
Expand Down
50 changes: 40 additions & 10 deletions docs/TODO.md
Original file line number Diff line number Diff line change
Expand Up @@ -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`)
Expand Down Expand Up @@ -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。

### 風險與待拍板

Expand Down
59 changes: 59 additions & 0 deletions internal/handler/ride.go
Original file line number Diff line number Diff line change
Expand Up @@ -17,6 +17,7 @@ type RideHandler struct {
tracking *service.TrackingService
rides *service.RideQueryService
rideService *service.RideService
stops *service.RideStopService
}

func NewRideHandler(
Expand All @@ -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) {
Expand Down
33 changes: 33 additions & 0 deletions internal/repository/ride_stop.go
Original file line number Diff line number Diff line change
Expand Up @@ -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
}
45 changes: 40 additions & 5 deletions internal/service/dispatch.go
Original file line number Diff line number Diff line change
Expand Up @@ -29,6 +29,7 @@ type DispatchService struct {
settings *DispatchSettings
publisher events.Publisher
appNotify *notify.Dispatcher
stops *repository.RideStopRepository
audit rideAuditor
}

Expand Down Expand Up @@ -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 {
Expand Down Expand Up @@ -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,
Expand All @@ -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
}

Expand Down Expand Up @@ -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)),
})
}

Expand Down Expand Up @@ -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
Expand Down
10 changes: 5 additions & 5 deletions internal/service/dispatch_publish_test.go
Original file line number Diff line number Diff line change
Expand Up @@ -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)
}
Expand All @@ -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"])
}
Expand All @@ -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")
}
Expand All @@ -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"])
}
Expand All @@ -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)
}
Expand Down
23 changes: 21 additions & 2 deletions internal/service/ride.go
Original file line number Diff line number Diff line change
Expand Up @@ -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) {
Expand Down Expand Up @@ -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 全放行、本趟乘客、被指派司機皆可,
Expand Down
Loading
Loading