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
2 changes: 2 additions & 0 deletions cmd/server/main.go
Original file line number Diff line number Diff line change
Expand Up @@ -73,6 +73,7 @@ func main() {
feeSettingsRepo := repository.NewFeeSettingsRepository(db)
membershipInvoiceRepo := repository.NewMembershipInvoiceRepository(db)
rideMessageRepo := repository.NewRideMessageRepository(db)
rideStopRepo := repository.NewRideStopRepository(db)
lostItemRepo := repository.NewLostItemRepository(db)

// 軌跡分區維護:啟動時預建未來月分區 + 每日排程(避免跨月寫入失敗)
Expand Down Expand Up @@ -128,6 +129,7 @@ func main() {
dispatchService.SetRideEvents(rideEventRepo)
deviceTokenService := service.NewDeviceTokenService(deviceTokenRepo)
rideService := service.NewRideService(customerRepo, rideRepo, redisStore, dispatchService)
rideService.SetStops(rideStopRepo) // N3:多乘客/多停靠點行程
rideService.SetRideEvents(rideEventRepo)
trackingService := service.NewTrackingService(
driverRepo, rideRepo, trackRepo, redisStore, lineClient, dispatchService,
Expand Down
2 changes: 2 additions & 0 deletions db/migrations/000021_create_ride_stops.down.sql
Original file line number Diff line number Diff line change
@@ -0,0 +1,2 @@
-- DROP TABLE 會連帶刪除其上的 CHECK、UNIQUE 與 FK。
DROP TABLE IF EXISTS ride_stops;
34 changes: 34 additions & 0 deletions db/migrations/000021_create_ride_stops.up.sql
Original file line number Diff line number Diff line change
@@ -0,0 +1,34 @@
-- 多乘客/多停靠點行程(N1):一張訂單裡多位同行乘客各自的上/下車點,依序停靠。
-- **不是陌生人拼車**——同一張訂單、不需配對演算法、不需跨訂單分帳。
--
-- 相容性(N1/N3 明確要求):既有單點訂單**不會有任何 ride_stops 列**。
-- rides.pickup_point / dropoff_point 仍是派單、地圖、報表的讀取來源,
-- 多停靠點訂單也照樣寫(第一個 pickup/最終 dropoff),既有路徑一行都不用改。
-- ride_stops 為空 = 舊行為(含 LINE 建的無目的地訂單)。
CREATE TABLE IF NOT EXISTS ride_stops (
id BIGSERIAL PRIMARY KEY,
ride_id BIGINT NOT NULL REFERENCES rides(id) ON DELETE CASCADE,
seq INT NOT NULL,
kind TEXT NOT NULL,
point geography(Point, 4326) NOT NULL,
address TEXT NOT NULL DEFAULT '',
-- passenger_label 給司機辨識用(A/B/C…)。刻意不做值域 CHECK:
-- 它不參與任何邏輯判斷,值髒掉不會算錯錢(不像車種是計費依據)。
passenger_label TEXT NOT NULL DEFAULT '',
-- 停靠點處理狀態(N7):兩個時間欄天然互斥,同時回答「是否發生」與「何時」,
-- 不必再維護一個狀態機。兩者皆 NULL = 尚未處理。
-- skipped_at:乘客沒出現、司機標記跳過(2026-07-17 拍板)。
-- **已跳過的停靠點不計入 N5 的計費路線**——沒去就沒開那段路。
arrived_at TIMESTAMPTZ,
skipped_at TIMESTAMPTZ,
created_at TIMESTAMPTZ NOT NULL DEFAULT NOW(),
updated_at TIMESTAMPTZ NOT NULL DEFAULT NOW(),

CONSTRAINT chk_ride_stops_seq CHECK (seq >= 1),
CONSTRAINT chk_ride_stops_kind CHECK (kind IN ('pickup', 'dropoff')),
-- 同一趟不得有重複順序——seq 是「第幾站」,重複的話「下一站是誰」就沒有答案。
CONSTRAINT uq_ride_stops_ride_seq UNIQUE (ride_id, seq)
);

-- 依序讀取整趟停靠點(司機端行程卡、N5 計費路線)都是 (ride_id, seq) 範圍掃描。
-- UNIQUE 已隱含建立此索引,故不另建。
58 changes: 41 additions & 17 deletions docs/TODO.md
Original file line number Diff line number Diff line change
Expand Up @@ -261,24 +261,48 @@

### 施作項目(嚴格相依,由上而下)

- [ ] **N1. `ride_stops` 資料表**(新 migration)
欄位建議:`ride_id`、`seq`(停靠順序,1..N)、`kind`(pickup/dropoff)、
`point`(geography Point)、`address`、`passenger_label`(A/B/C/D,或 `passenger_name`)、
`arrived_at`(司機到達時間,供軌跡稽核)。
索引 `(ride_id, seq)`;CHECK `seq >= 1`。
**相容性**:既有單點訂單維持只用 `rides.pickup_point`/`dropoff_point`,
`ride_stops` 為空=舊行為(LINE 建的無目的地訂單也走這條)。

- [ ] **N2. 乘客數上限與驗證** ✅ **已定案(2026-07-16):5 位乘客,各自上下車**
→ **最多 5 位乘客、最多 10 個停靠點**(每位一上一下)。上限值放常數或 `fleet_settings`(實作時定)。
驗證:每位乘客必須成對出現 pickup+dropoff;dropoff 的 `seq` 必須大於同一位乘客的 pickup;
最終目的地=`seq` 最大的 dropoff。超過上限回 400。

- [ ] **N3. 建單 API 擴充**(`POST /api/rides`)
- [x] **N1. `ride_stops` 資料表** ✅ **已實作(2026-07-17,migration `000021`)**
`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 列**。

- [x] **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 非白名單/無標籤/座標非法)。

- [x] **N3. 建單 API 擴充**(`POST /api/rides`)✅ **已實作(2026-07-17)**
body 加選填 `stops: [{seq, kind, lat, lng, address, passenger_label}]`。
無 `stops` 時完全維持現行行為(不可破壞既有 App/LINE 建單)。
`rides.pickup_point` 仍寫第一個 pickup、`dropoff_point` 寫最終 dropoff,
讓派單/地圖/報表等既有讀取路徑不必全面改寫。
無 `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`)
派單仍以「第一個上車點」找最近司機(現行邏輯不變)。
Expand Down
19 changes: 19 additions & 0 deletions internal/constants/ride_stop.go
Original file line number Diff line number Diff line change
@@ -0,0 +1,19 @@
package constants

// 停靠點種類(N1)。值域由 DB CHECK `chk_ride_stops_kind` 一併把關。
const (
StopKindPickup = "pickup" // 該位乘客的上車點
StopKindDropoff = "dropoff" // 該位乘客的下車點
)

// 多乘客/多停靠點上限(N2 拍板 2026-07-16):
// **5 位乘客、各自一上一下 → 最多 10 個停靠點**。
const (
MaxRidePassengers = 5
MaxRideStops = MaxRidePassengers * 2
)

// IsValidStopKind 是否為合法的停靠點種類。
func IsValidStopKind(s string) bool {
return s == StopKindPickup || s == StopKindDropoff
}
33 changes: 32 additions & 1 deletion internal/handler/ride.go
Original file line number Diff line number Diff line change
Expand Up @@ -153,11 +153,33 @@ func (h *RideHandler) Create(c *gin.Context) {
DropoffLng *float64 `json:"dropoff_lng"`
// 選填(P2):未帶=不指定車種,維持現行行為,既有 App/LINE 建單不受影響。
RequiredVehicleType string `json:"required_vehicle_type"`
// 選填(N3):多乘客/多停靠點行程。未帶=傳統單點訂單。
// 有帶時 pickup/dropoff 由 stops 推導(第一個 pickup/最終 dropoff),
// 此時上面的 pickup_lat/lng 等欄位會被忽略。
Stops []struct {
Seq int `json:"seq"`
Kind string `json:"kind"` // pickup / dropoff
Lat float64 `json:"lat"`
Lng float64 `json:"lng"`
Address string `json:"address"`
PassengerLabel string `json:"passenger_label"`
} `json:"stops"`
}
if err := c.ShouldBindJSON(&req); err != nil {
c.JSON(http.StatusBadRequest, gin.H{"error": "參數錯誤"})
return
}
stops := make([]service.StopInput, 0, len(req.Stops))
for _, s := range req.Stops {
stops = append(stops, service.StopInput{
Seq: s.Seq,
Kind: s.Kind,
Lat: s.Lat,
Lng: s.Lng,
Address: s.Address,
PassengerLabel: s.PassengerLabel,
})
}
ride, err := h.rideService.CreateByCustomer(
c.Request.Context(), customerID, service.CustomerCreateRequest{
PickupLat: req.PickupLat,
Expand All @@ -167,6 +189,7 @@ func (h *RideHandler) Create(c *gin.Context) {
DropoffLat: req.DropoffLat,
DropoffLng: req.DropoffLng,
RequiredVehicleType: req.RequiredVehicleType,
Stops: stops,
},
)
if err != nil {
Expand All @@ -179,8 +202,16 @@ func (h *RideHandler) Create(c *gin.Context) {
// createStatusForErr 將下單錯誤對應到 HTTP 狀態碼。
func createStatusForErr(err error) int {
switch {
case errors.Is(err, service.ErrInvalidCoords), errors.Is(err, service.ErrInvalidVehicleType):
case errors.Is(err, service.ErrInvalidCoords), errors.Is(err, service.ErrInvalidVehicleType),
// 停靠點填錯是乘客的輸入問題(N2)→ 400,錯誤訊息本身已說明錯在哪。
errors.Is(err, service.ErrTooManyStops), errors.Is(err, service.ErrTooManyPassengers),
errors.Is(err, service.ErrInvalidStopKind), errors.Is(err, service.ErrDuplicateStopSeq),
errors.Is(err, service.ErrUnpairedStop), errors.Is(err, service.ErrDropoffBeforePickup),
errors.Is(err, service.ErrMissingPassenger):
return http.StatusBadRequest
case errors.Is(err, service.ErrStopsUnavailable):
// 這是伺服器沒接好,不是乘客填錯——不可回 400 讓乘客以為是自己的問題。
return http.StatusServiceUnavailable
case errors.Is(err, service.ErrActiveRideExists):
return http.StatusConflict
case errors.Is(err, service.ErrRateLimited):
Expand Down
37 changes: 37 additions & 0 deletions internal/model/models.go
Original file line number Diff line number Diff line change
Expand Up @@ -210,6 +210,43 @@ func (MembershipInvoice) TableName() string {
return "membership_invoices"
}

// RideStop 多乘客/多停靠點行程的單一停靠點(N1)。
// 一趟的停靠點依 Seq 由小到大依序造訪;**ride_stops 為空 = 傳統單點訂單**(既有行為)。
type RideStop struct {
ID int64 `gorm:"primaryKey" json:"id"`
RideID int64 `gorm:"column:ride_id;not null" json:"ride_id"`
// Seq 停靠順序,1 起算;同一趟內唯一(uq_ride_stops_ride_seq)——
// 重複的話「下一站是誰」就沒有答案。
Seq int `gorm:"column:seq;not null" json:"seq"`
Kind string `gorm:"column:kind;not null" json:"kind"` // constants.StopKind*
// Point 停靠點座標。地址僅供顯示,導航與計費一律吃座標。
Point GeoPoint `gorm:"column:point;type:geography(Point,4326);not null" json:"point"`
Address string `gorm:"not null;default:''" json:"address"`
// PassengerLabel 給司機辨識用(A/B/C…);不參與邏輯判斷,故無值域限制。
PassengerLabel string `gorm:"column:passenger_label;not null;default:''" json:"passenger_label"`
// ArrivedAt/SkippedAt 停靠點處理狀態(N7):互斥,皆 nil = 尚未處理。
// SkippedAt 非 nil = 乘客沒出現、司機標記跳過 → **不計入 N5 的計費路線**
// (沒去就沒開那段路,計入等於收乘客沒走的路的錢)。
ArrivedAt *time.Time `gorm:"column:arrived_at" json:"arrived_at"`
SkippedAt *time.Time `gorm:"column:skipped_at" json:"skipped_at"`
CreatedAt time.Time `gorm:"not null" json:"created_at"`
UpdatedAt time.Time `gorm:"not null" json:"updated_at"`
}

func (RideStop) TableName() string {
return "ride_stops"
}

// Pending 尚未處理(未到達也未跳過)。
func (s RideStop) Pending() bool {
return s.ArrivedAt == nil && s.SkippedAt == nil
}

// Skipped 乘客沒出現、已被司機跳過;N5 計費路線不算這一段。
func (s RideStop) Skipped() bool {
return s.SkippedAt != nil
}

// RideMessage 行程內對話訊息(乘客↔司機)。即時遞送走 WebSocket(chat.message),本表為歷史真源。
type RideMessage struct {
ID int64 `gorm:"primaryKey" json:"id"`
Expand Down
56 changes: 56 additions & 0 deletions internal/repository/ride_stop.go
Original file line number Diff line number Diff line change
@@ -0,0 +1,56 @@
package repository

import (
"time"

"gorm.io/gorm"

"line-fleet-dispatch/internal/model"
)

// RideStopRepository 多停靠點(N1)讀寫。
type RideStopRepository struct {
db *gorm.DB
}

func NewRideStopRepository(db *gorm.DB) *RideStopRepository {
return &RideStopRepository{db: db}
}

// StopRow 落庫用的單一停靠點(座標分開傳,因為要走 ST_MakePoint)。
type StopRow struct {
Seq int
Kind string
Lat, Lng float64
Address string
PassengerLabel string
}

// CreateForRide 批次寫入某趟的停靠點。
// 呼叫端(RideService.CreateByCustomer)負責先驗證配對與上限。
func (r *RideStopRepository) CreateForRide(rideID int64, rows []StopRow) error {
if len(rows) == 0 {
return nil
}
now := time.Now()
return r.db.Transaction(func(tx *gorm.DB) error {
for _, s := range rows {
// 座標走 ST_MakePoint(lng, lat)——與 rides 的寫法一致(經度在前)。
err := tx.Exec(`
INSERT INTO ride_stops (ride_id, seq, kind, point, address, passenger_label, created_at, updated_at)
VALUES (?, ?, ?, ST_SetSRID(ST_MakePoint(?, ?), 4326)::geography, ?, ?, ?, ?)
`, rideID, s.Seq, s.Kind, s.Lng, s.Lat, s.Address, s.PassengerLabel, now, now).Error
if err != nil {
return err
}
}
return nil
})
}

// ListByRide 依 seq 由小到大回傳整趟停靠點;單點訂單回空 slice(非錯誤)。
func (r *RideStopRepository) ListByRide(rideID int64) ([]model.RideStop, error) {
var stops []model.RideStop
err := r.db.Where("ride_id = ?", rideID).Order("seq ASC").Find(&stops).Error
return stops, err
}
Loading
Loading