From 7e54b019206ed886aa93e76d453ca0e4785ab333 Mon Sep 17 00:00:00 2001 From: awei Date: Fri, 17 Jul 2026 09:23:13 +0800 Subject: [PATCH 1/3] =?UTF-8?q?feat(O2):=20=E5=8F=B8=E6=A9=9F=E8=BB=8A?= =?UTF-8?q?=E8=BC=9B=E8=B3=87=E8=A8=8A=20API=EF=BC=88GET/PUT=20/api/driver?= =?UTF-8?q?/vehicle=EF=BC=89?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 車牌格式拍板:寬鬆驗證(長度 2-10+字元集 A-Z/0-9/-,不綁樣式)。 台灣車牌多代並存,硬綁正則會誤擋真車牌;髒值由 O3 gate 兜底。 - constants:NormalizePlateNumber(去空白+轉大寫)+ IsValidPlateNumber。 正規化是 uq_drivers_plate_number(O1)的前提,否則同車以大小寫各佔一列。 - repository.UpdateVehicle:唯一索引衝突翻成 ErrPlateTaken(handler 回 409 而非 500), 以 pgconn SQLSTATE 23505 + 約束名判斷,不比對錯誤訊息字串。 - service.SetVehicle:車種白名單+車牌驗證,驗證失敗不寫入。 - handler:回應帶 has_vehicle(與 O3 gate 同一條件),400/409/404 分流。 驗收:build/vet/gofmt 綠;constants 單元測試、handler 授權與參數驗證測試、 service+repository 真 PostGIS 整合測試全綠。反向驗證:拿掉衝突翻譯或 正規化,對應測試皆 FAIL。 Co-Authored-By: Claude Opus 4.8 --- cmd/server/main.go | 2 + docs/TODO.md | 34 ++++++- go.mod | 4 +- internal/constants/vehicle.go | 47 ++++++++++ internal/constants/vehicle_test.go | 39 ++++++++ internal/handler/driver.go | 51 +++++++++++ internal/handler/driver_vehicle_test.go | 84 +++++++++++++++++ .../driver_vehicle_integration_test.go | 56 ++++++++++++ internal/repository/repository.go | 32 +++++++ internal/service/driver_registry.go | 28 ++++++ internal/service/driver_vehicle_test.go | 90 +++++++++++++++++++ internal/service/errors.go | 2 + 12 files changed, 464 insertions(+), 5 deletions(-) create mode 100644 internal/handler/driver_vehicle_test.go create mode 100644 internal/service/driver_vehicle_test.go diff --git a/cmd/server/main.go b/cmd/server/main.go index 292ad1b..597edb6 100644 --- a/cmd/server/main.go +++ b/cmd/server/main.go @@ -220,6 +220,8 @@ func main() { authed.Use(middleware.DriverAuth(cfg.JWTSecret)) { authed.GET("/driver/me", driverHandler.Me) + authed.GET("/driver/vehicle", driverHandler.Vehicle) + authed.PUT("/driver/vehicle", driverHandler.UpdateVehicle) authed.GET("/driver/earnings", driverHandler.Earnings) authed.POST("/driver/online", driverHandler.Online) authed.POST("/driver/offline", driverHandler.Offline) diff --git a/docs/TODO.md b/docs/TODO.md index 7d3f0c8..2c7486b 100644 --- a/docs/TODO.md +++ b/docs/TODO.md @@ -374,9 +374,36 @@ **順帶記錄的 Postgres 行為**:`DROP COLUMN` 會自動連帶刪除依賴該欄位的 CHECK 與 index, 故 down 裡的 `DROP CONSTRAINT`/`DROP INDEX` 其實冗餘——保留是為了明示意圖(`IF EXISTS`,無害)。 -- [ ] **O2. 車輛資訊 API** - `GET/PUT /api/driver/vehicle`(driver JWT,只能改自己的)。 - 驗證:車種必填、車牌必填且格式檢查(台灣車牌格式待拍板,例如 `ABC-1234`/`1234-AB`)。 +- [x] **O2. 車輛資訊 API** ✅ **已實作(2026-07-17)** + `GET/PUT /api/driver/vehicle`(driver JWT,`driver_id` 一律取自 token,只能改自己的)。 + 回應形狀 `{vehicle_type, plate_number, has_vehicle}`——附 `has_vehicle` 是為了讓 App + 不必自行判斷「兩欄皆非空」,與 O3 gate 用同一條件(`model.Driver.HasVehicle()`)。 + 未設定時兩欄回空字串、`has_vehicle=false`,非錯誤。 + + **車牌格式 ✅ 拍板(2026-07-17):寬鬆驗證** + 只檢查長度(2–10)與字元集(半形 `A-Z`/`0-9`/`-`,至少一個英數字),**不綁特定樣式**。 + 台灣車牌多代並存(`ABC-1234`/`1234-AB`/`AB-1234`/電動車/機車格式), + 硬綁正則會誤擋真車牌;擋不住的髒值由 O3 gate 與人工審核(O5,若做)兜底。 + 實作在 `constants.IsValidPlateNumber`/`NormalizePlateNumber`(去空白+轉大寫)。 + **正規化是唯一索引的前提**:不轉大寫去空白,同一台車會以 + 「abc-1234」「ABC-1234」各佔一列,`uq_drivers_plate_number`(O1)形同虛設。 + + **狀態碼**:車種非白名單/車牌格式錯/任一為空 → 400;車牌已被他人使用 → **409**; + 司機不存在 → 404。409 的關鍵是 `repository.UpdateVehicle` 把唯一索引衝突翻成 + `ErrPlateTaken`——原樣往上丟會變 500,司機看到「伺服器錯誤」而無從修正。 + 衝突判斷用 `pgconn.PgError` 的 SQLSTATE `23505` +約束名,**不比對錯誤訊息字串** + (訊息隨 Postgres 版本/語系變動);`jackc/pgx/v5` 因此從 indirect 升為 direct 依賴。 + + **驗收**:`go build`/`vet`/`gofmt` 綠。 + `internal/constants` 單元測試(正規化、寬鬆驗證的合法/非法各案,含全形字元不視為合法); + `internal/handler` 測試(授權邊界:無 token/customer token 皆 401;參數驗證 8 案皆 400); + `internal/service` 整合測試 `TestDriverSetVehicle`(真 PostGIS:正規化後才寫入、 + 驗證失敗不留半套資料、大小寫不同但同一車牌仍撞 `ErrPlateTaken`、司機不存在回 `ErrNotFound`); + `internal/repository` 整合測試 `TestDriverRepositoryUpdateVehicle`(寫入、`ErrPlateTaken`、 + 同一司機沿用自己車牌換車種不算衝突)。 + **反向驗證**:拿掉衝突翻譯 → 錯誤原樣為 SQLSTATE 23505,對應測試 FAIL; + 拿掉 `NormalizePlateNumber` → 正規化與車牌衝突兩案 FAIL。 + **未驗**:docker compose 起全服務的 live E2E(單元+整合已覆蓋,留待 O3 一起跑)。 - [ ] **O3. 接單前置檢查(gate)** ✅ **已定案(2026-07-16):強制填寫,無寬限期** **後端強制**:無車輛資訊的司機不得被派單(`dispatch.go` 候選司機過濾) @@ -548,6 +575,7 @@ 清潔費依乘客指定車種、上限 30%、**不計入抽成**/不降級+取消原因明確化/customer fees 端點/ **電話明碼、僅該趟乘客可見**)——**N、O、P 規格完備,可開始實作**, 建議順序:O1→O2→O3(車輛地基)→ P1→P2→P3+P4(車種)→ O6+P5(清潔費)→ O4/O7(乘客可見)→ N(多停靠點,最大塊)。 + **進度:O1 ✅(2026-07-16)、O2 ✅(2026-07-17,含車牌寬鬆驗證拍板)→ 下一項是 O3(接單 gate)。** 計費地基 **F1–F8+F3 里程退路+F9-1~F9-6+M 整數台幣 已全數合併進 main**,三端對帳與 F3/F9-3/F9-4 皆 docker E2E 驗過。 其餘皆屬「量體上升後才需」的大資料量最佳化,勿過早做: diff --git a/go.mod b/go.mod index 70f23d3..5b78226 100644 --- a/go.mod +++ b/go.mod @@ -6,6 +6,8 @@ require ( github.com/gin-gonic/gin v1.12.0 github.com/golang-jwt/jwt/v5 v5.3.1 github.com/golang-migrate/migrate/v4 v4.19.1 + github.com/gorilla/websocket v1.5.3 + github.com/jackc/pgx/v5 v5.9.2 github.com/redis/go-redis/v9 v9.21.0 github.com/rs/zerolog v1.35.1 github.com/testcontainers/testcontainers-go/modules/postgres v0.43.0 @@ -47,10 +49,8 @@ require ( github.com/goccy/go-json v0.10.5 // indirect github.com/goccy/go-yaml v1.19.2 // indirect github.com/google/uuid v1.6.0 // indirect - github.com/gorilla/websocket v1.5.3 // indirect github.com/jackc/pgpassfile v1.0.0 // indirect github.com/jackc/pgservicefile v0.0.0-20240606120523-5a60cdf6a761 // indirect - github.com/jackc/pgx/v5 v5.9.2 // indirect github.com/jackc/puddle/v2 v2.2.2 // indirect github.com/jinzhu/inflection v1.0.0 // indirect github.com/jinzhu/now v1.1.5 // indirect diff --git a/internal/constants/vehicle.go b/internal/constants/vehicle.go index 7343170..c9d0cf0 100644 --- a/internal/constants/vehicle.go +++ b/internal/constants/vehicle.go @@ -1,5 +1,10 @@ package constants +import ( + "strings" + "unicode" +) + // 車種 code(O1 定案 2026-07-16)。後端只認 code,顯示名稱由前端對應 // (轎車/休旅/七人座/無障礙/寵物用車)。 // 值域同時由 DB CHECK `chk_drivers_vehicle_type` 把關(migration 000017)—— @@ -38,3 +43,45 @@ func IsValidVehicleType(s string) bool { } return false } + +// 車牌長度界線(正規化後)。台灣現行最長為 `ABC-1234`(8 碼), +// 放寬到 10 是為了容納舊式與特殊車牌。 +const ( + MinPlateLen = 2 + MaxPlateLen = 10 +) + +// NormalizePlateNumber 去掉所有空白並轉大寫,作為寫入 DB 的正規形式。 +// 車牌非空時有唯一索引(O1),不正規化會讓「abc-1234」與「ABC-1234」被當成兩台車。 +func NormalizePlateNumber(s string) string { + var b strings.Builder + for _, r := range s { + if unicode.IsSpace(r) { + continue + } + b.WriteRune(unicode.ToUpper(r)) + } + return b.String() +} + +// IsValidPlateNumber 寬鬆驗證(O2 拍板 2026-07-17):只檢查長度與字元集 +// (半形 A-Z、0-9、`-`,且至少有一個英數字),不綁特定樣式。 +// 台灣車牌樣式多代並存(ABC-1234/1234-AB/AB-1234/電動車/機車格式), +// 硬綁正則會誤擋真車牌,而擋不住的髒值本來就由 O3 gate 與人工審核(O5)兜底。 +// 傳入值須為 NormalizePlateNumber 的輸出(全形字元不會被轉半形,會在此被判為非法)。 +func IsValidPlateNumber(s string) bool { + if len(s) < MinPlateLen || len(s) > MaxPlateLen { + return false + } + hasAlnum := false + for _, r := range s { + switch { + case r >= 'A' && r <= 'Z', r >= '0' && r <= '9': + hasAlnum = true + case r == '-': + default: + return false + } + } + return hasAlnum +} diff --git a/internal/constants/vehicle_test.go b/internal/constants/vehicle_test.go index cfce3a5..b8cdcd3 100644 --- a/internal/constants/vehicle_test.go +++ b/internal/constants/vehicle_test.go @@ -16,6 +16,45 @@ func TestIsValidVehicleType(t *testing.T) { } } +func TestNormalizePlateNumber(t *testing.T) { + cases := map[string]string{ + "abc-1234": "ABC-1234", + " ABC-1234 ": "ABC-1234", + "abc 1234": "ABC1234", + "": "", + } + for in, want := range cases { + // 正規化是車牌唯一索引(uq_drivers_plate_number)的前提: + // 不轉大寫去空白,同一台車會以多種寫法各佔一列。 + if got := NormalizePlateNumber(in); got != want { + t.Fatalf("NormalizePlateNumber(%q) = %q,預期 %q", in, got, want) + } + } +} + +func TestIsValidPlateNumber(t *testing.T) { + // 寬鬆驗證(O2 拍板):台灣車牌多代並存,只檢查長度與字元集,不綁樣式。 + for _, v := range []string{"ABC-1234", "1234-AB", "AB-1234", "EAA-0001", "123-AB", "AB", "0000000000"} { + if !IsValidPlateNumber(v) { + t.Fatalf("%q 應為合法車牌", v) + } + } + for _, v := range []string{ + "", // 空=未設定,不得當合法值(會繞過 O3 gate) + "A", // 短於 MinPlateLen + "ABCD-123456", // 長於 MaxPlateLen + "---", // 全連字號、無英數字 + "ABC 1234", // 未正規化(含空白) + "ABC-1234", // 全形字元不視為合法,需以半形輸入 + "ABC_1234", // 非允許字元 + "ABC-1234;DROP", // 過長且含非法字元 + } { + if IsValidPlateNumber(v) { + t.Fatalf("%q 不該被當成合法車牌", v) + } + } +} + func TestVehicleTypesIsDefensiveCopy(t *testing.T) { got := VehicleTypes() if len(got) != 5 { diff --git a/internal/handler/driver.go b/internal/handler/driver.go index 34b2c42..f0bf540 100644 --- a/internal/handler/driver.go +++ b/internal/handler/driver.go @@ -68,6 +68,57 @@ func (h *DriverHandler) Me(c *gin.Context) { c.JSON(http.StatusOK, driverPublic(d)) } +// driverVehicle 車輛資訊的回應形狀(O2)。附 `has_vehicle` 讓 App 不必自行判斷 +// 「兩欄皆非空」就知道能不能接單(與 O3 gate 同一條件)。 +func driverVehicle(d *model.Driver) gin.H { + return gin.H{ + "vehicle_type": d.VehicleType, + "plate_number": d.PlateNumber, + "has_vehicle": d.HasVehicle(), + } +} + +// Vehicle GET /api/driver/vehicle — 司機自己的車輛資訊(O2)。 +// 未設定時兩欄為空字串、has_vehicle=false,非錯誤。 +func (h *DriverHandler) Vehicle(c *gin.Context) { + driverID := middleware.DriverIDFromCtx(c) + d, err := h.drivers.Me(driverID) + if err != nil { + c.JSON(http.StatusNotFound, gin.H{"error": "找不到司機"}) + return + } + c.JSON(http.StatusOK, driverVehicle(d)) +} + +// UpdateVehicle PUT /api/driver/vehicle — 設定車種與車牌(O2)。 +// driver_id 一律取自 token,司機只能改自己的;車牌已被別人用走回 409。 +func (h *DriverHandler) UpdateVehicle(c *gin.Context) { + driverID := middleware.DriverIDFromCtx(c) + var req struct { + VehicleType string `json:"vehicle_type" binding:"required"` + PlateNumber string `json:"plate_number" binding:"required"` + } + if err := c.ShouldBindJSON(&req); err != nil { + c.JSON(http.StatusBadRequest, gin.H{"error": "參數錯誤"}) + return + } + d, err := h.drivers.SetVehicle(driverID, req.VehicleType, req.PlateNumber) + if err != nil { + switch { + case errors.Is(err, service.ErrInvalidVehicleType), errors.Is(err, service.ErrInvalidPlateNumber): + c.JSON(http.StatusBadRequest, gin.H{"error": err.Error()}) + case errors.Is(err, repository.ErrPlateTaken): + c.JSON(http.StatusConflict, gin.H{"error": err.Error()}) + case errors.Is(err, service.ErrNotFound): + c.JSON(http.StatusNotFound, gin.H{"error": "找不到司機"}) + default: + c.JSON(http.StatusInternalServerError, gin.H{"error": err.Error()}) + } + return + } + c.JSON(http.StatusOK, driverVehicle(d)) +} + // Earnings GET /api/driver/earnings?month=2026-07 — 司機當月收入(F7) // 回傳趟數、營業額、手續費、司機實得、月會費、應付總公司(皆為「分」)。 func (h *DriverHandler) Earnings(c *gin.Context) { diff --git a/internal/handler/driver_vehicle_test.go b/internal/handler/driver_vehicle_test.go new file mode 100644 index 0000000..476cb8a --- /dev/null +++ b/internal/handler/driver_vehicle_test.go @@ -0,0 +1,84 @@ +package handler + +import ( + "net/http" + "net/http/httptest" + "strings" + "testing" + "time" + + "github.com/gin-gonic/gin" + + "line-fleet-dispatch/internal/auth" + "line-fleet-dispatch/internal/middleware" + "line-fleet-dispatch/internal/service" +) + +// setupVehicleRouter 以 nil repo 的 DriverRegistry 建路由:驗證失敗的路徑在碰 DB 前就回, +// 故不需要真連線。成功寫入/車牌衝突(409)由 repository 整合測試覆蓋。 +func setupVehicleRouter() *gin.Engine { + gin.SetMode(gin.TestMode) + h := NewDriverHandler(nil, service.NewDriverRegistry(nil), nil, "s", 1) + r := gin.New() + g := r.Group("/api") + g.Use(middleware.DriverAuth("s")) + { + g.GET("/driver/vehicle", h.Vehicle) + g.PUT("/driver/vehicle", h.UpdateVehicle) + } + return r +} + +func putVehicle(t *testing.T, r *gin.Engine, token, body string) *httptest.ResponseRecorder { + t.Helper() + w := httptest.NewRecorder() + req, _ := http.NewRequest("PUT", "/api/driver/vehicle", strings.NewReader(body)) + req.Header.Set("Content-Type", "application/json") + if token != "" { + req.Header.Set("Authorization", "Bearer "+token) + } + r.ServeHTTP(w, req) + return w +} + +func TestDriverVehicle_授權邊界(t *testing.T) { + r := setupVehicleRouter() + + if w := putVehicle(t, r, "", `{"vehicle_type":"sedan","plate_number":"ABC-1234"}`); w.Code != http.StatusUnauthorized { + t.Fatalf("無 token 預期 401,得到 %d", w.Code) + } + + // 車輛資訊只有司機本人能改;customer token 走 DriverAuth 視為無效。 + ctok, _ := auth.GenerateToken("customer", 9, "s", time.Hour) + if w := putVehicle(t, r, ctok, `{"vehicle_type":"sedan","plate_number":"ABC-1234"}`); w.Code != http.StatusUnauthorized { + t.Fatalf("customer token 打 driver 端點預期 401,得到 %d", w.Code) + } +} + +func TestDriverVehicle_參數驗證(t *testing.T) { + r := setupVehicleRouter() + dtok, _ := auth.GenerateDriverToken(7, "s", time.Hour) + + cases := []struct { + name string + body string + }{ + {"壞 JSON", `{bad`}, + {"缺車種", `{"plate_number":"ABC-1234"}`}, + {"缺車牌", `{"vehicle_type":"sedan"}`}, + // 空值等同「未設定」:若被當成合法輸入寫入,司機就繞過了 O3 的接單 gate。 + {"車種空字串", `{"vehicle_type":"","plate_number":"ABC-1234"}`}, + {"車牌空字串", `{"vehicle_type":"sedan","plate_number":""}`}, + // 車種是清潔費(O6)與派單過濾(P3)的判斷依據,不得收白名單外的值。 + {"車種非白名單", `{"vehicle_type":"spaceship","plate_number":"ABC-1234"}`}, + {"車牌含非法字元", `{"vehicle_type":"sedan","plate_number":"ABC_1234"}`}, + {"車牌過長", `{"vehicle_type":"sedan","plate_number":"ABCD-123456"}`}, + } + for _, tc := range cases { + t.Run(tc.name, func(t *testing.T) { + if w := putVehicle(t, r, dtok, tc.body); w.Code != http.StatusBadRequest { + t.Fatalf("預期 400,得到 %d(body: %s)", w.Code, w.Body.String()) + } + }) + } +} diff --git a/internal/repository/driver_vehicle_integration_test.go b/internal/repository/driver_vehicle_integration_test.go index 16e3f80..a88c673 100644 --- a/internal/repository/driver_vehicle_integration_test.go +++ b/internal/repository/driver_vehicle_integration_test.go @@ -1,6 +1,7 @@ package repository import ( + "errors" "strings" "testing" @@ -61,3 +62,58 @@ func TestDriverVehicleSchema(t *testing.T) { } }) } + +// O2:UpdateVehicle 的寫入與唯一鍵衝突翻譯。 +func TestDriverRepositoryUpdateVehicle(t *testing.T) { + db := newMigratedTestDB(t) + repo := NewDriverRepository(db) + + create := func(lineID string) *model.Driver { + d := &model.Driver{LineUserID: lineID, Name: "測試司機"} + if err := db.Create(d).Error; err != nil { + t.Fatalf("建立司機失敗: %v", err) + } + return d + } + + t.Run("寫入車種車牌", func(t *testing.T) { + d := create("u_upd_1") + if err := repo.UpdateVehicle(d.ID, "pet", "ABC-1234"); err != nil { + t.Fatalf("更新車輛資訊應成功: %v", err) + } + got, err := repo.FindByID(d.ID) + if err != nil { + t.Fatalf("重讀司機失敗: %v", err) + } + if got.VehicleType != "pet" || got.PlateNumber != "ABC-1234" { + t.Fatalf("車輛資訊未寫入,得到 %q / %q", got.VehicleType, got.PlateNumber) + } + if !got.HasVehicle() { + t.Fatal("填妥車種車牌後 HasVehicle() 應為 true(O3 gate 的條件)") + } + }) + + t.Run("車牌被別人用走回 ErrPlateTaken", func(t *testing.T) { + // 唯一索引衝突若原樣往上丟,handler 會回 500;司機看到的是「伺服器錯誤」 + // 而非「這張車牌已被使用」,無從修正。 + owner := create("u_upd_owner") + if err := repo.UpdateVehicle(owner.ID, "sedan", "XYZ-5678"); err != nil { + t.Fatalf("第一位司機設定車牌應成功: %v", err) + } + other := create("u_upd_other") + err := repo.UpdateVehicle(other.ID, "suv", "XYZ-5678") + if !errors.Is(err, ErrPlateTaken) { + t.Fatalf("預期 ErrPlateTaken,得到 %v", err) + } + }) + + t.Run("同一司機重設同一車牌不算衝突", func(t *testing.T) { + d := create("u_upd_same") + if err := repo.UpdateVehicle(d.ID, "sedan", "SAME-001"); err != nil { + t.Fatalf("首次設定應成功: %v", err) + } + if err := repo.UpdateVehicle(d.ID, "suv", "SAME-001"); err != nil { + t.Fatalf("同一司機沿用自己的車牌換車種應成功: %v", err) + } + }) +} diff --git a/internal/repository/repository.go b/internal/repository/repository.go index df025be..66b9cd3 100644 --- a/internal/repository/repository.go +++ b/internal/repository/repository.go @@ -5,6 +5,7 @@ import ( "fmt" "time" + "github.com/jackc/pgx/v5/pgconn" "gorm.io/gorm" "gorm.io/gorm/clause" @@ -12,6 +13,9 @@ import ( "line-fleet-dispatch/internal/model" ) +// pgUniqueViolation Postgres 唯一鍵衝突的 SQLSTATE。 +const pgUniqueViolation = "23505" + type CustomerRepository struct { db *gorm.DB } @@ -201,6 +205,34 @@ func (r *DriverRepository) UpdateStatus(id int64, status int16) error { }).Error } +// ErrPlateTaken 車牌已掛在別的司機帳號上(uq_drivers_plate_number,O1)。 +var ErrPlateTaken = errors.New("此車牌已被其他司機使用") + +// UpdateVehicle 更新司機車輛資訊(O2)。呼叫端負責驗證車種白名單與車牌格式; +// 值域仍由 DB CHECK 與 partial unique index 兜底。 +// 撞到車牌唯一索引時翻成 ErrPlateTaken,讓 handler 能回 409 而非 500。 +func (r *DriverRepository) UpdateVehicle(id int64, vehicleType, plateNumber string) error { + err := r.db.Model(&model.Driver{}).Where("id = ?", id).Updates(map[string]interface{}{ + "vehicle_type": vehicleType, + "plate_number": plateNumber, + "updated_at": time.Now(), + }).Error + if isPlateConflict(err) { + return ErrPlateTaken + } + return err +} + +// isPlateConflict 判斷是否為車牌唯一索引衝突。以 PgError 的 code + 約束名判斷, +// 不比對錯誤訊息字串(訊息會隨 Postgres 版本/語系變動)。 +func isPlateConflict(err error) bool { + var pgErr *pgconn.PgError + if !errors.As(err, &pgErr) { + return false + } + return pgErr.Code == pgUniqueViolation && pgErr.ConstraintName == "uq_drivers_plate_number" +} + func (r *DriverRepository) SetPassword(id int64, passwordHash string) error { return r.db.Model(&model.Driver{}).Where("id = ?", id).Updates(map[string]interface{}{ "password_hash": passwordHash, diff --git a/internal/service/driver_registry.go b/internal/service/driver_registry.go index f6c562c..c07d302 100644 --- a/internal/service/driver_registry.go +++ b/internal/service/driver_registry.go @@ -2,8 +2,10 @@ package service import ( "context" + "errors" "golang.org/x/crypto/bcrypt" + "gorm.io/gorm" "line-fleet-dispatch/internal/constants" "line-fleet-dispatch/internal/model" @@ -56,6 +58,32 @@ func (s *DriverRegistry) Me(driverID int64) (*model.Driver, error) { return s.drivers.FindByID(driverID) } +// SetVehicle 設定司機車輛資訊(O2):車種須為白名單 code,車牌正規化後做寬鬆格式檢查。 +// 兩者皆必填——留空等同「未設定」,會讓司機繞過 O3 的接單 gate。 +// 車牌與其他司機重複時回 repository.ErrPlateTaken。 +func (s *DriverRegistry) SetVehicle(driverID int64, vehicleType, plateNumber string) (*model.Driver, error) { + if !constants.IsValidVehicleType(vehicleType) { + return nil, ErrInvalidVehicleType + } + plate := constants.NormalizePlateNumber(plateNumber) + if !constants.IsValidPlateNumber(plate) { + return nil, ErrInvalidPlateNumber + } + d, err := s.drivers.FindByID(driverID) + if err != nil { + if errors.Is(err, gorm.ErrRecordNotFound) { + return nil, ErrNotFound + } + return nil, err + } + if err := s.drivers.UpdateVehicle(driverID, vehicleType, plate); err != nil { + return nil, err + } + d.VehicleType = vehicleType + d.PlateNumber = plate + return d, nil +} + // GoOnline 顯式上線:設為待命(Idle),重新進入派單池。 // 載客中(OnTrip)則維持原狀不降級;已停用(Disabled)回 ErrDriverDisabled。 func (s *DriverRegistry) GoOnline(driverID int64) (*model.Driver, error) { diff --git a/internal/service/driver_vehicle_test.go b/internal/service/driver_vehicle_test.go new file mode 100644 index 0000000..994194c --- /dev/null +++ b/internal/service/driver_vehicle_test.go @@ -0,0 +1,90 @@ +package service + +import ( + "errors" + "testing" + + "line-fleet-dispatch/internal/repository" +) + +// TestDriverSetVehicle 驗證 O2 的車輛資訊設定:驗證、正規化與唯一車牌。 +func TestDriverSetVehicle(t *testing.T) { + db := newServiceTestDB(t) + driversRepo := repository.NewDriverRepository(db) + reg := NewDriverRegistry(driversRepo) + + newDriver := func(t *testing.T, lineID string) int64 { + t.Helper() + d, err := driversRepo.FindOrCreate(lineID, "車輛測試司機") + if err != nil { + t.Fatalf("建立司機失敗:%v", err) + } + return d.ID + } + + t.Run("車牌寫入前先正規化", func(t *testing.T) { + // 車牌非空時有唯一索引;不正規化就存,同一台車會以「abc-1234」「ABC-1234」 + // 各佔一列,唯一性形同虛設。 + id := newDriver(t, "U_veh_norm") + got, err := reg.SetVehicle(id, "sedan", " abc-1234 ") + if err != nil { + t.Fatalf("設定車輛資訊失敗:%v", err) + } + if got.PlateNumber != "ABC-1234" { + t.Fatalf("回傳車牌應為正規化後的 ABC-1234,得到 %q", got.PlateNumber) + } + reread, err := driversRepo.FindByID(id) + if err != nil { + t.Fatalf("重讀司機失敗:%v", err) + } + if reread.PlateNumber != "ABC-1234" { + t.Fatalf("DB 內車牌應為正規化後的 ABC-1234,得到 %q", reread.PlateNumber) + } + if !reread.HasVehicle() { + t.Fatal("填妥車輛資訊後 HasVehicle() 應為 true(O3 gate 的條件)") + } + }) + + t.Run("車種與車牌驗證失敗時不寫入", func(t *testing.T) { + id := newDriver(t, "U_veh_invalid") + if _, err := reg.SetVehicle(id, "spaceship", "ABC-9999"); !errors.Is(err, ErrInvalidVehicleType) { + t.Fatalf("非白名單車種預期 ErrInvalidVehicleType,得到 %v", err) + } + if _, err := reg.SetVehicle(id, "", "ABC-9999"); !errors.Is(err, ErrInvalidVehicleType) { + t.Fatalf("空車種預期 ErrInvalidVehicleType,得到 %v", err) + } + if _, err := reg.SetVehicle(id, "sedan", "ABC_9999"); !errors.Is(err, ErrInvalidPlateNumber) { + t.Fatalf("非法字元車牌預期 ErrInvalidPlateNumber,得到 %v", err) + } + if _, err := reg.SetVehicle(id, "sedan", " "); !errors.Is(err, ErrInvalidPlateNumber) { + t.Fatalf("空白車牌預期 ErrInvalidPlateNumber,得到 %v", err) + } + // 驗證失敗不得留下半套資料——否則司機會通過 O3 gate 卻沒有有效車輛資訊。 + reread, err := driversRepo.FindByID(id) + if err != nil { + t.Fatalf("重讀司機失敗:%v", err) + } + if reread.HasVehicle() { + t.Fatalf("驗證失敗不該寫入任何車輛資訊,得到 %q / %q", reread.VehicleType, reread.PlateNumber) + } + }) + + t.Run("車牌被別的司機用走", func(t *testing.T) { + ownerID := newDriver(t, "U_veh_owner") + if _, err := reg.SetVehicle(ownerID, "pet", "PET-0001"); err != nil { + t.Fatalf("第一位司機設定車牌應成功:%v", err) + } + otherID := newDriver(t, "U_veh_other") + // 大小寫不同但正規化後同一張車牌,仍應撞唯一索引。 + _, err := reg.SetVehicle(otherID, "suv", "pet-0001") + if !errors.Is(err, repository.ErrPlateTaken) { + t.Fatalf("預期 repository.ErrPlateTaken,得到 %v", err) + } + }) + + t.Run("司機不存在", func(t *testing.T) { + if _, err := reg.SetVehicle(999999, "sedan", "NON-0001"); !errors.Is(err, ErrNotFound) { + t.Fatalf("預期 ErrNotFound,得到 %v", err) + } + }) +} diff --git a/internal/service/errors.go b/internal/service/errors.go index cd0f8ec..60931e9 100644 --- a/internal/service/errors.go +++ b/internal/service/errors.go @@ -14,4 +14,6 @@ var ( ErrBadRole = errors.New("角色無效") ErrSelfLockout = errors.New("不可對自己執行此操作") ErrLastSuperadmin = errors.New("不可移除最後一個 superadmin") + ErrInvalidVehicleType = errors.New("車種無效") + ErrInvalidPlateNumber = errors.New("車牌格式錯誤") ) From c2bf154f34514ae0fee9540ff9c0e7c0132d94af Mon Sep 17 00:00:00 2001 From: awei Date: Fri, 17 Jul 2026 09:45:45 +0800 Subject: [PATCH 2/3] =?UTF-8?q?feat(O3):=20=E6=8E=A5=E5=96=AE=E5=89=8D?= =?UTF-8?q?=E7=BD=AE=E6=AA=A2=E6=9F=A5=20gate=EF=BC=88=E6=9C=AA=E5=A1=AB?= =?UTF-8?q?=E8=BB=8A=E8=BC=9B=E4=B8=8D=E6=B4=BE=E5=96=AE=E3=80=81=E6=8E=A5?= =?UTF-8?q?=E5=96=AE=E5=9B=9E=20409=EF=BC=89?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 兩道都在後端,以 model.Driver.HasVehicle() 為單一判準(與 O2 回應的 has_vehicle 同源)。只靠 App 端跳轉擋不住——API 可被直接呼叫。 - dispatchRound:候選司機迴圈跳過未填車輛者(與既有「已派過/已拒接/ 非待命」同層)。 - AcceptRide:回 ErrDriverNoVehicle。handler 無需改動——statusForErr 對非 ErrForbidden 一律 409;LINE webhook 既有的 err.Error() 回覆會把 「請先填寫車種與車牌才能接單」原樣送給司機。 - gate 排在「非待命狀態」檢查之前:沒填車輛卻被告知「非待命狀態」, 司機不會知道要去填車輛。 驗收:build/vet/gofmt 綠;service 全套通過(781s)。新增真 PostGIS+Redis 整合測試:未填車輛者不進派單候選、接單回 ErrDriverNoVehicle 且無副作用、 有車司機隨後仍能接走該單(釘住 gate 早退時有釋放搶單鎖)。反向驗證: 停用派單過濾 → 兩台都收到派單;停用接單 gate → AcceptRide 回 nil,皆 FAIL。 註:本次之前沒有任何測試走過 service.AcceptRide/Dispatch(既有測試都用 repository.AcceptRide 直接改狀態),這兩條路徑的覆蓋來自本次新增的測試。 Co-Authored-By: Claude Opus 4.8 --- docs/TODO.md | 34 ++++- internal/service/dispatch.go | 13 +- .../service/dispatch_vehicle_gate_test.go | 138 ++++++++++++++++++ internal/service/errors.go | 3 + 4 files changed, 179 insertions(+), 9 deletions(-) create mode 100644 internal/service/dispatch_vehicle_gate_test.go diff --git a/docs/TODO.md b/docs/TODO.md index 2c7486b..b1c14c9 100644 --- a/docs/TODO.md +++ b/docs/TODO.md @@ -405,13 +405,30 @@ 拿掉 `NormalizePlateNumber` → 正規化與車牌衝突兩案 FAIL。 **未驗**:docker compose 起全服務的 live E2E(單元+整合已覆蓋,留待 O3 一起跑)。 -- [ ] **O3. 接單前置檢查(gate)** ✅ **已定案(2026-07-16):強制填寫,無寬限期** - **後端強制**:無車輛資訊的司機不得被派單(`dispatch.go` 候選司機過濾) - 且 `POST /api/rides/:id/accept` 回 409/400。 - **不能只靠 App 端擋**——API 可被直接呼叫。 - **既有司機**:上線時全部沒有車輛資料 → **一律無法接單,直到填完**(使用者拍板:不設寬限期)。 - App 端以**強制跳轉**引導填寫(見 App TODO);後端不需要回填 migration, - 但**上線前要通知司機**(營運事項,非工程項)。 +- [x] **O3. 接單前置檢查(gate)** ✅ **已實作(2026-07-17)**(定案 2026-07-16:強制填寫,無寬限期) + **兩道都在後端**(`model.Driver.HasVehicle()` 為單一判準,與 O2 回應的 `has_vehicle` 同源): + 1. **派單過濾**:`dispatch.go` 的 `dispatchRound` 候選迴圈跳過未填車輛者 + (與既有「已派過/已拒接/非待命」同一層)。 + 2. **接單擋下**:`AcceptRide` 回 `ErrDriverNoVehicle`。 + **API 自動得到 409**——`statusForErr` 對非 `ErrForbidden` 的錯誤一律回 409,不必改 handler; + **LINE 路徑自動得到文字回覆**——webhook 既有的 `err.Error()` 回覆會把 + 「請先填寫車種與車牌才能接單」原樣送給司機。 + **不能只靠 App 端擋**——API 可被直接呼叫,故 gate 長在 service 層而非 handler。 + **順序**:gate 排在既有的「非待命狀態」檢查**之前**——沒填車輛卻被告知「非待命狀態」, + 司機不會知道要去填車輛。 + **既有司機**:O1 migration 後兩欄皆為 `''` → 一律無法接單,直到填完(無寬限期)。 + 後端不需要回填 migration,但**上線前要通知司機**(營運事項,非工程項)。 + + **驗收**:`go build`/`vet`/`gofmt` 綠;`internal/service` 整合測試(真 PostGIS + Redis)—— + `TestDispatch_未填車輛的司機不被派單`(兩台同樣待命且都在附近,只有填了車輛的收到 `ride.assigned`)、 + `TestAcceptRide_未填車輛回ErrDriverNoVehicle`(回 `ErrDriverNoVehicle`、訂單狀態與司機狀態皆無副作用、 + **且有車司機隨後仍能接走這張單**——釘住 gate 早退時有正確釋放搶單鎖)。 + **反向驗證**:停用派單過濾 → 兩台都收到派單,測試 FAIL;停用接單 gate → `AcceptRide` 回 nil,測試 FAIL。 + **回歸**:`internal/service` 全套通過(781s,無 FAIL)。 + **順帶盤到的事實**:本次之前**沒有任何測試走過 `service.AcceptRide`/`Dispatch`** + (既有測試一律用 `repository.AcceptRide` 直接改狀態),所以回歸全綠**不代表** gate 被既有測試考驗過—— + 這兩條路徑的覆蓋完全來自本次新增的測試。日後改動搶單/派單邏輯時別誤以為有既有安全網。 + **未驗**:docker compose 全服務 live E2E。 - [ ] **O4. 乘客端可見車輛資訊** `ride.accepted` payload 與 `GET /api/customer/rides/active` 加 @@ -575,7 +592,8 @@ 清潔費依乘客指定車種、上限 30%、**不計入抽成**/不降級+取消原因明確化/customer fees 端點/ **電話明碼、僅該趟乘客可見**)——**N、O、P 規格完備,可開始實作**, 建議順序:O1→O2→O3(車輛地基)→ P1→P2→P3+P4(車種)→ O6+P5(清潔費)→ O4/O7(乘客可見)→ N(多停靠點,最大塊)。 - **進度:O1 ✅(2026-07-16)、O2 ✅(2026-07-17,含車牌寬鬆驗證拍板)→ 下一項是 O3(接單 gate)。** + **進度:O1 ✅(2026-07-16)、O2 ✅(2026-07-17,含車牌寬鬆驗證拍板)、O3 ✅(2026-07-17,派單過濾+接單 409) + → 車輛地基完成,下一項是 P1(`rides` 加 `required_vehicle_type`)。** 計費地基 **F1–F8+F3 里程退路+F9-1~F9-6+M 整數台幣 已全數合併進 main**,三端對帳與 F3/F9-3/F9-4 皆 docker E2E 驗過。 其餘皆屬「量體上升後才需」的大資料量最佳化,勿過早做: diff --git a/internal/service/dispatch.go b/internal/service/dispatch.go index 155c765..7d4cb6c 100644 --- a/internal/service/dispatch.go +++ b/internal/service/dispatch.go @@ -109,7 +109,7 @@ func (s *DispatchService) dispatchRound(rideID int64, attempt int, offered map[i return err } - // 篩掉「已派過的」「已拒接的」「非待命的」,避免重複派給同一台車 + // 篩掉「已派過的」「已拒接的」「非待命的」「未填車輛資訊的」,避免重複派給同一台車 rejected := s.redis.RejectedDrivers(ctx, rideID) var targets []*model.Driver for _, id := range candidates { @@ -120,6 +120,10 @@ func (s *DispatchService) dispatchRound(rideID int64, attempt int, offered map[i if err != nil || driver.Status != constants.DriverStatusIdle { continue } + // O3 gate:未填車種/車牌者不派單。既有司機一律如此,直到填完(拍板:無寬限期)。 + if !driver.HasVehicle() { + continue + } targets = append(targets, driver) } @@ -380,6 +384,13 @@ func (s *DispatchService) AcceptRide(ctx context.Context, rideID, driverID int64 s.redis.ReleaseRideLock(ctx, rideID) return "", err } + // O3 gate:未填車輛資訊者不得接單。派單已先過濾(dispatchRound),這裡擋的是 + // 直接打 API/LINE 的路徑——只靠 App 端跳轉擋不住。 + // 排在狀態檢查之前:這是接單資格問題,回「非待命狀態」會讓司機不知道要去填車輛。 + if !driver.HasVehicle() { + s.redis.ReleaseRideLock(ctx, rideID) + return "", ErrDriverNoVehicle + } if driver.Status != constants.DriverStatusIdle { s.redis.ReleaseRideLock(ctx, rideID) return "您目前無法接單(非待命狀態)", nil diff --git a/internal/service/dispatch_vehicle_gate_test.go b/internal/service/dispatch_vehicle_gate_test.go new file mode 100644 index 0000000..2dc4f1d --- /dev/null +++ b/internal/service/dispatch_vehicle_gate_test.go @@ -0,0 +1,138 @@ +package service + +import ( + "context" + "errors" + "testing" + + "line-fleet-dispatch/internal/constants" + "line-fleet-dispatch/internal/events" + lineclient "line-fleet-dispatch/internal/line" + "line-fleet-dispatch/internal/repository" +) + +// gateFixture 一台有車、一台沒車,兩台都在上車點附近待命。 +type gateFixture struct { + dispatch *DispatchService + publisher *fakePublisher + withID int64 + withoutID int64 + rideID int64 + driversRep *repository.DriverRepository + ridesRep *repository.RideRepository +} + +func newGateFixture(t *testing.T, prefix string) *gateFixture { + t.Helper() + db := newServiceTestDB(t) + redisStore := newServiceTestRedis(t) + drivers := repository.NewDriverRepository(db) + rides := repository.NewRideRepository(db) + customers := repository.NewCustomerRepository(db) + fp := &fakePublisher{} + // maxAttempts=1:只跑一輪,測試不必等重派。 + dispatch := NewDispatchService(drivers, rides, customers, redisStore, + lineclient.NewClient(""), NewETAService(nil), NewDispatchSettings(3000, 5, 20, 1, 5), fp) + + withVehicle, err := drivers.FindOrCreate(prefix+"_with", "有車司機") + if err != nil { + t.Fatalf("建立司機失敗:%v", err) + } + if err := drivers.UpdateVehicle(withVehicle.ID, constants.VehicleTypeSedan, "GATE-0001"); err != nil { + t.Fatalf("設定車輛資訊失敗:%v", err) + } + // 未填車輛:這正是既有司機在 O1 migration 後的狀態(兩欄皆為 '')。 + withoutVehicle, err := drivers.FindOrCreate(prefix+"_without", "無車司機") + if err != nil { + t.Fatalf("建立司機失敗:%v", err) + } + + ctx := context.Background() + for _, id := range []int64{withVehicle.ID, withoutVehicle.ID} { + if err := redisStore.UpdateDriverLocation(ctx, id, 25.031, 121.561); err != nil { + t.Fatalf("寫入司機位置失敗:%v", err) + } + } + + cust, err := customers.FindOrCreateByLineUserID(prefix+"_cust", "乘客") + if err != nil { + t.Fatalf("建立乘客失敗:%v", err) + } + ride := newTestRide(t, rides, cust.ID, constants.RideStatusRequested) + + return &gateFixture{ + dispatch: dispatch, + publisher: fp, + withID: withVehicle.ID, + withoutID: withoutVehicle.ID, + rideID: ride.ID, + driversRep: drivers, + ridesRep: rides, + } +} + +// TestDispatch_未填車輛的司機不被派單 O3 gate 的派單側: +// 未填車種/車牌者不得進入候選(拍板:既有司機一律如此,無寬限期)。 +func TestDispatch_未填車輛的司機不被派單(t *testing.T) { + f := newGateFixture(t, "U_gate_dispatch") + + if err := f.dispatch.Dispatch(context.Background(), f.rideID); err != nil { + t.Fatalf("派單失敗:%v", err) + } + + var offeredTo []int64 + for _, r := range f.publisher.recv { + if r.Ev.Type == events.TypeRideAssigned && r.Rec.Role == events.RoleDriver { + offeredTo = append(offeredTo, r.Rec.ID) + } + } + if len(offeredTo) != 1 { + t.Fatalf("預期只派給 1 位(有車者),實際派給 %v", offeredTo) + } + if offeredTo[0] != f.withID { + t.Fatalf("預期派給有車司機 %d,實際派給 %d", f.withID, offeredTo[0]) + } +} + +// TestAcceptRide_未填車輛回ErrDriverNoVehicle O3 gate 的接單側: +// 擋的是直接打 API/LINE 的路徑——只靠 App 端跳轉擋不住。 +func TestAcceptRide_未填車輛回ErrDriverNoVehicle(t *testing.T) { + f := newGateFixture(t, "U_gate_accept") + ctx := context.Background() + + _, err := f.dispatch.AcceptRide(ctx, f.rideID, f.withoutID, "") + if !errors.Is(err, ErrDriverNoVehicle) { + t.Fatalf("預期 ErrDriverNoVehicle,得到 %v", err) + } + + // 被擋下時不得留下副作用:訂單狀態不變、司機沒被設成載客中。 + ride, err := f.ridesRep.GetByID(f.rideID) + if err != nil { + t.Fatalf("重讀訂單失敗:%v", err) + } + if ride.Status != constants.RideStatusRequested { + t.Fatalf("被擋下的接單不該改變訂單狀態,得到 %d", ride.Status) + } + if ride.DriverID != nil { + t.Fatalf("被擋下的接單不該綁定司機,得到 %v", *ride.DriverID) + } + d, err := f.driversRep.FindByID(f.withoutID) + if err != nil { + t.Fatalf("重讀司機失敗:%v", err) + } + if d.Status != constants.DriverStatusIdle { + t.Fatalf("被擋下的司機狀態不該變動,得到 %d", d.Status) + } + + // gate 早退時若漏放搶單鎖,這張單就再也沒人接得走——用「有車司機仍能接」釘住。 + if _, err := f.dispatch.AcceptRide(ctx, f.rideID, f.withID, ""); err != nil { + t.Fatalf("有車司機應能接單(gate 須釋放搶單鎖):%v", err) + } + ride, err = f.ridesRep.GetByID(f.rideID) + if err != nil { + t.Fatalf("重讀訂單失敗:%v", err) + } + if ride.Status != constants.RideStatusAccepted { + t.Fatalf("有車司機接單後預期 Accepted,得到 %d", ride.Status) + } +} diff --git a/internal/service/errors.go b/internal/service/errors.go index 60931e9..3a25fbb 100644 --- a/internal/service/errors.go +++ b/internal/service/errors.go @@ -16,4 +16,7 @@ var ( ErrLastSuperadmin = errors.New("不可移除最後一個 superadmin") ErrInvalidVehicleType = errors.New("車種無效") ErrInvalidPlateNumber = errors.New("車牌格式錯誤") + // ErrDriverNoVehicle O3 gate:未填車輛資訊者不得接單。訊息會原樣回給司機 + // (API 走 statusForErr → 409;LINE 走 webhook 的 err.Error() 文字回覆)。 + ErrDriverNoVehicle = errors.New("請先填寫車種與車牌才能接單") ) From 8ea2601b2b10df80a879a57460aee2b48b148475 Mon Sep 17 00:00:00 2001 From: awei Date: Fri, 17 Jul 2026 10:35:42 +0800 Subject: [PATCH 3/3] =?UTF-8?q?feat(P1-P4):=20=E4=B9=98=E5=AE=A2=E6=8C=87?= =?UTF-8?q?=E5=AE=9A=E8=BB=8A=E7=A8=AE=E2=80=94=E2=80=94=E6=AC=84=E4=BD=8D?= =?UTF-8?q?=E3=80=81=E5=BB=BA=E5=96=AE=20API=E3=80=81=E6=B4=BE=E5=96=AE?= =?UTF-8?q?=E9=81=8E=E6=BF=BE=E3=80=81=E5=8F=96=E6=B6=88=E5=8E=9F=E5=9B=A0?= =?UTF-8?q?=E6=98=8E=E7=A2=BA=E5=8C=96?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit P1 migration 000018:rides 加 required_vehicle_type + CHECK。沿用 O1 慣例 TEXT NOT NULL DEFAULT '',不用 NULL——否則「未指定」有 NULL 與 '' 兩種表示法, 每個過濾條件都要處理兩者,遲早漏一條。 P2 建單 API 帶車種:handler → CustomerCreateRequest → CreateByCustomer → RideRepository.Create 的 raw INSERT(兩條分支都要補;raw SQL 不是 GORM 自動 映射,漏帶會靜靜存成 '',回傳的 struct 卻是對的)。非白名單在 service 擋成 400,不讓它撞 DB CHECK 變 500。 P3 派單過濾:指定車種時只派同車種,排在 O3 的 HasVehicle gate 之後。 P4 取消原因明確化:giveUpCancelInfo() 同時產生「機器可讀原因/乘客文案/WS payload」,三者同源不漂移。指定車種找不到 → cancel_reason=no_vehicle_of_type + required_vehicle_type +「附近暫無寵物用車」;未指定 → no_driver_available 且不帶車種鍵(帶了 App 會誤以為乘客指定過)。 註:目前只有逾時取消這條路徑帶 cancel_reason,App 端須容忍缺席。 順帶修:O1 的可逆性測試用 Steps(-1),隱含「O1 是最後一個 migration」。P1 一加 就變成驗 P1 的 down,O1 反而失去覆蓋。改為版本導向(Migrate(17) 再 Steps(-1))。 驗收:build/vet/gofmt 綠;repository 568s、service 967s、handler 51s、constants 全套通過。反向驗證 6 項皆確認對應測試 FAIL:CHECK、O1 測試修正、P2 無目的地分支 漏帶值、P3 過濾、P4 車種分支。 Co-Authored-By: Claude Opus 4.8 --- ...18_add_ride_required_vehicle_type.down.sql | 4 + ...0018_add_ride_required_vehicle_type.up.sql | 15 ++ docs/TODO.md | 95 ++++++-- internal/constants/cancel_reason.go | 14 ++ internal/constants/vehicle.go | 22 ++ internal/handler/ride.go | 17 +- internal/model/models.go | 3 + .../driver_vehicle_migration_test.go | 7 + internal/repository/repository.go | 8 +- .../ride_required_vehicle_integration_test.go | 154 +++++++++++++ internal/service/dispatch.go | 34 ++- .../service/dispatch_required_vehicle_test.go | 216 ++++++++++++++++++ internal/service/ride.go | 26 ++- .../service/ride_create_vehicle_type_test.go | 138 +++++++++++ 14 files changed, 712 insertions(+), 41 deletions(-) create mode 100644 db/migrations/000018_add_ride_required_vehicle_type.down.sql create mode 100644 db/migrations/000018_add_ride_required_vehicle_type.up.sql create mode 100644 internal/constants/cancel_reason.go create mode 100644 internal/repository/ride_required_vehicle_integration_test.go create mode 100644 internal/service/dispatch_required_vehicle_test.go create mode 100644 internal/service/ride_create_vehicle_type_test.go diff --git a/db/migrations/000018_add_ride_required_vehicle_type.down.sql b/db/migrations/000018_add_ride_required_vehicle_type.down.sql new file mode 100644 index 0000000..a4b7567 --- /dev/null +++ b/db/migrations/000018_add_ride_required_vehicle_type.down.sql @@ -0,0 +1,4 @@ +-- DROP COLUMN 會自動連帶刪除依賴該欄位的 CHECK(比照 000017 的記錄); +-- 這行是明示意圖,IF EXISTS 故無害。 +ALTER TABLE rides DROP CONSTRAINT IF EXISTS chk_rides_required_vehicle_type; +ALTER TABLE rides DROP COLUMN IF EXISTS required_vehicle_type; diff --git a/db/migrations/000018_add_ride_required_vehicle_type.up.sql b/db/migrations/000018_add_ride_required_vehicle_type.up.sql new file mode 100644 index 0000000..22a8704 --- /dev/null +++ b/db/migrations/000018_add_ride_required_vehicle_type.up.sql @@ -0,0 +1,15 @@ +-- 乘客指定車種(P1):乘客叫車時可要求特定車種(寵物用車/無障礙/七人座…)。 +-- 必須存在 ride 上而不只是派單當下的參數——清潔費(O6)、報表與稽核都要回頭看 +-- 「這趟乘客要的是什麼車」;派單參數不留痕,事後無從對帳。 +-- +-- 沿用 drivers.vehicle_type 的慣例(O1):TEXT NOT NULL DEFAULT '','' 代表「不指定」。 +-- 刻意不用 NULL——否則「未指定」會有 NULL 與 '' 兩種表示法,過濾條件得同時處理兩者, +-- 遲早有一條路徑漏掉。既有訂單一律為「不指定」,維持現行行為(任何車種都可派)。 +ALTER TABLE rides ADD COLUMN IF NOT EXISTS required_vehicle_type TEXT NOT NULL DEFAULT ''; + +-- 值域同 O1 的車種白名單;'' =不指定。 +-- 與 chk_drivers_vehicle_type 放同一層的理由相同:這是清潔費(O6)加收與否的判斷依據, +-- 值髒掉直接影響計費,最後防線要在資料層而非 API 驗證。 +ALTER TABLE rides DROP CONSTRAINT IF EXISTS chk_rides_required_vehicle_type; +ALTER TABLE rides ADD CONSTRAINT chk_rides_required_vehicle_type + CHECK (required_vehicle_type IN ('', 'sedan', 'suv', 'van7', 'accessible', 'pet')); diff --git a/docs/TODO.md b/docs/TODO.md index b1c14c9..7df9edf 100644 --- a/docs/TODO.md +++ b/docs/TODO.md @@ -526,24 +526,77 @@ ### 施作項目 -- [ ] **P1. `rides` 加 `required_vehicle_type`**(新 migration,接在 O1 之後) - 選填(null/空=不指定,任何車種都可派);值域同 O1 的車種 code 白名單。 - **必須存在 ride 上**(不是只當派單參數)——清潔費、報表、稽核都要回頭看「這趟乘客要的是什麼車」。 - -- [ ] **P2. 叫車 API 帶車種**(`POST /api/rides`) - request 加選填 `required_vehicle_type`;非白名單值回 400。 - 未帶=維持現行行為(不過濾車種),**不可破壞既有 App/LINE 建單**。 - -- [ ] **P3. 派單依車種過濾**(`dispatch.go` 候選司機迴圈) - 現行: - ```go - driver, err := s.drivers.FindByID(id) - if err != nil || driver.Status != constants.DriverStatusIdle { continue } - ``` - 加上:`ride.RequiredVehicleType != "" && driver.VehicleType != ride.RequiredVehicleType` → skip。 - 注意這與 O3 的 gate 疊加(無車輛資料的司機本來就不得被派單)。 - -- [ ] **P4. 「找不到指定車種」的行為** ✅ **已定案(2026-07-16,採建議方案):不降級+取消原因明確化** +- [x] **P1. `rides` 加 `required_vehicle_type`** ✅ **已實作(2026-07-17,migration `000018`)** + 值域同 O1 的車種 code 白名單,由 `chk_rides_required_vehicle_type` 把關(與 O1 同理由: + 這是清潔費 O6 加收與否的判斷依據,值髒掉直接影響計費,最後防線要在資料層)。 + **存在 ride 上**(不是只當派單參數)——清潔費、報表、稽核都要回頭看「這趟乘客要的是什麼車」。 + + **實作時定的一件事**:規格寫「null/空=不指定」,實作採 **`TEXT NOT NULL DEFAULT ''`**(沿用 O1 慣例), + **不用 NULL**——否則「未指定」會有 NULL 與 `''` 兩種表示法,每個過濾條件都得同時處理兩者, + 遲早有一條路徑漏掉。既有訂單一律為 `''`(不指定),維持現行行為。 + + **驗收**:`go build`/`vet`/`gofmt` 綠;`internal/repository` 整合測試(真 PostGIS + 跑完整 migration)—— + `TestRideRequiredVehicleTypeSchema`(**既有建單路徑預設為不指定**:`RideRepository.Create` 走 raw INSERT + 且不含新欄位,DB default 必須生效,否則既有 App/LINE 建單全掛/白名單皆可寫入/非白名單由 CHECK 擋下)、 + `TestRideRequiredVehicleMigrationReversible`(up → down 到 v17 → 再 up)。 + **反向驗證**:拿掉 CHECK → 非白名單案 FAIL。 + + **順帶修掉一個既有測試的隱含假設**:`TestDriverVehicleMigrationReversible`(O1)用 `m.Steps(-1)` + 驗自己的 down,隱含「O1 是最後一個 migration」。P1 一加,那步卸的就變成 P1,**O1 的 down 會安靜地失去覆蓋**。 + 已改為先 `m.Migrate(17)` 再 `Steps(-1)`,P1 的測試同樣以版本表達意圖。 + **反向驗證**:拿掉該修正 → O1 測試 FAIL(`down 後不應還有欄位 vehicle_type`)。 + **日後新增 migration 者注意**:可逆性測試要用版本導向,別用「往回一步」。 + +- [x] **P2. 叫車 API 帶車種**(`POST /api/rides`)✅ **已實作(2026-07-17)** + request 加選填 `required_vehicle_type`;未帶=不指定,維持現行行為。 + 非白名單值 → `ErrInvalidVehicleType` → **400**(`createStatusForErr` 新增映射)。 + 驗證放在 service 而非仰賴 DB CHECK:撞 CHECK 會變成 500,乘客看到「伺服器錯誤」而不知道是車種填錯。 + + **改動四處**(缺一不可):handler request struct → `CustomerCreateRequest` → + `CreateByCustomer` 驗證+帶入 model → **`RideRepository.Create` 的 raw INSERT**。 + 最後一項最容易漏:`Create` 走 raw SQL,**不是 GORM 自動映射**——service 設了 + `RequiredVehicleType`,SQL 沒帶就靜靜地存成 `''`,回傳的 struct 卻是對的(只有 DB 是空的)。 + 且它有「帶/不帶 dropoff」**兩條 INSERT 分支,兩條都要補**。 + + **驗收**:`go build`/`vet`/`gofmt` 綠;`internal/service` 整合測試(真 PostGIS + Redis)—— + 指定車種持久化(**重讀 DB**,不只看回傳值)、**無目的地的單也要帶車種**(釘住第二條 INSERT 分支)、 + 未指定維持現行行為(`''`,不破壞既有 App/LINE 建單)、非白名單被拒回 `ErrInvalidVehicleType`。 + **反向驗證**:只讓「無目的地」分支漏帶值 → 該案 FAIL(`得到 ""`)、有目的地案照樣 PASS + ——證明兩條分支各需一個測試。 + **未驗**:docker compose 全服務 live E2E。 + +- [x] **P3. 派單依車種過濾**(`dispatch.go` 候選司機迴圈)✅ **已實作(2026-07-17)** + `ride.RequiredVehicleType != "" && driver.VehicleType != ride.RequiredVehicleType` → skip, + 排在 O3 的 `HasVehicle()` gate 之後(無車輛資料者本來就不得被派單,兩者疊加)。 + 未指定(`''`)時完全不過濾,既有訂單行為不變。 + +- [x] **P4. 「找不到指定車種」的行為** ✅ **已實作(2026-07-17)**(定案 2026-07-16:不降級+取消原因明確化) + **不降級**由 P3 的過濾直接達成(找不到就沒有候選 → 走現行 `giveUpIfUnaccepted` 自動取消)。 + **取消原因明確化**:新增 `giveUpCancelInfo(ride)` 同時決定「機器可讀原因/給乘客的文案/WS payload」, + 三者由同一處產生,不會各自漂移。 + - 未指定車種:`cancel_reason=no_driver_available` + 原文案「抱歉,附近暫無可用司機,請稍後再試」。 + - 指定車種:`cancel_reason=no_vehicle_of_type` + `required_vehicle_type` + + 文案「抱歉,附近暫無**寵物用車**,請稍後再試」。 + 常數在 `internal/constants/cancel_reason.go`。 + **顯示名的例外**:一般原則是「後端只認 code、顯示名由前端對應」(O1),但 LINE 推播文案是**後端組的**, + 沒有前端可以對應 → 加 `constants.VehicleTypeDisplayName`,**僅供後端自產文案使用**; + API/WS payload 一律只送 code。未知 code 回「可用車輛」,讓文案在資料異常時仍讀得通。 + **範圍限制(App 端請注意)**:目前**只有逾時取消這條路徑**帶 `cancel_reason`; + 乘客主動取消/司機放棄等路徑不帶,App 端須容忍此欄位缺席。 + + **驗收**:`go build`/`vet`/`gofmt` 綠。 + 單元 `TestGiveUpCancelInfo`(未指定→泛用文案且**不帶** `required_vehicle_type` 鍵, + 否則 App 會誤以為乘客指定過/指定→原因、文案、payload 三者皆具體); + 整合(真 PostGIS + Redis)`TestDispatch_指定車種只派同車種`、 + `TestDispatch_未指定車種時所有車種都可派`(釘住「不可讓既有不指定的單變窄」)、 + `TestDispatch_找不到指定車種時取消並帶原因`(端到端:一台都不派 → 逾時自動取消 → + `ride.cancelled` 帶 `no_vehicle_of_type`+車種、訂單狀態為已取消; + 測試把 `offerTimeout` 設 1 秒讓 `giveUpIfUnaccepted` 在測試時間內觸發)。 + **反向驗證**:停用 P3 過濾 → 兩台都收到派單、「不降級」斷言 FAIL; + 停用 P4 車種分支 → `cancel_reason` 退回 `no_driver_available`,單元與整合皆 FAIL。 + **未驗**:docker compose 全服務 live E2E。 + + 原始定案內容如下(保留供對照): 1. **不降級**:找不到指定車種時**不改派一般車**,走現行 `giveUpIfUnaccepted` 自動取消。 寵物車/無障礙車是硬需求,默默派來一般車=服務失敗還照收錢。 2. **取消原因明確化**:`giveUpIfUnaccepted` 目前推播固定文案「抱歉,附近暫無可用司機,請稍後再試」; @@ -592,8 +645,10 @@ 清潔費依乘客指定車種、上限 30%、**不計入抽成**/不降級+取消原因明確化/customer fees 端點/ **電話明碼、僅該趟乘客可見**)——**N、O、P 規格完備,可開始實作**, 建議順序:O1→O2→O3(車輛地基)→ P1→P2→P3+P4(車種)→ O6+P5(清潔費)→ O4/O7(乘客可見)→ N(多停靠點,最大塊)。 - **進度:O1 ✅(2026-07-16)、O2 ✅(2026-07-17,含車牌寬鬆驗證拍板)、O3 ✅(2026-07-17,派單過濾+接單 409) - → 車輛地基完成,下一項是 P1(`rides` 加 `required_vehicle_type`)。** + **進度:O1 ✅(2026-07-16)、O2 ✅、O3 ✅、P1 ✅、P2 ✅、P3 ✅、P4 ✅(皆 2026-07-17) + → **乘客指定車種整條鏈路已通**:建單帶車種 → 只派同車種 → 找不到就明確取消並帶機器可讀原因。 + 下一項建議 **O6+P5(清潔費)**——P 章節只剩 P5(`GET /api/customer/fees`), + 而 O6 的觸發條件(依 `rides.required_vehicle_type` 是否為 `pet`)現在已經存在了。** 計費地基 **F1–F8+F3 里程退路+F9-1~F9-6+M 整數台幣 已全數合併進 main**,三端對帳與 F3/F9-3/F9-4 皆 docker E2E 驗過。 其餘皆屬「量體上升後才需」的大資料量最佳化,勿過早做: diff --git a/internal/constants/cancel_reason.go b/internal/constants/cancel_reason.go new file mode 100644 index 0000000..46f8c79 --- /dev/null +++ b/internal/constants/cancel_reason.go @@ -0,0 +1,14 @@ +package constants + +// 取消原因(P4,2026-07-17):隨 WS `ride.cancelled` payload 的 `cancel_reason` 送出。 +// **機器可讀**——App 端據此顯示訊息並決定後續引導(例如「改用不指定車種重新叫車」), +// 不該去 parse 中文文案字串(文案會改,字串比對會無聲失效)。 +// +// 目前只有 `giveUpIfUnaccepted`(逾時無人接單)這條路徑會帶 cancel_reason; +// 乘客主動取消/司機放棄等路徑不帶,App 端須容忍此欄位缺席。 +const ( + // CancelReasonNoDriver 逾時無人接單(未指定車種,或指定了但就是沒人接)。 + CancelReasonNoDriver = "no_driver_available" + // CancelReasonNoVehicleOfType 乘客指定了車種,但附近沒有該車種的司機。 + CancelReasonNoVehicleOfType = "no_vehicle_of_type" +) diff --git a/internal/constants/vehicle.go b/internal/constants/vehicle.go index c9d0cf0..4171948 100644 --- a/internal/constants/vehicle.go +++ b/internal/constants/vehicle.go @@ -44,6 +44,28 @@ func IsValidVehicleType(s string) bool { return false } +// vehicleTypeNames 車種 code 的中文顯示名。 +// +// 一般原則仍是「後端只認 code,顯示名由前端對應」(O1)——這份對照表**只給後端自產的文案用**, +// 也就是 LINE 推播(例如「附近暫無寵物用車」,P4):那些字串是後端組的,沒有前端可以對應。 +// API/WS payload 一律只送 code,不要送顯示名。 +var vehicleTypeNames = map[string]string{ + VehicleTypeSedan: "轎車", + VehicleTypeSUV: "休旅車", + VehicleTypeVan7: "七人座", + VehicleTypeAccessible: "無障礙車", + VehicleTypePet: "寵物用車", +} + +// VehicleTypeDisplayName 回傳車種的中文顯示名;未知 code(含空字串)回「可用車輛」, +// 讓文案在資料異常時仍讀得通,而不是出現空白或原始 code。 +func VehicleTypeDisplayName(code string) string { + if name, ok := vehicleTypeNames[code]; ok { + return name + } + return "可用車輛" +} + // 車牌長度界線(正規化後)。台灣現行最長為 `ABC-1234`(8 碼), // 放寬到 10 是為了容納舊式與特殊車牌。 const ( diff --git a/internal/handler/ride.go b/internal/handler/ride.go index 64179f8..0ecc25c 100644 --- a/internal/handler/ride.go +++ b/internal/handler/ride.go @@ -151,6 +151,8 @@ func (h *RideHandler) Create(c *gin.Context) { DropoffAddress string `json:"dropoff_address"` DropoffLat *float64 `json:"dropoff_lat"` DropoffLng *float64 `json:"dropoff_lng"` + // 選填(P2):未帶=不指定車種,維持現行行為,既有 App/LINE 建單不受影響。 + RequiredVehicleType string `json:"required_vehicle_type"` } if err := c.ShouldBindJSON(&req); err != nil { c.JSON(http.StatusBadRequest, gin.H{"error": "參數錯誤"}) @@ -158,12 +160,13 @@ func (h *RideHandler) Create(c *gin.Context) { } ride, err := h.rideService.CreateByCustomer( c.Request.Context(), customerID, service.CustomerCreateRequest{ - PickupLat: req.PickupLat, - PickupLng: req.PickupLng, - PickupAddress: req.PickupAddress, - DropoffAddress: req.DropoffAddress, - DropoffLat: req.DropoffLat, - DropoffLng: req.DropoffLng, + PickupLat: req.PickupLat, + PickupLng: req.PickupLng, + PickupAddress: req.PickupAddress, + DropoffAddress: req.DropoffAddress, + DropoffLat: req.DropoffLat, + DropoffLng: req.DropoffLng, + RequiredVehicleType: req.RequiredVehicleType, }, ) if err != nil { @@ -176,7 +179,7 @@ func (h *RideHandler) Create(c *gin.Context) { // createStatusForErr 將下單錯誤對應到 HTTP 狀態碼。 func createStatusForErr(err error) int { switch { - case errors.Is(err, service.ErrInvalidCoords): + case errors.Is(err, service.ErrInvalidCoords), errors.Is(err, service.ErrInvalidVehicleType): return http.StatusBadRequest case errors.Is(err, service.ErrActiveRideExists): return http.StatusConflict diff --git a/internal/model/models.go b/internal/model/models.go index d757275..e7fabb6 100644 --- a/internal/model/models.go +++ b/internal/model/models.go @@ -153,6 +153,9 @@ type Ride struct { CompletedAt *time.Time `gorm:"" json:"completed_at"` DistanceM *int `gorm:"column:distance_m" json:"distance_m"` EtaPickupSec *int `gorm:"column:eta_pickup_sec" json:"eta_pickup_sec"` + // RequiredVehicleType 乘客指定的車種(P1):constants.VehicleType* 之一;'' =不指定(任何車種都可派)。 + // 這是清潔費(O6)加收與否的判斷依據——依**乘客要的車種**,不是司機開的車種。 + RequiredVehicleType string `gorm:"column:required_vehicle_type;not null;default:''" json:"required_vehicle_type"` // 計費欄位:完成時定格寫入(費率快照制),一律以「分」儲存;未完成/取消為 nil。 FareAmountCents *int64 `gorm:"column:fare_amount_cents" json:"fare_amount_cents"` CommissionAmountCents *int64 `gorm:"column:commission_amount_cents" json:"commission_amount_cents"` diff --git a/internal/repository/driver_vehicle_migration_test.go b/internal/repository/driver_vehicle_migration_test.go index 0e92e23..9c96a79 100644 --- a/internal/repository/driver_vehicle_migration_test.go +++ b/internal/repository/driver_vehicle_migration_test.go @@ -77,6 +77,13 @@ func TestDriverVehicleMigrationReversible(t *testing.T) { t.Fatal("up 後應有車牌 partial unique index") } + // 先回到「O1 剛套用完」的版本,把 O1 之後的 migration 卸掉。 + // 不能直接 Steps(-1)——那卸的是最新的那個 migration,一旦有人在 O1 之後新增 + // migration(P1 就是),這個測試會安靜地改去驗別人的 down,O1 反而失去覆蓋。 + if err := m.Migrate(17); err != nil && err != migrate.ErrNoChange { + t.Fatalf("回到 version 17 失敗: %v", err) + } + // down 一步:O1 的產物要全部消失(含 CHECK 與 index,不能只 drop 欄位) if err := m.Steps(-1); err != nil { t.Fatalf("down 失敗: %v", err) diff --git a/internal/repository/repository.go b/internal/repository/repository.go index 66b9cd3..3335881 100644 --- a/internal/repository/repository.go +++ b/internal/repository/repository.go @@ -84,7 +84,7 @@ func (r *RideRepository) Create(ride *model.Ride) error { return r.db.Raw(` INSERT INTO rides ( customer_id, status, pickup_point, pickup_address, - dropoff_point, dropoff_address, + dropoff_point, dropoff_address, required_vehicle_type, requested_at, created_at, updated_at ) VALUES ( ?, ?, @@ -92,6 +92,7 @@ func (r *RideRepository) Create(ride *model.Ride) error { ?, ST_SetSRID(ST_MakePoint(?, ?), 4326)::geography, ?, + ?, ?, ?, ? ) RETURNING id @@ -104,6 +105,7 @@ func (r *RideRepository) Create(ride *model.Ride) error { ride.DropoffPoint.Lng, ride.DropoffPoint.Lat, ride.DropoffAddress, + ride.RequiredVehicleType, ride.RequestedAt, ride.CreatedAt, ride.UpdatedAt, @@ -112,13 +114,14 @@ func (r *RideRepository) Create(ride *model.Ride) error { return r.db.Raw(` INSERT INTO rides ( customer_id, status, pickup_point, pickup_address, - dropoff_address, + dropoff_address, required_vehicle_type, requested_at, created_at, updated_at ) VALUES ( ?, ?, ST_SetSRID(ST_MakePoint(?, ?), 4326)::geography, ?, ?, + ?, ?, ?, ? ) RETURNING id @@ -129,6 +132,7 @@ func (r *RideRepository) Create(ride *model.Ride) error { ride.PickupPoint.Lat, ride.PickupAddress, ride.DropoffAddress, + ride.RequiredVehicleType, ride.RequestedAt, ride.CreatedAt, ride.UpdatedAt, diff --git a/internal/repository/ride_required_vehicle_integration_test.go b/internal/repository/ride_required_vehicle_integration_test.go new file mode 100644 index 0000000..644fe35 --- /dev/null +++ b/internal/repository/ride_required_vehicle_integration_test.go @@ -0,0 +1,154 @@ +package repository + +import ( + "context" + "strings" + "testing" + "time" + + "github.com/golang-migrate/migrate/v4" + _ "github.com/golang-migrate/migrate/v4/database/postgres" + _ "github.com/golang-migrate/migrate/v4/source/file" + tcpostgres "github.com/testcontainers/testcontainers-go/modules/postgres" + gormpostgres "gorm.io/driver/postgres" + "gorm.io/gorm" + + "line-fleet-dispatch/internal/model" +) + +// P1 的 schema 保證:乘客指定車種存在 ride 上,值域由 DB CHECK 把關。 +// 它是清潔費(O6)加收與否的判斷依據,值髒掉直接影響計費。 +func TestRideRequiredVehicleTypeSchema(t *testing.T) { + db := newMigratedTestDB(t) + rides := NewRideRepository(db) + customers := NewCustomerRepository(db) + + cust, err := customers.FindOrCreateByLineUserID("U_req_veh", "乘客") + if err != nil { + t.Fatalf("建立乘客失敗: %v", err) + } + + newRide := func() *model.Ride { + now := time.Now() + return &model.Ride{ + CustomerID: cust.ID, + PickupPoint: model.GeoPoint{Lat: 25.03, Lng: 121.56}, + PickupAddress: "台北車站", + RequestedAt: now, + CreatedAt: now, + UpdatedAt: now, + } + } + + t.Run("既有建單路徑預設為不指定", func(t *testing.T) { + // RideRepository.Create 走 raw INSERT 且不含新欄位——DB default '' 必須生效, + // 否則既有 App/LINE 建單全掛(P2 才會開始帶車種)。 + ride := newRide() + if err := rides.Create(ride); err != nil { + t.Fatalf("建立訂單失敗: %v", err) + } + got, err := rides.GetByID(ride.ID) + if err != nil { + t.Fatalf("重讀訂單失敗: %v", err) + } + if got.RequiredVehicleType != "" { + t.Fatalf("未指定車種時應為空字串,得到 %q", got.RequiredVehicleType) + } + }) + + t.Run("白名單車種可寫入", func(t *testing.T) { + for _, v := range []string{"", "sedan", "suv", "van7", "accessible", "pet"} { + r := newRide() + r.RequiredVehicleType = v + if err := db.Create(r).Error; err != nil { + t.Fatalf("車種 %q 應為合法值: %v", v, err) + } + } + }) + + t.Run("非白名單車種由 DB CHECK 擋下", func(t *testing.T) { + r := newRide() + r.RequiredVehicleType = "spaceship" + err := db.Create(r).Error + if err == nil { + t.Fatal("非白名單車種不該寫得進去") + } + if !strings.Contains(strings.ToLower(err.Error()), "chk_rides_required_vehicle_type") { + t.Fatalf("應由 chk_rides_required_vehicle_type 擋下,實際錯誤: %v", err) + } + }) +} + +// P1 migration 可逆性:up → down 到 O1 為止 → 再 up。 +// down 寫壞平常沒人發現,等到要 rollback 才炸。 +func TestRideRequiredVehicleMigrationReversible(t *testing.T) { + ctx := context.Background() + container, err := tcpostgres.Run(ctx, "postgis/postgis:16-3.4", + tcpostgres.WithDatabase("test"), + tcpostgres.WithUsername("test"), + tcpostgres.WithPassword("test"), + tcpostgres.BasicWaitStrategies(), + ) + if err != nil { + t.Skipf("略過整合測試(Docker/testcontainers 不可用): %v", err) + } + t.Cleanup(func() { _ = container.Terminate(ctx) }) + + connStr, err := container.ConnectionString(ctx, "sslmode=disable") + if err != nil { + t.Fatalf("取得連線字串失敗: %v", err) + } + + m, err := migrate.New("file://../../db/migrations", connStr) + if err != nil { + t.Fatalf("建立 migrate 失敗: %v", err) + } + defer m.Close() + + if err := m.Up(); err != nil && err != migrate.ErrNoChange { + t.Fatalf("up 失敗: %v", err) + } + + db, err := gorm.Open(gormpostgres.Open(connStr), &gorm.Config{}) + if err != nil { + t.Fatalf("連線失敗: %v", err) + } + + hasColumn := func() bool { + var n int64 + db.Raw(`SELECT count(*) FROM information_schema.columns + WHERE table_name='rides' AND column_name='required_vehicle_type'`).Scan(&n) + return n > 0 + } + hasConstraint := func() bool { + var n int64 + db.Raw(`SELECT count(*) FROM pg_constraint WHERE conname='chk_rides_required_vehicle_type'`).Scan(&n) + return n > 0 + } + + if !hasColumn() { + t.Fatal("up 後應有 required_vehicle_type 欄位") + } + if !hasConstraint() { + t.Fatal("up 後應有車種 CHECK") + } + + // 以版本而非「往回一步」表達意圖:日後有人在 P1 之後加 migration, + // 這個測試仍然驗的是 P1 的 down。 + if err := m.Migrate(17); err != nil && err != migrate.ErrNoChange { + t.Fatalf("down 到 version 17 失敗: %v", err) + } + if hasColumn() { + t.Fatal("down 後不應還有 required_vehicle_type 欄位") + } + if hasConstraint() { + t.Fatal("down 後不應還有車種 CHECK") + } + + if err := m.Up(); err != nil && err != migrate.ErrNoChange { + t.Fatalf("再次 up 失敗: %v", err) + } + if !hasColumn() || !hasConstraint() { + t.Fatal("再次 up 後 P1 的欄位與 CHECK 應回來") + } +} diff --git a/internal/service/dispatch.go b/internal/service/dispatch.go index 7d4cb6c..c63fcb0 100644 --- a/internal/service/dispatch.go +++ b/internal/service/dispatch.go @@ -124,6 +124,11 @@ func (s *DispatchService) dispatchRound(rideID int64, attempt int, offered map[i if !driver.HasVehicle() { continue } + // P3:乘客指定車種時只派同車種的司機。**不降級**(P4 拍板)——寵物車/無障礙車是硬需求, + // 默默改派一般車=服務失敗還照收錢;找不到就讓它走 giveUpIfUnaccepted 明確取消。 + if ride.RequiredVehicleType != "" && driver.VehicleType != ride.RequiredVehicleType { + continue + } targets = append(targets, driver) } @@ -236,15 +241,38 @@ func (s *DispatchService) giveUpIfUnaccepted(rideID int64) { events.TypeRideCancelled, events.ActorSystem, nil, "dispatch_timeout") s.redis.ClearRejected(ctx, rideID) log.Warn().Int64("ride_id", rideID).Msg("逾時無人接單,訂單自動取消") + + reason, text, payload := giveUpCancelInfo(ride) if customerLineID, err := s.rides.GetCustomerLineUserID(rideID); err == nil && customerLineID != "" { - _ = s.line.PushText(ctx, customerLineID, "抱歉,附近暫無可用司機,請稍後再試") + _ = s.line.PushText(ctx, customerLineID, text) } + log.Warn().Int64("ride_id", rideID).Str("cancel_reason", reason).Msg("逾時取消原因") s.publish(events.Recipient{Role: events.RoleCustomer, ID: ride.CustomerID}, events.Event{ - Type: events.TypeRideCancelled, - RideID: rideID, + Type: events.TypeRideCancelled, + RideID: rideID, + Payload: payload, }) } +// giveUpCancelInfo 組出逾時取消的原因、給乘客的文案與 WS payload(P4)。 +// 指定了車種卻沒人接,多半是「附近沒有這種車」而非「沒有司機」——泛用文案會誤導乘客 +// 一直重試,而正確的引導是「改用不指定車種」。payload 帶機器可讀欄位, +// App 端不必去 parse 文案字串。 +func giveUpCancelInfo(ride *model.Ride) (reason, text string, payload map[string]any) { + if ride.RequiredVehicleType == "" { + return constants.CancelReasonNoDriver, + "抱歉,附近暫無可用司機,請稍後再試", + map[string]any{"cancel_reason": constants.CancelReasonNoDriver} + } + name := constants.VehicleTypeDisplayName(ride.RequiredVehicleType) + return constants.CancelReasonNoVehicleOfType, + fmt.Sprintf("抱歉,附近暫無%s,請稍後再試", name), + map[string]any{ + "cancel_reason": constants.CancelReasonNoVehicleOfType, + "required_vehicle_type": ride.RequiredVehicleType, + } +} + // CancelByCustomer 客戶主動取消進行中的訂單(尚未上車前)——LINE 入口,以 line_user_id 找目前進行中的訂單 func (s *DispatchService) CancelByCustomer(ctx context.Context, lineUserID string) (string, error) { customer, err := s.customers.FindByLineUserID(lineUserID) diff --git a/internal/service/dispatch_required_vehicle_test.go b/internal/service/dispatch_required_vehicle_test.go new file mode 100644 index 0000000..110f24c --- /dev/null +++ b/internal/service/dispatch_required_vehicle_test.go @@ -0,0 +1,216 @@ +package service + +import ( + "context" + "testing" + "time" + + "line-fleet-dispatch/internal/constants" + "line-fleet-dispatch/internal/events" + lineclient "line-fleet-dispatch/internal/line" + "line-fleet-dispatch/internal/model" + "line-fleet-dispatch/internal/repository" +) + +// TestGiveUpCancelInfo P4 的文案與 payload。純單元——不必起容器。 +func TestGiveUpCancelInfo(t *testing.T) { + t.Run("未指定車種維持泛用文案", func(t *testing.T) { + reason, text, payload := giveUpCancelInfo(&model.Ride{}) + if reason != constants.CancelReasonNoDriver { + t.Fatalf("預期 %s,得到 %s", constants.CancelReasonNoDriver, reason) + } + if text != "抱歉,附近暫無可用司機,請稍後再試" { + t.Fatalf("文案錯誤:%q", text) + } + if payload["cancel_reason"] != constants.CancelReasonNoDriver { + t.Fatalf("payload cancel_reason 錯誤:%v", payload) + } + // 沒指定車種就不該出現這個鍵,否則 App 會以為乘客指定過。 + if _, ok := payload["required_vehicle_type"]; ok { + t.Fatalf("未指定車種時不該帶 required_vehicle_type:%v", payload) + } + }) + + t.Run("指定車種時原因與文案都要具體", func(t *testing.T) { + reason, text, payload := giveUpCancelInfo(&model.Ride{RequiredVehicleType: constants.VehicleTypePet}) + if reason != constants.CancelReasonNoVehicleOfType { + t.Fatalf("預期 %s,得到 %s", constants.CancelReasonNoVehicleOfType, reason) + } + if text != "抱歉,附近暫無寵物用車,請稍後再試" { + t.Fatalf("文案應指出是車種問題,得到 %q", text) + } + if payload["cancel_reason"] != constants.CancelReasonNoVehicleOfType { + t.Fatalf("payload cancel_reason 錯誤:%v", payload) + } + // App 端靠這兩個機器可讀欄位判斷,不 parse 文案。 + if payload["required_vehicle_type"] != constants.VehicleTypePet { + t.Fatalf("payload 應帶 required_vehicle_type=pet:%v", payload) + } + }) +} + +// newRequiredVehicleFixture 一台寵物車、一台轎車,都在上車點附近待命且已填車輛資訊。 +func newRequiredVehicleFixture(t *testing.T, prefix string, offerTimeoutSec int) ( + *DispatchService, *fakePublisher, *repository.RideRepository, *repository.CustomerRepository, map[string]int64, +) { + t.Helper() + db := newServiceTestDB(t) + redisStore := newServiceTestRedis(t) + drivers := repository.NewDriverRepository(db) + rides := repository.NewRideRepository(db) + customers := repository.NewCustomerRepository(db) + fp := &fakePublisher{} + dispatch := NewDispatchService(drivers, rides, customers, redisStore, + lineclient.NewClient(""), NewETAService(nil), + NewDispatchSettings(3000, 5, offerTimeoutSec, 1, 5), fp) + + ids := map[string]int64{} + ctx := context.Background() + for _, spec := range []struct{ key, vType, plate string }{ + {constants.VehicleTypePet, constants.VehicleTypePet, prefix + "-PET"}, + {constants.VehicleTypeSedan, constants.VehicleTypeSedan, prefix + "-SED"}, + } { + d, err := drivers.FindOrCreate(prefix+"_"+spec.key, spec.key+"司機") + if err != nil { + t.Fatalf("建立司機失敗:%v", err) + } + if err := drivers.UpdateVehicle(d.ID, spec.vType, spec.plate); err != nil { + t.Fatalf("設定車輛失敗:%v", err) + } + if err := redisStore.UpdateDriverLocation(ctx, d.ID, 25.031, 121.561); err != nil { + t.Fatalf("寫入司機位置失敗:%v", err) + } + ids[spec.key] = d.ID + } + return dispatch, fp, rides, customers, ids +} + +func newRideWithVehicleType(t *testing.T, rides *repository.RideRepository, customerID int64, vType string) *model.Ride { + t.Helper() + now := time.Now() + ride := &model.Ride{ + CustomerID: customerID, + Status: constants.RideStatusRequested, + PickupPoint: model.GeoPoint{Lat: 25.03, Lng: 121.56}, + PickupAddress: "台北車站", + RequiredVehicleType: vType, + RequestedAt: now, + CreatedAt: now, + UpdatedAt: now, + } + if err := rides.Create(ride); err != nil { + t.Fatalf("建立訂單失敗:%v", err) + } + return ride +} + +// TestDispatch_指定車種只派同車種 P3:指定寵物車時,轎車司機不得收到派單。 +func TestDispatch_指定車種只派同車種(t *testing.T) { + dispatch, fp, rides, customers, ids := newRequiredVehicleFixture(t, "U_p3_match", 20) + + cust, err := customers.FindOrCreateByLineUserID("U_p3_match_cust", "寵物乘客") + if err != nil { + t.Fatalf("建立乘客失敗:%v", err) + } + ride := newRideWithVehicleType(t, rides, cust.ID, constants.VehicleTypePet) + + if err := dispatch.Dispatch(context.Background(), ride.ID); err != nil { + t.Fatalf("派單失敗:%v", err) + } + + var offeredTo []int64 + for _, r := range fp.recv { + if r.Ev.Type == events.TypeRideAssigned && r.Rec.Role == events.RoleDriver { + offeredTo = append(offeredTo, r.Rec.ID) + } + } + if len(offeredTo) != 1 || offeredTo[0] != ids[constants.VehicleTypePet] { + t.Fatalf("指定寵物車時只該派給寵物車司機 %d,實際派給 %v", ids[constants.VehicleTypePet], offeredTo) + } +} + +// TestDispatch_未指定車種時所有車種都可派 P3 不可讓既有(不指定)的單變窄。 +func TestDispatch_未指定車種時所有車種都可派(t *testing.T) { + dispatch, fp, rides, customers, _ := newRequiredVehicleFixture(t, "U_p3_any", 20) + + cust, err := customers.FindOrCreateByLineUserID("U_p3_any_cust", "一般乘客") + if err != nil { + t.Fatalf("建立乘客失敗:%v", err) + } + ride := newRideWithVehicleType(t, rides, cust.ID, "") + + if err := dispatch.Dispatch(context.Background(), ride.ID); err != nil { + t.Fatalf("派單失敗:%v", err) + } + + count := 0 + for _, r := range fp.recv { + if r.Ev.Type == events.TypeRideAssigned && r.Rec.Role == events.RoleDriver { + count++ + } + } + if count != 2 { + t.Fatalf("未指定車種時兩台都該收到派單,實際 %d 台", count) + } +} + +// TestDispatch_找不到指定車種時取消並帶原因 P3+P4 端到端: +// 沒有無障礙車 → 不降級(轎車/寵物車都不得收到派單)→ 逾時自動取消 → +// ride.cancelled 帶 cancel_reason=no_vehicle_of_type。 +func TestDispatch_找不到指定車種時取消並帶原因(t *testing.T) { + // offerTimeout 設 1 秒,讓 giveUpIfUnaccepted 在測試時間內觸發。 + dispatch, fp, rides, customers, _ := newRequiredVehicleFixture(t, "U_p3_none", 1) + + cust, err := customers.FindOrCreateByLineUserID("U_p3_none_cust", "無障礙乘客") + if err != nil { + t.Fatalf("建立乘客失敗:%v", err) + } + ride := newRideWithVehicleType(t, rides, cust.ID, constants.VehicleTypeAccessible) + + if err := dispatch.Dispatch(context.Background(), ride.ID); err != nil { + t.Fatalf("派單失敗:%v", err) + } + + // 不降級:一台都不該收到派單。 + for _, r := range fp.recv { + if r.Ev.Type == events.TypeRideAssigned { + t.Fatalf("沒有無障礙車時不得改派其他車種,卻派給了 %+v", r.Rec) + } + } + + // 等 giveUpIfUnaccepted(AfterFunc offerTimeout=1s)觸發。 + deadline := time.Now().Add(10 * time.Second) + var cancelled *events.Event + for time.Now().Before(deadline) { + fp.mu.Lock() + for i := range fp.recv { + if fp.recv[i].Ev.Type == events.TypeRideCancelled { + ev := fp.recv[i].Ev + cancelled = &ev + break + } + } + fp.mu.Unlock() + if cancelled != nil { + break + } + time.Sleep(200 * time.Millisecond) + } + if cancelled == nil { + t.Fatal("逾時無人接單應發出 ride.cancelled") + } + if cancelled.Payload["cancel_reason"] != constants.CancelReasonNoVehicleOfType { + t.Fatalf("cancel_reason 應為 no_vehicle_of_type,得到 %v", cancelled.Payload) + } + if cancelled.Payload["required_vehicle_type"] != constants.VehicleTypeAccessible { + t.Fatalf("payload 應帶 required_vehicle_type=accessible,得到 %v", cancelled.Payload) + } + + got, err := rides.GetByID(ride.ID) + if err != nil { + t.Fatalf("重讀訂單失敗:%v", err) + } + if got.Status != constants.RideStatusCancelled { + t.Fatalf("訂單應被自動取消,狀態為 %d", got.Status) + } +} diff --git a/internal/service/ride.go b/internal/service/ride.go index 4b8a7ef..17f0636 100644 --- a/internal/service/ride.go +++ b/internal/service/ride.go @@ -97,12 +97,14 @@ func (s *RideService) rateLimitPerMin() int { return rate } -// CustomerCreateRequest 乘客 App 下單輸入(含選填目的地)。 +// CustomerCreateRequest 乘客 App 下單輸入(含選填目的地與選填指定車種)。 type CustomerCreateRequest struct { PickupLat, PickupLng float64 PickupAddress string DropoffAddress string DropoffLat, DropoffLng *float64 + // RequiredVehicleType 選填(P2):'' =不指定,維持現行行為(任何車種都可派)。 + RequiredVehicleType string } // CreateByCustomer 供已登入乘客(App)直接叫車:身分取自 JWT 的 customer_id。 @@ -118,6 +120,11 @@ func (s *RideService) CreateByCustomer( if err := validateOptionalDropoffCoords(req.DropoffLat, req.DropoffLng); err != nil { return nil, err } + // 指定車種為選填;有給就必須是白名單 code(DB CHECK 是最後防線,但錯誤要在這裡 + // 變成 400 而不是讓 INSERT 撞 CHECK 回 500)。 + if req.RequiredVehicleType != "" && !constants.IsValidVehicleType(req.RequiredVehicleType) { + return nil, ErrInvalidVehicleType + } customer, err := s.customers.FindByID(customerID) if err != nil { @@ -142,14 +149,15 @@ func (s *RideService) CreateByCustomer( now := time.Now() ride := &model.Ride{ - CustomerID: customer.ID, - Status: constants.RideStatusRequested, - PickupPoint: model.GeoPoint{Lat: req.PickupLat, Lng: req.PickupLng}, - PickupAddress: req.PickupAddress, - DropoffAddress: req.DropoffAddress, - RequestedAt: now, - CreatedAt: now, - UpdatedAt: now, + CustomerID: customer.ID, + Status: constants.RideStatusRequested, + PickupPoint: model.GeoPoint{Lat: req.PickupLat, Lng: req.PickupLng}, + PickupAddress: req.PickupAddress, + DropoffAddress: req.DropoffAddress, + RequiredVehicleType: req.RequiredVehicleType, + RequestedAt: now, + CreatedAt: now, + UpdatedAt: now, } if req.DropoffLat != nil && req.DropoffLng != nil { ride.DropoffPoint = &model.GeoPoint{Lat: *req.DropoffLat, Lng: *req.DropoffLng} diff --git a/internal/service/ride_create_vehicle_type_test.go b/internal/service/ride_create_vehicle_type_test.go new file mode 100644 index 0000000..d81bf44 --- /dev/null +++ b/internal/service/ride_create_vehicle_type_test.go @@ -0,0 +1,138 @@ +package service + +import ( + "context" + "errors" + "testing" + + "line-fleet-dispatch/internal/constants" + lineclient "line-fleet-dispatch/internal/line" + "line-fleet-dispatch/internal/repository" +) + +func newVehicleTypeRideService(t *testing.T) (*RideService, *repository.RideRepository, *repository.CustomerRepository) { + t.Helper() + db := newServiceTestDB(t) + customers := repository.NewCustomerRepository(db) + rides := repository.NewRideRepository(db) + redis := newServiceTestRedis(t) + dispatch := NewDispatchService( + repository.NewDriverRepository(db), + rides, + customers, + redis, + lineclient.NewClient(""), + nil, NewDispatchSettings(3000, 5, 20, 1, 5), nil, + ) + return NewRideService(customers, rides, redis, dispatch), rides, customers +} + +// TestCreateByCustomer_指定車種持久化 P2:乘客指定的車種要真的落到 rides 上。 +// 重讀 DB 而非只看回傳值——RideRepository.Create 走 raw INSERT,漏掉欄位時 +// 回傳的 struct 仍然是對的,只有 DB 裡是空的。 +func TestCreateByCustomer_指定車種持久化(t *testing.T) { + svc, rides, customers := newVehicleTypeRideService(t) + + cust, err := customers.FindOrCreateByLineUserID("U_req_veh_pet", "寵物車乘客") + if err != nil { + t.Fatalf("建立乘客失敗:%v", err) + } + + dropoffLat, dropoffLng := 25.08, 121.57 + created, err := svc.CreateByCustomer(context.Background(), cust.ID, CustomerCreateRequest{ + PickupLat: 25.03, + PickupLng: 121.56, + PickupAddress: "台北車站", + DropoffAddress: "松山機場", + DropoffLat: &dropoffLat, + DropoffLng: &dropoffLng, + RequiredVehicleType: constants.VehicleTypePet, + }) + if err != nil { + t.Fatalf("下單失敗:%v", err) + } + + got, err := rides.GetByID(created.ID) + if err != nil { + t.Fatalf("讀回訂單失敗:%v", err) + } + if got.RequiredVehicleType != constants.VehicleTypePet { + t.Fatalf("DB 裡的 required_vehicle_type 應為 pet,得到 %q", got.RequiredVehicleType) + } +} + +// TestCreateByCustomer_指定車種持久化_無目的地 Create 有「帶/不帶 dropoff」兩條 raw INSERT, +// 兩條都要帶車種——只補其中一條,無目的地的單(LINE 建單常見)就會靜靜地掉車種。 +func TestCreateByCustomer_指定車種持久化_無目的地(t *testing.T) { + svc, rides, customers := newVehicleTypeRideService(t) + + cust, err := customers.FindOrCreateByLineUserID("U_req_veh_nodrop", "無目的地乘客") + if err != nil { + t.Fatalf("建立乘客失敗:%v", err) + } + + created, err := svc.CreateByCustomer(context.Background(), cust.ID, CustomerCreateRequest{ + PickupLat: 25.03, + PickupLng: 121.56, + PickupAddress: "台北車站", + RequiredVehicleType: constants.VehicleTypeAccessible, + }) + if err != nil { + t.Fatalf("下單失敗:%v", err) + } + + got, err := rides.GetByID(created.ID) + if err != nil { + t.Fatalf("讀回訂單失敗:%v", err) + } + if got.RequiredVehicleType != constants.VehicleTypeAccessible { + t.Fatalf("無目的地的單也該帶車種,得到 %q", got.RequiredVehicleType) + } +} + +// TestCreateByCustomer_未指定車種維持現行行為 P2 不可破壞既有 App/LINE 建單。 +func TestCreateByCustomer_未指定車種維持現行行為(t *testing.T) { + svc, rides, customers := newVehicleTypeRideService(t) + + cust, err := customers.FindOrCreateByLineUserID("U_req_veh_none", "一般乘客") + if err != nil { + t.Fatalf("建立乘客失敗:%v", err) + } + + created, err := svc.CreateByCustomer(context.Background(), cust.ID, CustomerCreateRequest{ + PickupLat: 25.03, + PickupLng: 121.56, + PickupAddress: "台北車站", + }) + if err != nil { + t.Fatalf("未帶車種的下單不該失敗:%v", err) + } + got, err := rides.GetByID(created.ID) + if err != nil { + t.Fatalf("讀回訂單失敗:%v", err) + } + if got.RequiredVehicleType != "" { + t.Fatalf("未指定車種應為空字串,得到 %q", got.RequiredVehicleType) + } +} + +// TestCreateByCustomer_非白名單車種回400 錯誤要在 service 就變成 ErrInvalidVehicleType, +// 而不是讓 INSERT 撞 DB CHECK——那會變成 500,乘客看到「伺服器錯誤」。 +func TestCreateByCustomer_非白名單車種被拒(t *testing.T) { + svc, _, customers := newVehicleTypeRideService(t) + + cust, err := customers.FindOrCreateByLineUserID("U_req_veh_bad", "亂填乘客") + if err != nil { + t.Fatalf("建立乘客失敗:%v", err) + } + + _, err = svc.CreateByCustomer(context.Background(), cust.ID, CustomerCreateRequest{ + PickupLat: 25.03, + PickupLng: 121.56, + PickupAddress: "台北車站", + RequiredVehicleType: "spaceship", + }) + if !errors.Is(err, ErrInvalidVehicleType) { + t.Fatalf("預期 ErrInvalidVehicleType,得到 %v", err) + } +}