Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
1 change: 1 addition & 0 deletions cmd/server/main.go
Original file line number Diff line number Diff line change
Expand Up @@ -310,6 +310,7 @@ func main() {
ops.Use(middleware.RequireAdminRole(auth.RoleDispatcher))
{
ops.PATCH("/drivers/:id/status", adminHandler.PatchDriverStatus)
ops.POST("/drivers/:id/vehicle-review", adminHandler.ReviewDriverVehicle)
ops.PUT("/settings/dispatch", adminHandler.PutDispatchSettings)
ops.POST("/rides/:id/cancel", adminHandler.CancelRide)
}
Expand Down
3 changes: 3 additions & 0 deletions db/migrations/000022_add_driver_vehicle_review.down.sql
Original file line number Diff line number Diff line change
@@ -0,0 +1,3 @@
ALTER TABLE drivers DROP CONSTRAINT IF EXISTS chk_drivers_vehicle_review_status;
ALTER TABLE drivers DROP COLUMN IF EXISTS vehicle_review_note;
ALTER TABLE drivers DROP COLUMN IF EXISTS vehicle_review_status;
15 changes: 15 additions & 0 deletions db/migrations/000022_add_driver_vehicle_review.up.sql
Original file line number Diff line number Diff line change
@@ -0,0 +1,15 @@
-- 車輛審核(O5 定案 2026-07-19):司機填/改車輛後需 admin 核准才能接單。
-- O3 gate 從「有填車種車牌」升級為「已審核」;App 端多一種「待審核」等待狀態。
-- 沿用 drivers 既有慣例:TEXT NOT NULL DEFAULT ''。
ALTER TABLE drivers ADD COLUMN IF NOT EXISTS vehicle_review_status TEXT NOT NULL DEFAULT '';
ALTER TABLE drivers ADD COLUMN IF NOT EXISTS vehicle_review_note TEXT NOT NULL DEFAULT '';

-- 值域最後防線放 DB CHECK:gate 直接讀它,值髒掉會讓不該接單的司機接到單。
ALTER TABLE drivers DROP CONSTRAINT IF EXISTS chk_drivers_vehicle_review_status;
ALTER TABLE drivers ADD CONSTRAINT chk_drivers_vehicle_review_status
CHECK (vehicle_review_status IN ('', 'pending', 'approved', 'rejected'));

-- 祖父化:導入審核前既有已填車輛的司機一律視為已核准,不因導入審核而被鎖出
-- (O5 導入決策 2026-07-19;未填車輛者維持 '',仍走強制設定頁)。
UPDATE drivers SET vehicle_review_status = 'approved'
WHERE vehicle_type <> '' AND plate_number <> '' AND vehicle_review_status = '';
10 changes: 10 additions & 0 deletions internal/constants/vehicle.go
Original file line number Diff line number Diff line change
Expand Up @@ -17,6 +17,16 @@ const (
VehicleTypePet = "pet" // 寵物用車(乘客指定此車種時加收清潔費,見 O6/P)
)

// 車輛審核狀態(O5 定案 2026-07-19)。司機填/改車輛後進 Pending,admin 核准才能接單。
// 值域由 DB CHECK `chk_drivers_vehicle_review_status` 把關(migration 000022)。
// 導入時既有已填車輛的司機祖父化為 Approved(migration 一次性 UPDATE),不因導入被鎖出。
const (
VehicleReviewNone = "" // 未提交(沒填車輛)
VehicleReviewPending = "pending" // 待審核(填了/改了,等 admin)
VehicleReviewApproved = "approved" // 已核准(可接單)
VehicleReviewRejected = "rejected" // 已退回(附原因,可重填)
)

// vehicleTypes 白名單;順序即前端建議的顯示順序。
var vehicleTypes = []string{
VehicleTypeSedan,
Expand Down
33 changes: 33 additions & 0 deletions internal/handler/admin.go
Original file line number Diff line number Diff line change
Expand Up @@ -343,6 +343,39 @@ func (h *AdminHandler) PatchDriverStatus(c *gin.Context) {
c.JSON(http.StatusOK, gin.H{"driver": driver})
}

// ReviewDriverVehicle POST /api/admin/drivers/:id/vehicle-review — 車輛審核(O5)。
// body: {approve: bool, note?: string}。approve=false 時 note 必填(退回原因)。
func (h *AdminHandler) ReviewDriverVehicle(c *gin.Context) {
id, err := strconv.ParseInt(c.Param("id"), 10, 64)
if err != nil {
c.JSON(http.StatusBadRequest, gin.H{"error": "id 格式錯誤"})
return
}
var req struct {
Approve bool `json:"approve"`
Note string `json:"note"`
}
if err := c.ShouldBindJSON(&req); err != nil {
c.JSON(http.StatusBadRequest, gin.H{"error": "參數錯誤"})
return
}
driver, err := h.adminOps.ReviewDriverVehicle(id, req.Approve, strings.TrimSpace(req.Note))
if err != nil {
switch {
case errors.Is(err, service.ErrNotFound):
c.JSON(http.StatusNotFound, gin.H{"error": "找不到司機"})
case errors.Is(err, service.ErrVehicleNotPending):
c.JSON(http.StatusConflict, gin.H{"error": err.Error()})
case errors.Is(err, service.ErrRejectNoteRequired):
c.JSON(http.StatusBadRequest, gin.H{"error": err.Error()})
default:
c.JSON(http.StatusInternalServerError, gin.H{"error": err.Error()})
}
return
}
c.JSON(http.StatusOK, gin.H{"driver": driver})
}

// GetDispatchSettings GET /api/admin/settings/dispatch
func (h *AdminHandler) GetDispatchSettings(c *gin.Context) {
c.JSON(http.StatusOK, h.dispatchSettings.JSON())
Expand Down
15 changes: 10 additions & 5 deletions internal/handler/driver.go
Original file line number Diff line number Diff line change
Expand Up @@ -68,13 +68,18 @@ func (h *DriverHandler) Me(c *gin.Context) {
c.JSON(http.StatusOK, driverPublic(d))
}

// driverVehicle 車輛資訊的回應形狀(O2)。附 `has_vehicle` 讓 App 不必自行判斷
// 「兩欄皆非空」就知道能不能接單(與 O3 gate 同一條件)。
// driverVehicle 車輛資訊的回應形狀(O2/O5)。
// `has_vehicle`=填了沒(App 決定是否顯示強制設定頁);
// `review_status`=審核狀態(App 四態路由:pending 審核中/rejected 已退回+原因);
// `can_accept`=能不能接單(O5 gate =已核准),App 用它就不必自行推導審核邏輯。
func driverVehicle(d *model.Driver) gin.H {
return gin.H{
"vehicle_type": d.VehicleType,
"plate_number": d.PlateNumber,
"has_vehicle": d.HasVehicle(),
"vehicle_type": d.VehicleType,
"plate_number": d.PlateNumber,
"has_vehicle": d.HasVehicle(),
"review_status": d.VehicleReviewStatus,
"review_note": d.VehicleReviewNote,
"can_accept": d.VehicleApproved(),
}
}

Expand Down
21 changes: 16 additions & 5 deletions internal/model/models.go
Original file line number Diff line number Diff line change
Expand Up @@ -123,17 +123,28 @@ type Driver struct {
// 未設定的司機不得被派單/接單(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"`
PlateNumber string `gorm:"column:plate_number;not null;default:''" json:"plate_number"`
// VehicleReviewStatus 車輛審核狀態(O5):constants.VehicleReview* 之一。
// gate 讀它(approved 才能接單);填/改車輛→pending,admin 核准/退回改它。
VehicleReviewStatus string `gorm:"column:vehicle_review_status;not null;default:''" json:"vehicle_review_status"`
// VehicleReviewNote 退回原因(O5):rejected 時給司機看,其餘為空。
VehicleReviewNote string `gorm:"column:vehicle_review_note;not null;default:''" json:"vehicle_review_note"`
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)。
// HasVehicle 是否已填妥車輛資訊(O2)。是「填了沒」,不是「能不能接單」——
// 後者要看審核(VehicleApproved)。App 用它決定要不要顯示強制設定頁。
func (d Driver) HasVehicle() bool {
return d.VehicleType != "" && d.PlateNumber != ""
}

// VehicleApproved 車輛是否已通過審核(O5 gate):唯有已核准才得被派單/接單。
func (d Driver) VehicleApproved() bool {
return d.VehicleReviewStatus == "approved"
}

func (Driver) TableName() string {
return "drivers"
}
Expand Down
15 changes: 14 additions & 1 deletion internal/repository/repository.go
Original file line number Diff line number Diff line change
Expand Up @@ -219,14 +219,27 @@ func (r *DriverRepository) UpdateVehicle(id int64, vehicleType, plateNumber stri
err := r.db.Model(&model.Driver{}).Where("id = ?", id).Updates(map[string]interface{}{
"vehicle_type": vehicleType,
"plate_number": plateNumber,
"updated_at": time.Now(),
// O5:填/改車輛一律回 pending 並清掉退回原因——原子地與車輛欄位一起寫,
// 避免「改了車卻還掛著上一次的 approved」讓未審核的新車直接能接單。
"vehicle_review_status": constants.VehicleReviewPending,
"vehicle_review_note": "",
"updated_at": time.Now(),
}).Error
if isPlateConflict(err) {
return ErrPlateTaken
}
return err
}

// UpdateVehicleReview 後台審核結果(O5):approve→approved、reject→rejected+原因。
func (r *DriverRepository) UpdateVehicleReview(id int64, status, note string) error {
return r.db.Model(&model.Driver{}).Where("id = ?", id).Updates(map[string]interface{}{
"vehicle_review_status": status,
"vehicle_review_note": note,
"updated_at": time.Now(),
}).Error
}

// isPlateConflict 判斷是否為車牌唯一索引衝突。以 PgError 的 code + 約束名判斷,
// 不比對錯誤訊息字串(訊息會隨 Postgres 版本/語系變動)。
func isPlateConflict(err error) bool {
Expand Down
26 changes: 26 additions & 0 deletions internal/service/admin_operations.go
Original file line number Diff line number Diff line change
Expand Up @@ -59,6 +59,32 @@ func (a *AdminOperations) SetDriverEnabled(ctx context.Context, driverID int64,
return d, nil
}

// ReviewDriverVehicle 後台審核司機車輛(O5)。approve→approved(清原因);
// reject→rejected+原因。只有「待審核」的司機能審——避免誤審已核准者或沒填車輛者。
// 退回必須附原因(司機要知道哪裡不對才能修)。
func (a *AdminOperations) ReviewDriverVehicle(driverID int64, approve bool, note string) (*model.Driver, error) {
d, err := a.drivers.FindByID(driverID)
if err != nil {
return nil, ErrNotFound
}
if d.VehicleReviewStatus != constants.VehicleReviewPending {
return nil, ErrVehicleNotPending
}
status, resultNote := constants.VehicleReviewApproved, ""
if !approve {
if note == "" {
return nil, ErrRejectNoteRequired
}
status, resultNote = constants.VehicleReviewRejected, note
}
if err := a.drivers.UpdateVehicleReview(driverID, status, resultNote); err != nil {
return nil, err
}
d.VehicleReviewStatus = status
d.VehicleReviewNote = resultNote
return d, nil
}

// CancelRideByAdmin 後台強制取消訂單(沿用 cancelActiveRide 核心,已上車不可取消)。
func (a *AdminOperations) CancelRideByAdmin(ctx context.Context, rideID int64) (string, error) {
ride, err := a.dispatch.rides.GetByID(rideID)
Expand Down
91 changes: 91 additions & 0 deletions internal/service/admin_operations_test.go
Original file line number Diff line number Diff line change
Expand Up @@ -77,3 +77,94 @@ func TestSetDriverEnabled_載客中不可停用(t *testing.T) {
t.Fatalf("載客中停用預期 ErrDriverOnTrip,得到 %v", err)
}
}

// TestReviewDriverVehicle O5:admin 車輛審核 approve/reject/退回需原因/僅待審核可審。
func TestReviewDriverVehicle(t *testing.T) {
db := newServiceTestDB(t)
drivers := repository.NewDriverRepository(db)
rides := repository.NewRideRepository(db)
customers := repository.NewCustomerRepository(db)
redisStore := newServiceTestRedis(t)
settings := NewDispatchSettings(3000, 5, 20, 1, 5)
dispatch := NewDispatchService(drivers, rides, customers, redisStore, lineclient.NewClient(""), nil, settings, nil)
ops := NewAdminOperations(drivers, dispatch, redisStore, settings)
reg := NewDriverRegistry(drivers)

newPending := func(t *testing.T, lineID, plate string) int64 {
t.Helper()
d, err := drivers.FindOrCreate(lineID, "審核測試司機")
if err != nil {
t.Fatalf("建立司機失敗:%v", err)
}
if _, err := reg.SetVehicle(d.ID, constants.VehicleTypeSedan, plate); err != nil {
t.Fatalf("填車輛失敗:%v", err)
}
return d.ID
}

t.Run("核准後可接單", func(t *testing.T) {
id := newPending(t, "U_rev_ok", "REV-0001")
got, err := ops.ReviewDriverVehicle(id, true, "")
if err != nil {
t.Fatalf("核准失敗:%v", err)
}
if got.VehicleReviewStatus != constants.VehicleReviewApproved || !got.VehicleApproved() {
t.Fatalf("核准後應 approved,得到 %q", got.VehicleReviewStatus)
}
})

t.Run("退回附原因,狀態為 rejected", func(t *testing.T) {
id := newPending(t, "U_rev_rej", "REV-0002")
got, err := ops.ReviewDriverVehicle(id, false, "車牌照片模糊")
if err != nil {
t.Fatalf("退回失敗:%v", err)
}
if got.VehicleReviewStatus != constants.VehicleReviewRejected {
t.Fatalf("退回後應 rejected,得到 %q", got.VehicleReviewStatus)
}
if got.VehicleReviewNote != "車牌照片模糊" {
t.Fatalf("退回原因應保留,得到 %q", got.VehicleReviewNote)
}
if got.VehicleApproved() {
t.Fatal("退回的司機不該能接單")
}
})

t.Run("退回未附原因回 ErrRejectNoteRequired", func(t *testing.T) {
id := newPending(t, "U_rev_noreason", "REV-0003")
if _, err := ops.ReviewDriverVehicle(id, false, ""); !errors.Is(err, ErrRejectNoteRequired) {
t.Fatalf("預期 ErrRejectNoteRequired,得到 %v", err)
}
})

t.Run("非待審核狀態不可審(已核准者重審回 ErrVehicleNotPending)", func(t *testing.T) {
id := newPending(t, "U_rev_twice", "REV-0004")
if _, err := ops.ReviewDriverVehicle(id, true, ""); err != nil {
t.Fatalf("首次核准失敗:%v", err)
}
if _, err := ops.ReviewDriverVehicle(id, true, ""); !errors.Is(err, ErrVehicleNotPending) {
t.Fatalf("已核准者重審預期 ErrVehicleNotPending,得到 %v", err)
}
})

t.Run("改車輛回 pending 後可再審", func(t *testing.T) {
id := newPending(t, "U_rev_rechange", "REV-0005")
if _, err := ops.ReviewDriverVehicle(id, true, ""); err != nil {
t.Fatalf("核准失敗:%v", err)
}
// 改車輛 → 回 pending(O5:任何改動都要重審)。
if _, err := reg.SetVehicle(id, constants.VehicleTypeSUV, "REV-0006"); err != nil {
t.Fatalf("改車輛失敗:%v", err)
}
d, err := drivers.FindByID(id)
if err != nil {
t.Fatalf("重讀失敗:%v", err)
}
if d.VehicleReviewStatus != constants.VehicleReviewPending {
t.Fatalf("改車輛後應回 pending,得到 %q", d.VehicleReviewStatus)
}
if _, err := ops.ReviewDriverVehicle(id, true, ""); err != nil {
t.Fatalf("重審核准失敗:%v", err)
}
})
}
16 changes: 10 additions & 6 deletions internal/service/dispatch.go
Original file line number Diff line number Diff line change
Expand Up @@ -144,8 +144,8 @@ func (s *DispatchService) dispatchRound(rideID int64, attempt int, offered map[i
if err != nil || driver.Status != constants.DriverStatusIdle {
continue
}
// O3 gate:未填車種/車牌者不派單。既有司機一律如此,直到填完(拍板:無寬限期)。
if !driver.HasVehicle() {
// O5 gate:車輛未通過審核者不派單(O3「有填」升級為「已審核」,拍板:無寬限期)。
if !driver.VehicleApproved() {
continue
}
// P3:乘客指定車種時只派同車種的司機。**不降級**(P4 拍板)——寵物車/無障礙車是硬需求,
Expand Down Expand Up @@ -502,12 +502,16 @@ func (s *DispatchService) AcceptRide(ctx context.Context, rideID, driverID int64
s.redis.ReleaseRideLock(ctx, rideID)
return "", err
}
// O3 gate:未填車輛資訊者不得接單。派單已先過濾(dispatchRound),這裡擋的是
// O5 gate:車輛未通過審核者不得接單。派單已先過濾(dispatchRound),這裡擋的是
// 直接打 API/LINE 的路徑——只靠 App 端跳轉擋不住。
// 排在狀態檢查之前:這是接單資格問題,回「非待命狀態」會讓司機不知道要去填車輛。
if !driver.HasVehicle() {
// 排在狀態檢查之前:這是接單資格問題,回「非待命狀態」會讓司機不知道原因。
// 分「沒填」與「填了待審核」兩種訊息,司機才知道下一步該做什麼。
if !driver.VehicleApproved() {
s.redis.ReleaseRideLock(ctx, rideID)
return "", ErrDriverNoVehicle
if !driver.HasVehicle() {
return "", ErrDriverNoVehicle
}
return "", ErrDriverNotApproved
}
if driver.Status != constants.DriverStatusIdle {
s.redis.ReleaseRideLock(ctx, rideID)
Expand Down
4 changes: 4 additions & 0 deletions internal/service/dispatch_required_vehicle_test.go
Original file line number Diff line number Diff line change
Expand Up @@ -77,6 +77,10 @@ func newRequiredVehicleFixture(t *testing.T, prefix string, offerTimeoutSec int)
if err := drivers.UpdateVehicle(d.ID, spec.vType, spec.plate); err != nil {
t.Fatalf("設定車輛失敗:%v", err)
}
// O5:填車輛只到 pending,這批測試司機都要核准才進得了派單候選。
if err := drivers.UpdateVehicleReview(d.ID, constants.VehicleReviewApproved, ""); err != nil {
t.Fatalf("核准車輛失敗:%v", err)
}
if err := redisStore.UpdateDriverLocation(ctx, d.ID, 25.031, 121.561); err != nil {
t.Fatalf("寫入司機位置失敗:%v", err)
}
Expand Down
Loading
Loading