diff --git a/db/migrations/000017_add_driver_vehicle.down.sql b/db/migrations/000017_add_driver_vehicle.down.sql new file mode 100644 index 0000000..7f13b68 --- /dev/null +++ b/db/migrations/000017_add_driver_vehicle.down.sql @@ -0,0 +1,4 @@ +DROP INDEX IF EXISTS uq_drivers_plate_number; +ALTER TABLE drivers DROP CONSTRAINT IF EXISTS chk_drivers_vehicle_type; +ALTER TABLE drivers DROP COLUMN IF EXISTS plate_number; +ALTER TABLE drivers DROP COLUMN IF EXISTS vehicle_type; diff --git a/db/migrations/000017_add_driver_vehicle.up.sql b/db/migrations/000017_add_driver_vehicle.up.sql new file mode 100644 index 0000000..f777f8f --- /dev/null +++ b/db/migrations/000017_add_driver_vehicle.up.sql @@ -0,0 +1,19 @@ +-- 司機車輛資訊(O1):乘客端要顯示「搭的是什麼車」,且司機未填車輛資訊不得被派單/接單(O3 的 gate)。 +-- 沿用 drivers 既有慣例:TEXT NOT NULL DEFAULT '','' 代表未設定。 +-- 既有司機一律為未設定,上線後必須自行填寫(不設寬限期,2026-07-16 拍板)。 +ALTER TABLE drivers ADD COLUMN IF NOT EXISTS vehicle_type TEXT NOT NULL DEFAULT ''; +ALTER TABLE drivers ADD COLUMN IF NOT EXISTS plate_number TEXT NOT NULL DEFAULT ''; + +-- 車種白名單(O1 定案):sedan 轎車/suv 休旅/van7 七人座/accessible 無障礙/pet 寵物用車。 +-- 後端只認 code,顯示名稱由前端對應;'' 為未設定。 +-- 放 DB CHECK 而不只在 API 驗證:這是清潔費(O6)與派單過濾(P3)的判斷依據, +-- 值一旦髒掉會直接影響計費,最後防線要在資料層。 +ALTER TABLE drivers DROP CONSTRAINT IF EXISTS chk_drivers_vehicle_type; +ALTER TABLE drivers ADD CONSTRAINT chk_drivers_vehicle_type + CHECK (vehicle_type IN ('', 'sedan', 'suv', 'van7', 'accessible', 'pet')); + +-- 車牌唯一:同一車牌不該同時掛兩個司機帳號。 +-- 必須是 partial index —— 既有司機的 plate_number 都是 '', +-- 若用一般 UNIQUE,第二個未填車牌的司機就會撞唯一鍵而插不進去。 +CREATE UNIQUE INDEX IF NOT EXISTS uq_drivers_plate_number + ON drivers (plate_number) WHERE plate_number <> ''; diff --git a/docs/TODO.md b/docs/TODO.md index 22413d7..7d3f0c8 100644 --- a/docs/TODO.md +++ b/docs/TODO.md @@ -350,12 +350,29 @@ ### 施作項目 -- [ ] **O1. `drivers` 加車輛欄位**(新 migration) - `vehicle_type`(車種,**選單值**)、`plate_number`(車牌)、`vehicle_color`(可選)。 - **車種為選單** ✅ 已定案(2026-07-16):`sedan`(轎車)/`suv`(休旅)/`van7`(七人座)/ - `accessible`(無障礙)/`pet`(寵物用車)。存 enum 字串或 smallint(實作時定), - **顯示名稱在前端對應**,後端只認 code。非白名單值回 400。 - **車牌唯一性**:建議 `UNIQUE(plate_number)`(同一車牌不該同時掛兩個司機帳號)——待拍板。 +- [x] **O1. `drivers` 加車輛欄位** ✅ **已實作(2026-07-16,migration `000017`)** + `vehicle_type`/`plate_number`,沿用 drivers 既有慣例 `TEXT NOT NULL DEFAULT ''`(`''` =未設定)。 + **`vehicle_color` 不做**(YAGNI):需求只要求顯示車種與車牌,日後要再加。 + + **實作時定的兩件事**: + 1. **車種存字串 + DB CHECK**(非 smallint):`chk_drivers_vehicle_type` + 限定 `('', 'sedan', 'suv', 'van7', 'accessible', 'pet')`。 + 放資料層而不只在 API 驗證——它是清潔費(O6)與派單過濾(P3)的判斷依據,值髒掉直接影響計費。 + Go 端白名單在 `internal/constants/vehicle.go`(`IsValidVehicleType` 刻意**不接受空字串**, + 避免 API 收到空值當合法而繞過 O3 gate)。 + 2. **車牌唯一性 ✅ 拍板:partial unique index** + `uq_drivers_plate_number ON drivers(plate_number) WHERE plate_number <> ''`。 + **不可用一般 `UNIQUE`**——既有司機 `plate_number` 全是 `''`,一般唯一鍵會讓 + 第二個未填車牌的司機直接插不進去。**已用測試釘住**(反向驗證:改成一般 UNIQUE 該案即 FAIL)。 + + **驗收**:`go build`/`vet` 綠;`internal/constants` 單元測試(白名單、防禦性副本); + 整合測試(真 PostGIS 容器 + 跑完整 migration)—— + `TestDriverVehicleSchema`(多筆空車牌不衝突/車牌非空時唯一/CHECK 擋非白名單)、 + `TestDriverVehicleMigrationReversible`(up → down → 再 up,欄位/CHECK/index 正確消失與回來)。 + 反向驗證:一般 UNIQUE → 空車牌案 FAIL;down 漏 `DROP COLUMN` → 可逆性測試 FAIL。 + + **順帶記錄的 Postgres 行為**:`DROP COLUMN` 會自動連帶刪除依賴該欄位的 CHECK 與 index, + 故 down 裡的 `DROP CONSTRAINT`/`DROP INDEX` 其實冗餘——保留是為了明示意圖(`IF EXISTS`,無害)。 - [ ] **O2. 車輛資訊 API** `GET/PUT /api/driver/vehicle`(driver JWT,只能改自己的)。 @@ -430,8 +447,8 @@ ### 風險與待拍板 1. ~~**車種自由文字 vs 選單**~~ ✅ **已拍板:選單**(轎車/休旅/七人座/無障礙/寵物用車),見 O1。 -2. **車牌格式驗證**:台灣車牌格式多樣(舊式/新式/機車/電動車),過嚴會擋到真司機。 - 建議寬鬆格式 + 後台可修正。 +2. **車牌格式驗證**(O2 要面對,O1 不管格式):台灣車牌格式多樣(舊式/新式/機車/電動車), + 過嚴會擋到真司機。建議寬鬆格式 + 後台可修正。**O1 的 DB 層只保證唯一性,不驗格式。** 3. ~~**既有司機資料**~~ ✅ **已拍板:強制填寫、不設寬限期**,App 端強制跳轉引導,見 O3。 **營運提醒**:上線當下所有司機都會無法接單,需事前通知。 4. ~~**車輛異動**~~ ✅ **已拍板:rides 落車輛快照**+開放司機聯絡方式+沿用既有 chat 當留言板,見 O7。 diff --git a/internal/constants/vehicle.go b/internal/constants/vehicle.go new file mode 100644 index 0000000..7343170 --- /dev/null +++ b/internal/constants/vehicle.go @@ -0,0 +1,40 @@ +package constants + +// 車種 code(O1 定案 2026-07-16)。後端只認 code,顯示名稱由前端對應 +// (轎車/休旅/七人座/無障礙/寵物用車)。 +// 值域同時由 DB CHECK `chk_drivers_vehicle_type` 把關(migration 000017)—— +// 這是清潔費(O6)與派單車種過濾(P3)的判斷依據,值髒掉會直接影響計費。 +const ( + VehicleTypeSedan = "sedan" // 轎車 + VehicleTypeSUV = "suv" // 休旅 + VehicleTypeVan7 = "van7" // 七人座 + VehicleTypeAccessible = "accessible" // 無障礙 + VehicleTypePet = "pet" // 寵物用車(乘客指定此車種時加收清潔費,見 O6/P) +) + +// vehicleTypes 白名單;順序即前端建議的顯示順序。 +var vehicleTypes = []string{ + VehicleTypeSedan, + VehicleTypeSUV, + VehicleTypeVan7, + VehicleTypeAccessible, + VehicleTypePet, +} + +// VehicleTypes 回傳白名單副本(呼叫端不得改動內部切片)。 +func VehicleTypes() []string { + out := make([]string, len(vehicleTypes)) + copy(out, vehicleTypes) + return out +} + +// IsValidVehicleType 是否為合法車種 code。空字串(未設定)**不算合法**—— +// 呼叫端若要允許「未設定」需自行另判,避免 API 不小心接受空車種而繞過 O3 gate。 +func IsValidVehicleType(s string) bool { + for _, v := range vehicleTypes { + if v == s { + return true + } + } + return false +} diff --git a/internal/constants/vehicle_test.go b/internal/constants/vehicle_test.go new file mode 100644 index 0000000..cfce3a5 --- /dev/null +++ b/internal/constants/vehicle_test.go @@ -0,0 +1,28 @@ +package constants + +import "testing" + +func TestIsValidVehicleType(t *testing.T) { + for _, v := range []string{"sedan", "suv", "van7", "accessible", "pet"} { + if !IsValidVehicleType(v) { + t.Fatalf("%q 應為合法車種", v) + } + } + // 空字串=未設定,**不算合法車種**:避免 API 收到空值就當合法而繞過 O3 的 gate。 + for _, v := range []string{"", "SEDAN", "car", "寵物", "pet "} { + if IsValidVehicleType(v) { + t.Fatalf("%q 不該被當成合法車種", v) + } + } +} + +func TestVehicleTypesIsDefensiveCopy(t *testing.T) { + got := VehicleTypes() + if len(got) != 5 { + t.Fatalf("預期 5 種車種,得到 %d", len(got)) + } + got[0] = "tampered" + if VehicleTypes()[0] != VehicleTypeSedan { + t.Fatal("VehicleTypes() 必須回副本,呼叫端不得改動白名單") + } +} diff --git a/internal/model/models.go b/internal/model/models.go index 7cd8ed8..d757275 100644 --- a/internal/model/models.go +++ b/internal/model/models.go @@ -114,16 +114,26 @@ func (Customer) TableName() string { } type Driver struct { - ID int64 `gorm:"primaryKey"` - LineUserID string `gorm:"column:line_user_id;uniqueIndex;not null"` - Name string `gorm:"not null;default:''"` - Phone string `gorm:"not null;default:''"` - Status int16 `gorm:"not null;default:0"` + ID int64 `gorm:"primaryKey"` + LineUserID string `gorm:"column:line_user_id;uniqueIndex;not null"` + Name string `gorm:"not null;default:''"` + Phone string `gorm:"not null;default:''"` + Status int16 `gorm:"not null;default:0"` + // VehicleType 車種 code(O1):constants.VehicleType* 之一;'' 為未設定。 + // 未設定的司機不得被派單/接單(O3),且它是清潔費(O6)與派單車種過濾(P3)的判斷依據。 + VehicleType string `gorm:"column:vehicle_type;not null;default:''" json:"vehicle_type"` + // PlateNumber 車牌(O1):非空時唯一(partial unique index),'' 為未設定。 + PlateNumber string `gorm:"column:plate_number;not null;default:''" json:"plate_number"` PasswordHash string `gorm:"column:password_hash;not null;default:''" json:"-"` CreatedAt time.Time `gorm:"not null"` UpdatedAt time.Time `gorm:"not null"` } +// HasVehicle 是否已填妥車輛資訊;未填者不得被派單/接單(O3 gate)。 +func (d Driver) HasVehicle() bool { + return d.VehicleType != "" && d.PlateNumber != "" +} + func (Driver) TableName() string { return "drivers" } diff --git a/internal/repository/driver_vehicle_integration_test.go b/internal/repository/driver_vehicle_integration_test.go new file mode 100644 index 0000000..16e3f80 --- /dev/null +++ b/internal/repository/driver_vehicle_integration_test.go @@ -0,0 +1,63 @@ +package repository + +import ( + "strings" + "testing" + + "line-fleet-dispatch/internal/model" +) + +// O1 的 schema 保證:跑真 migration 後驗車種 CHECK 與車牌 partial unique index。 +// 這兩條是清潔費(O6)與派單過濾(P3)的地基,值髒掉會直接影響計費,故釘在資料層。 +func TestDriverVehicleSchema(t *testing.T) { + db := newMigratedTestDB(t) + + newDriver := func(lineID, vType, plate string) *model.Driver { + return &model.Driver{ + LineUserID: lineID, + Name: "測試司機", + VehicleType: vType, + PlateNumber: plate, + } + } + + t.Run("既有司機(未填車輛)可正常建立,且多筆空車牌不互相衝突", func(t *testing.T) { + // 這是 partial unique index 的存在理由:一般 UNIQUE 會讓第二筆空車牌撞唯一鍵, + // 既有司機(plate_number='') 全部插不進去。 + if err := db.Create(newDriver("u_empty_1", "", "")).Error; err != nil { + t.Fatalf("第一位未填車輛的司機應可建立: %v", err) + } + if err := db.Create(newDriver("u_empty_2", "", "")).Error; err != nil { + t.Fatalf("第二位未填車輛的司機也應可建立(空車牌不受唯一約束): %v", err) + } + }) + + t.Run("車牌非空時唯一", func(t *testing.T) { + if err := db.Create(newDriver("u_plate_1", "sedan", "ABC-1234")).Error; err != nil { + t.Fatalf("建立第一台車應成功: %v", err) + } + err := db.Create(newDriver("u_plate_2", "suv", "ABC-1234")).Error + if err == nil { + t.Fatal("同一車牌不該能掛在兩個司機帳號上") + } + if !strings.Contains(strings.ToLower(err.Error()), "uq_drivers_plate_number") { + t.Fatalf("應由 uq_drivers_plate_number 擋下,實際錯誤: %v", err) + } + }) + + t.Run("車種白名單由 DB CHECK 把關", func(t *testing.T) { + for _, ok := range []string{"", "sedan", "suv", "van7", "accessible", "pet"} { + d := newDriver("u_ok_"+ok, ok, "PLATE-"+ok) + if err := db.Create(d).Error; err != nil { + t.Fatalf("車種 %q 應為合法值: %v", ok, err) + } + } + err := db.Create(newDriver("u_bad", "spaceship", "ZZZ-9999")).Error + if err == nil { + t.Fatal("非白名單車種不該寫得進去") + } + if !strings.Contains(strings.ToLower(err.Error()), "chk_drivers_vehicle_type") { + t.Fatalf("應由 chk_drivers_vehicle_type 擋下,實際錯誤: %v", err) + } + }) +} diff --git a/internal/repository/driver_vehicle_migration_test.go b/internal/repository/driver_vehicle_migration_test.go new file mode 100644 index 0000000..0e92e23 --- /dev/null +++ b/internal/repository/driver_vehicle_migration_test.go @@ -0,0 +1,104 @@ +package repository + +import ( + "context" + "testing" + + "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" +) + +// O1 migration 可逆性:up → down 1 步 → 再 up,欄位/約束都要正確消失與回來。 +// down 寫壞(例如漏 DROP CONSTRAINT)平常不會有人發現,等到要 rollback 時才炸。 +func TestDriverVehicleMigrationReversible(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(col string) bool { + var n int64 + db.Raw(`SELECT count(*) FROM information_schema.columns + WHERE table_name='drivers' AND column_name=?`, col).Scan(&n) + return n > 0 + } + hasConstraint := func(name string) bool { + var n int64 + db.Raw(`SELECT count(*) FROM pg_constraint WHERE conname=?`, name).Scan(&n) + return n > 0 + } + hasIndex := func(name string) bool { + var n int64 + db.Raw(`SELECT count(*) FROM pg_indexes WHERE indexname=?`, name).Scan(&n) + return n > 0 + } + + // up 後:欄位、CHECK、partial unique index 都在 + for _, col := range []string{"vehicle_type", "plate_number"} { + if !hasColumn(col) { + t.Fatalf("up 後應有欄位 %s", col) + } + } + if !hasConstraint("chk_drivers_vehicle_type") { + t.Fatal("up 後應有車種 CHECK") + } + if !hasIndex("uq_drivers_plate_number") { + t.Fatal("up 後應有車牌 partial unique index") + } + + // down 一步:O1 的產物要全部消失(含 CHECK 與 index,不能只 drop 欄位) + if err := m.Steps(-1); err != nil { + t.Fatalf("down 失敗: %v", err) + } + for _, col := range []string{"vehicle_type", "plate_number"} { + if hasColumn(col) { + t.Fatalf("down 後不應還有欄位 %s", col) + } + } + if hasConstraint("chk_drivers_vehicle_type") { + t.Fatal("down 後不應還有車種 CHECK") + } + if hasIndex("uq_drivers_plate_number") { + t.Fatal("down 後不應還有車牌 index") + } + + // 再 up:可重複套用 + if err := m.Up(); err != nil && err != migrate.ErrNoChange { + t.Fatalf("再次 up 失敗: %v", err) + } + if !hasColumn("vehicle_type") || !hasConstraint("chk_drivers_vehicle_type") || + !hasIndex("uq_drivers_plate_number") { + t.Fatal("再次 up 後 O1 的欄位/約束/索引應全部回來") + } +}