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
4 changes: 4 additions & 0 deletions db/migrations/000017_add_driver_vehicle.down.sql
Original file line number Diff line number Diff line change
@@ -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;
19 changes: 19 additions & 0 deletions db/migrations/000017_add_driver_vehicle.up.sql
Original file line number Diff line number Diff line change
@@ -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 <> '';
33 changes: 25 additions & 8 deletions docs/TODO.md
Original file line number Diff line number Diff line change
Expand Up @@ -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,只能改自己的)。
Expand Down Expand Up @@ -430,8 +447,8 @@
### 風險與待拍板

1. ~~**車種自由文字 vs 選單**~~ ✅ **已拍板:選單**(轎車/休旅/七人座/無障礙/寵物用車),見 O1。
2. **車牌格式驗證**:台灣車牌格式多樣(舊式/新式/機車/電動車),過嚴會擋到真司機。
建議寬鬆格式 + 後台可修正。
2. **車牌格式驗證**(O2 要面對,O1 不管格式):台灣車牌格式多樣(舊式/新式/機車/電動車),
過嚴會擋到真司機。建議寬鬆格式 + 後台可修正。**O1 的 DB 層只保證唯一性,不驗格式。**
3. ~~**既有司機資料**~~ ✅ **已拍板:強制填寫、不設寬限期**,App 端強制跳轉引導,見 O3。
**營運提醒**:上線當下所有司機都會無法接單,需事前通知。
4. ~~**車輛異動**~~ ✅ **已拍板:rides 落車輛快照**+開放司機聯絡方式+沿用既有 chat 當留言板,見 O7。
Expand Down
40 changes: 40 additions & 0 deletions internal/constants/vehicle.go
Original file line number Diff line number Diff line change
@@ -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
}
28 changes: 28 additions & 0 deletions internal/constants/vehicle_test.go
Original file line number Diff line number Diff line change
@@ -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() 必須回副本,呼叫端不得改動白名單")
}
}
20 changes: 15 additions & 5 deletions internal/model/models.go
Original file line number Diff line number Diff line change
Expand Up @@ -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"
}
Expand Down
63 changes: 63 additions & 0 deletions internal/repository/driver_vehicle_integration_test.go
Original file line number Diff line number Diff line change
@@ -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)
}
})
}
104 changes: 104 additions & 0 deletions internal/repository/driver_vehicle_migration_test.go
Original file line number Diff line number Diff line change
@@ -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 的欄位/約束/索引應全部回來")
}
}
Loading