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
1 change: 1 addition & 0 deletions cmd/server/main.go
Original file line number Diff line number Diff line change
Expand Up @@ -140,6 +140,7 @@ func main() {
trackingService.SetReports(reportRepo) // F9-3:完成時重算每日彙總 daily_driver_earnings
driverRegistry := service.NewDriverRegistry(driverRepo)
rideQueryService := service.NewRideQueryService(trackRepo, rideRepo)
rideQueryService.SetDrivers(driverRepo) // O4/O7:乘客查自己訂單時附司機姓名/電話
chatService := service.NewChatService(rideRepo, rideMessageRepo, hub)
lostItemService := service.NewLostItemService(rideRepo, lostItemRepo, feeSettings, hub)

Expand Down
Original file line number Diff line number Diff line change
@@ -0,0 +1,4 @@
-- DROP COLUMN 會自動連帶刪除依賴該欄位的 CHECK;DROP CONSTRAINT 是明示意圖(IF EXISTS,無害)。
ALTER TABLE rides DROP CONSTRAINT IF EXISTS chk_rides_driver_vehicle_type;
ALTER TABLE rides DROP COLUMN IF EXISTS driver_plate_number;
ALTER TABLE rides DROP COLUMN IF EXISTS driver_vehicle_type;
13 changes: 13 additions & 0 deletions db/migrations/000020_add_ride_driver_vehicle_snapshot.up.sql
Original file line number Diff line number Diff line change
@@ -0,0 +1,13 @@
-- 車輛快照(O7):接單時把司機當下的車種/車牌定格寫進 ride。
--
-- 為什麼要快照而不是 JOIN drivers:司機會換車(O2 的 PUT /api/driver/vehicle 隨時可改),
-- 但歷史行程不能跟著變——乘客三個月後回頭找遺失物時,要知道「當時搭的是哪台車」。
-- 與費率/會費/遺失物處理費的快照制一致。
ALTER TABLE rides ADD COLUMN IF NOT EXISTS driver_vehicle_type TEXT NOT NULL DEFAULT '';
ALTER TABLE rides ADD COLUMN IF NOT EXISTS driver_plate_number TEXT NOT NULL DEFAULT '';

-- 值域同 O1 白名單;'' =尚未接單(或舊資料)。
-- 注意:這裡**不加**車牌唯一索引——快照是歷史紀錄,同一台車本來就會出現在很多趟行程上。
ALTER TABLE rides DROP CONSTRAINT IF EXISTS chk_rides_driver_vehicle_type;
ALTER TABLE rides ADD CONSTRAINT chk_rides_driver_vehicle_type
CHECK (driver_vehicle_type IN ('', 'sedan', 'suv', 'van7', 'accessible', 'pet'));
76 changes: 61 additions & 15 deletions docs/TODO.md
Original file line number Diff line number Diff line change
Expand Up @@ -324,10 +324,18 @@
1. ~~**車資算法**~~ ✅ **已拍板(2026-07-16):採全程實際路線(含繞路)**,見 N5。
衍生風險:乘客建單時看不到預估車資,繞路越多車資越高 → 若日後要「先報價」,
需要一支報價 API(以全程路線試算),目前**沒有**(後端只在完成時定格計費)。
2. **狀態機**:現行 `picked_up` 是單一時間點。多位乘客時「第一位上車」=picked_up?
還是每位各自狀態?影響 F 系列報表與 tracking 的里程計算起點。
2. ~~**狀態機**~~ ✅ **已拍板(2026-07-17):維持單一 `picked_up`=第一位乘客上車**,
其餘乘客不另計行程狀態。理由:F 系列報表、tracking 里程起點、已打通的三端對帳全部不受影響;
`ride_stops.arrived_at`(N1 已含)保留為日後要精確化時的升級路徑。
已知取捨:「行程中」會涵蓋「尚未接到後續乘客」的區段。
3. ~~**上限 5 位**~~ ✅ **已拍板(2026-07-16):5 位「乘客」,各自上下車 → 最多 10 個停靠點**。
4. **取消/缺席**:某位乘客沒出現時,司機能否跳過該停靠點?
4. ~~**取消/缺席**~~ ✅ **已拍板(2026-07-17):司機可標記跳過**(乘客沒出現時)。
→ **N7 因此從「可選」變成必要**:`ride_stops` 需要狀態欄(`arrived_at`/`skipped_at`)
與司機端標記 API。
**對車資的影響(實作推論,非另行拍板):跳過的停靠點不計入 N5 的計費路線**——
N5 的精神是「司機真的開了那些路,繞路不該做白工」;沒去的站就沒開那段路,
計入等於收乘客沒走的路的錢。軌跡那側本來就自然反映(沒去就沒軌跡),
`billableDistanceM` 取大者的邏輯不變。
5. **admin 呈現**:訂單詳情要顯示多個 stops 與軌跡(`line-fleet-admin` 對應項)。

---
Expand Down Expand Up @@ -430,10 +438,12 @@
這兩條路徑的覆蓋完全來自本次新增的測試。日後改動搶單/派單邏輯時別誤以為有既有安全網。
**未驗**:docker compose 全服務 live E2E。

- [ ] **O4. 乘客端可見車輛資訊**
`ride.accepted` payload 與 `GET /api/customer/rides/active` 加
`driver_vehicle_type`/`driver_plate_number`(比照現行 `driver_name` 的送法)。
**隱私**:只在該趟行程的乘客可見(沿用既有 MultiAuth 授權),不可對外公開司機車牌。
- [x] **O4. 乘客端可見車輛資訊** ✅ **已實作(2026-07-17,與 O7 同批)**
三條路徑都帶:`ride.accepted` payload(`rideAcceptedCustomerPayload`)、
`GET /api/customer/rides/active`、`GET /api/customer/rides/:id`(後兩者見 O7 的 `CustomerRideView`)。
送**車種 code** 而非顯示名(O1 原則:顯示名由前端對應)。
**空值不帶該鍵**(而非帶空字串)——寧可少一個鍵,也不要讓 App 顯示空白車牌。
**隱私**:`ride.accepted` 的收件人是 `ride.CustomerID` 一人;查詢類一律先授權再組資料(見 O7)。

- [ ] **O5. admin 呈現/審核(可選)**
司機列表顯示車種車牌;是否需要「車輛審核」狀態(pending/approved)待拍板——
Expand Down Expand Up @@ -515,7 +525,41 @@
**乘客端可見**:完成卡與(若日後有)報價都要**分項顯示**「車資」與「清潔費」,
不可只給總額——使用者明確要求「乘客端要顯示多增加清潔費」。

- [ ] **O7. 車輛快照 + 司機聯絡方式 + 留言板** ✅ **已定案(2026-07-16)**
- [x] **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`(完成或接單時定格)。
Expand Down Expand Up @@ -700,13 +744,15 @@
清潔費依乘客指定車種、上限 30%、**不計入抽成**/不降級+取消原因明確化/customer fees 端點/
**電話明碼、僅該趟乘客可見**)——**N、O、P 規格完備,可開始實作**,
建議順序:O1→O2→O3(車輛地基)→ P1→P2→P3+P4(車種)→ O6+P5(清潔費)→ O4/O7(乘客可見)→ N(多停靠點,最大塊)。
**進度:O1 ✅(2026-07-16)、O2 ✅、O3 ✅、P1 ✅、P2 ✅、P3 ✅、P4 ✅、O6 ✅、P5 ✅(皆 2026-07-17)
→ **P 章節全數完成**;O 章節只剩 **O4(乘客端可見車輛資訊)/O5(admin 呈現,可選)/
O7(車輛快照+司機電話+留言板)**。
寵物車清潔費整條鏈路已通:乘客指定 pet → 只派寵物車 → 完成時依**乘客指定的車種**加收 →
報表分項(營業額不含、抽成不含、全額歸司機)→ `ride.completed` 帶分項 → 乘客可查費率。
下一項建議 **O4+O7**(都是「乘客端可見的司機/車輛資訊」,共用 `ride.accepted` payload 與
rides 快照欄,分開做會改到同一批地方兩次)。**
**進度:O1/O2/O3/O4/O6/O7 ✅、P1–P5 ✅(O1 為 2026-07-16,其餘皆 2026-07-17)
→ **N、O、P 三章中的 O 與 P 已全數完成**,只剩 **O5(admin 呈現/審核,可選、待拍板)**。
後端能力已到位:司機填車輛才能接單 → 乘客指定車種 → 只派同車種、找不到明確取消 →
依乘客指定車種加收清潔費、報表分項 → 乘客看得到車種車牌與司機電話、對話無時間限制。

**下一項建議**:**N(多乘客/多停靠點)**——三章中僅存的大塊,需擴充 OSRM client
支援多 waypoint(現行介面寫死兩點)並讓 haversine 退路逐段累加。
或先補 **下游 UI 同步**(admin 費率頁/月報表分項、App 完成卡分項+車輛資訊+強制填寫跳轉),
否則後端做完的能力在兩端都還看不到。**

計費地基 **F1–F8+F3 里程退路+F9-1~F9-6+M 整數台幣 已全數合併進 main**,三端對帳與 F3/F9-3/F9-4 皆 docker E2E 驗過。
其餘皆屬「量體上升後才需」的大資料量最佳化,勿過早做:
Expand Down
4 changes: 4 additions & 0 deletions internal/model/models.go
Original file line number Diff line number Diff line change
Expand Up @@ -156,6 +156,10 @@ type Ride struct {
// RequiredVehicleType 乘客指定的車種(P1):constants.VehicleType* 之一;'' =不指定(任何車種都可派)。
// 這是清潔費(O6)加收與否的判斷依據——依**乘客要的車種**,不是司機開的車種。
RequiredVehicleType string `gorm:"column:required_vehicle_type;not null;default:''" json:"required_vehicle_type"`
// 車輛快照(O7):接單時定格司機當下的車種/車牌;'' =尚未接單。
// 司機日後換車,歷史行程不會跟著變——乘客回頭找遺失物時要知道「當時搭的是哪台車」。
DriverVehicleType string `gorm:"column:driver_vehicle_type;not null;default:''" json:"driver_vehicle_type"`
DriverPlateNumber string `gorm:"column:driver_plate_number;not null;default:''" json:"driver_plate_number"`
// 計費欄位:完成時定格寫入(費率快照制),一律以「分」儲存;未完成/取消為 nil。
FareAmountCents *int64 `gorm:"column:fare_amount_cents" json:"fare_amount_cents"`
CommissionAmountCents *int64 `gorm:"column:commission_amount_cents" json:"commission_amount_cents"`
Expand Down
20 changes: 15 additions & 5 deletions internal/repository/repository.go
Original file line number Diff line number Diff line change
Expand Up @@ -333,16 +333,26 @@ func (r *RideRepository) UpdateStatus(id int64, status int16) error {
}).Error
}

// AcceptRide 司機接單,並在同一個 UPDATE 內定格車輛快照(O7)。
//
// 快照以子查詢直接自 drivers 複製,而非由呼叫端傳入:
// - 與 driver_id 在同一個 UPDATE 定格,不會有「接了單但快照還沒寫」的中間狀態;
// - 呼叫端不可能傳錯車——快照必然是被指派司機當下的車。
//
// O3 gate 保證接單者一定填了車輛資訊,故正常情況下快照不會是空字串;
// COALESCE 只是防禦司機資料異常時仍滿足 NOT NULL。
func (r *RideRepository) AcceptRide(id, driverID int64, etaSec int) error {
now := time.Now()
return r.db.Model(&model.Ride{}).Where("id = ? AND status IN ?", id,
[]int16{constants.RideStatusRequested, constants.RideStatusAssigned},
).Updates(map[string]interface{}{
"driver_id": driverID,
"status": constants.RideStatusAccepted,
"accepted_at": now,
"eta_pickup_sec": etaSec,
"updated_at": now,
"driver_id": driverID,
"status": constants.RideStatusAccepted,
"accepted_at": now,
"eta_pickup_sec": etaSec,
"driver_vehicle_type": gorm.Expr("COALESCE((SELECT vehicle_type FROM drivers WHERE id = ?), '')", driverID),
"driver_plate_number": gorm.Expr("COALESCE((SELECT plate_number FROM drivers WHERE id = ?), '')", driverID),
"updated_at": now,
}).Error
}

Expand Down
85 changes: 85 additions & 0 deletions internal/service/chat_after_completion_test.go
Original file line number Diff line number Diff line change
@@ -0,0 +1,85 @@
package service

import (
"errors"
"testing"
"time"

"line-fleet-dispatch/internal/constants"
"line-fleet-dispatch/internal/events"
"line-fleet-dispatch/internal/model"
"line-fleet-dispatch/internal/repository"
)

// TestChat_行程完成很久之後仍可對話 O7 的「留言板」=沿用既有 ride_messages,不另建一套。
// 規格要求實作前先釘住這個行為:乘客常常是幾天後才發現東西掉了,
// 那時行程早已完成,對話入口必須還能用(遺失物協尋 H2 就靠這條)。
//
// 現行 authorizeRideParticipant 只看「是不是本趟參與者」,不看狀態也不看時間——
// 這個測試把它變成有意的保證,而不是「碰巧沒擋」。
func TestChat_行程完成很久之後仍可對話(t *testing.T) {
db := newServiceTestDB(t)
drivers := repository.NewDriverRepository(db)
rides := repository.NewRideRepository(db)
customers := repository.NewCustomerRepository(db)
messages := repository.NewRideMessageRepository(db)
fp := &fakePublisher{}
svc := NewChatService(rides, messages, fp)

cust, err := customers.FindOrCreateByLineUserID("U_chat_old", "乘客")
if err != nil {
t.Fatalf("建立乘客失敗:%v", err)
}
driver, err := drivers.FindOrCreate("D_chat_old", "司機")
if err != nil {
t.Fatalf("建立司機失敗:%v", err)
}

// 一趟 90 天前就完成的行程。
long := time.Now().AddDate(0, 0, -90)
ride := &model.Ride{
CustomerID: cust.ID, DriverID: &driver.ID,
Status: constants.RideStatusCompleted,
PickupPoint: model.GeoPoint{Lat: 25.03, Lng: 121.56}, PickupAddress: "台北車站",
RequestedAt: long, CompletedAt: &long, CreatedAt: long, UpdatedAt: long,
}
if err := db.Create(ride).Error; err != nil {
t.Fatalf("建立行程失敗:%v", err)
}

t.Run("乘客仍可發話", func(t *testing.T) {
msg, err := svc.Send(events.RoleCustomer, cust.ID, ride.ID, "請問有看到我的傘嗎?")
if err != nil {
t.Fatalf("完成 90 天後乘客仍應可發話:%v", err)
}
if msg.SenderRole != events.RoleCustomer {
t.Fatalf("sender_role 錯誤:%q", msg.SenderRole)
}
})

t.Run("司機仍可回話", func(t *testing.T) {
if _, err := svc.Send(events.RoleDriver, driver.ID, ride.ID, "有的,明天拿給你"); err != nil {
t.Fatalf("完成 90 天後司機仍應可回話:%v", err)
}
})

t.Run("歷史讀得到", func(t *testing.T) {
list, err := svc.List(events.RoleCustomer, cust.ID, ride.ID, 0, 50)
if err != nil {
t.Fatalf("讀歷史失敗:%v", err)
}
if len(list) != 2 {
t.Fatalf("預期 2 則訊息,得到 %d", len(list))
}
})

t.Run("非參與者仍被擋", func(t *testing.T) {
// 「沒有時間限制」不等於「沒有授權」——路人不得插話或偷看。
if _, err := svc.Send(events.RoleCustomer, 999999, ride.ID, "路人"); !errors.Is(err, ErrForbidden) {
t.Fatalf("非本趟乘客預期 ErrForbidden,得到 %v", err)
}
if _, err := svc.List(events.RoleDriver, 999999, ride.ID, 0, 50); !errors.Is(err, ErrForbidden) {
t.Fatalf("非本趟司機預期 ErrForbidden,得到 %v", err)
}
})
}
28 changes: 27 additions & 1 deletion internal/service/dispatch.go
Original file line number Diff line number Diff line change
Expand Up @@ -169,6 +169,32 @@ func putDropoff(payload map[string]any, ride *model.Ride) {
}
}

// rideAcceptedCustomerPayload 組裝給乘客的 ride.accepted payload(O4/O7)。
//
// 車種與車牌讓乘客在路邊對得到車;電話讓乘客能直接聯絡司機(O7 拍板:明碼)。
// **只送給該趟乘客**——本 payload 的收件人是 ride.CustomerID 一人,
// 司機電話絕不可出現在任何列表或廣播事件上。
//
// 送 code 而非顯示名:前端有自己的車種對照(O1 原則)。
// 車輛欄位在 O3 gate 下必定非空,但仍以 omitempty 式的判斷帶入——
// 舊資料或資料異常時,寧可少一個鍵,也不要讓 App 顯示空白車牌。
func rideAcceptedCustomerPayload(driver *model.Driver, etaSec int) map[string]any {
payload := map[string]any{
"driver_name": driver.Name,
"eta_sec": etaSec,
}
if driver.VehicleType != "" {
payload["driver_vehicle_type"] = driver.VehicleType
}
if driver.PlateNumber != "" {
payload["driver_plate_number"] = driver.PlateNumber
}
if driver.Phone != "" {
payload["driver_phone"] = driver.Phone
}
return payload
}

// rideAssignedPayload 組裝 ride.assigned WS 事件 payload(含選填目的地)。
// pickup 座標與 dropoff 對稱一併帶上:司機端接單當下就要在地圖標出上車點,
// 光靠 address 字串無法定位(PickupPoint 為 not null,必定有值)。
Expand Down Expand Up @@ -458,7 +484,7 @@ func (s *DispatchService) AcceptRide(ctx context.Context, rideID, driverID int64
s.publish(events.Recipient{Role: events.RoleCustomer, ID: ride.CustomerID}, events.Event{
Type: events.TypeRideAccepted,
RideID: rideID,
Payload: map[string]any{"driver_name": driver.Name, "eta_sec": etaSec},
Payload: rideAcceptedCustomerPayload(driver, etaSec),
})
s.publish(events.Recipient{Role: events.RoleDriver, ID: driverID}, events.Event{
Type: events.TypeRideAccepted,
Expand Down
Loading
Loading