---
schema: "hl-changelog/v2"
ticket: "5574"
title: "派车候选透传常驻司机赛季状态并对拉黑常驻给出明确自动代入原因"
consumer: "admin"
author: "wx(GIT)"
change_type: "修改接口"
backend_status: "deployed"
gateway_status: "verified"
frontend_status: "implemented"
frontend_owner: "pi-main-session"
frontend_ref: "hl-admin@d97cc730b019f5947766f3778e2f5b3ca03a5280"
target_release: "v2.1"
verified_at: "2026-08-06"
status_note: "后端完成：PR #5582 已合并 dev-v3 并部署 TEST，网关验证 3/3 通过。候选车辆 VO 新增 primaryDriverSeason 字段（新增字段，兼容）；suggestedDriverReason 新增 RESIDENT_BLACKLISTED 值（新增值，兼容）。前端可在车辆候选行标注'常驻司机已拉黑'，并在自动代入提示中区分拉黑与档期冲突。"
updated_at: "2026-08-06"
base: "dev-v3"
generated: "2026-08-06T09:40:00+08:00"
---

# 派车候选透传常驻司机赛季状态并对拉黑常驻给出明确自动代入原因

> 后端完成：PR #5582 已合并 dev-v3 并部署 TEST，网关验证 3/3 通过。

## 关联 / 联系人

### 链接

- **Issue**: [#5574](https://git.1814.love:8443/wx/HL/issues/5574)
- **PR**: [#5582](https://git.1814.love:8443/wx/HL/pulls/5582)
- **Merge commit**: [83dd24d1b](https://git.1814.love:8443/wx/HL/commit/83dd24d1b)

### 联系人

- **后端负责人**: @wx

## 背景

工单 #5574 三个现象经 TEST 库实证 + 候选链路代码核对，**均为测试环境数据状态**而非候选过滤 bug：

1. 巴特尔（`2065272153565020161`）`season=blacklist`（06-15 拉黑 reason=4444）——司机候选 SQL 按 `season=ACTIVE` 过滤，黑名单司机不进候选是业务正确语义（#5139 契约：黑名单仍按现有业务守卫阻断）；另一同名 active 巴特尔已软删（06-12）
2. 蒙A-G8888 `vehicle_status=busy`（今日起 08-14~26 有 9 条在途 assigned 派单，正确）但候选区间 08-28~31 无冲突显示"所选服务日期内可用"（也正确）——两者口径不同但不矛盾，候选 VO 已透传 `vehicleStatus` 供前端展示
3. 测A88V01 已软删（06-12 创建 20 秒后删除）——车辆候选 @TableLogic 自动过滤软删，正确

## 变更接口

| 方法 | 路径 | 来源 |
|---|---|---|
| `POST` | `/admin/fleet/assignments/candidates` | `AssignmentController`（fleet） |

路径前缀 `/admin/fleet/**` 已由网关登录/角色校验收口，无需新增网关规则。**兼容性**：仅新增字段与新增枚举值，无删除/无类型变化。

## 行为变化

### 车辆候选新增字段

| 字段 | 类型 | 说明 |
|---|---|---|
| `primaryDriverSeason` | String/null | 常驻司机赛季状态（`active`/`pending`/`archived`/`blacklist`）；无常驻或常驻已软删为 `null` |

车辆候选此前显示常驻司机姓名（`primaryDriverName`）但司机候选无此人（blacklist 被正确排除）时，前端无法向用户解释"常驻司机去哪了"；新增字段后可按 `primaryDriverSeason=blacklist` 标注"常驻司机已拉黑"。

### suggestedDriverReason 新增枚举值

| 值 | 语义 |
|---|---|
| `RESIDENT_BLACKLISTED` | 常驻司机已拉黑（season=blacklist），已回退自动代入空闲司机 |

此前已选车辆常驻司机为 blacklist 时，`getAssignmentCandidate` 返回 null（与档期冲突/休整同落 null），自动代入回退原因误报 `RESIDENT_BUSY_FALLBACK`（"常驻司机不空闲"）；现按 season 区分，返回 `RESIDENT_BLACKLISTED`（"常驻司机已拉黑"）。既有 `RESIDENT_BUSY_FALLBACK` 语义不变（档期冲突/休整/待激活/停用）。

## 前端/调用方动作

1. 车辆候选行可按 `primaryDriverSeason === "blacklist"` 显示"常驻司机已拉黑"标注（可选优化）
2. 自动代入提示按 `suggestedDriverReason` 展示后端 message（`RESIDENT_BLACKLISTED` 已有明确文案）
3. `vehicleStatus` 已透传（busy=今日起有在途派单），可在候选行展示"当前忙碌/所选区间可用"（可选优化）

## 验证证据

- 定向测试：AssignmentCandidateServiceTest 45/45（+2：blacklist 常驻自动代入 RESIDENT_BLACKLISTED / 车辆候选 primaryDriverSeason 透传）；fleet verify 全绿（含 MySQL 集成测试）
- 网关验证（TEST）：G8888 车辆候选 `primaryDriverSeason=blacklist` + `vehicleStatus=busy` + `available=true`（区间无冲突）；司机候选 22 人含"巴特尔"=0（blacklist 正确排除）；selectedVehicle=G8888 → `suggestedDriverReason=RESIDENT_BLACKLISTED` + "常驻司机已拉黑，已回退自动代入空闲司机"