changelog-filename-gate / validate (push) Successful in 2s

详情

修改原因：拉黑常驻司机状态与回退建议已完成前端消费。

修改内容：回写 implemented 和业务提交引用。

实际验证：pnpm checkpoint 定向验证通过。

Changelog：#5574 source 文档。

2026-08-06 10:05:31 +08:00

4.5 KiB

原始文件 Blame 文件历史

schema, ticket, title, consumer, author, change_type, backend_status, gateway_status, frontend_status, frontend_owner, frontend_ref, target_release, verified_at, status_note, updated_at, base, generated

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

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

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

关联 / 联系人

链接

Issue: #5574
PR: #5582
Merge commit: 83dd24d1b

联系人

后端负责人: @wx

背景

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

巴特尔（2065272153565020161）season=blacklist（06-15 拉黑 reason=4444）——司机候选 SQL 按 season=ACTIVE 过滤，黑名单司机不进候选是业务正确语义（#5139 契约：黑名单仍按现有业务守卫阻断）；另一同名 active 巴特尔已软删（06-12）
蒙A-G8888 vehicle_status=busy（今日起 08-14~~26 有 9 条在途 assigned 派单，正确）但候选区间 08-28~~31 无冲突显示"所选服务日期内可用"（也正确）——两者口径不同但不矛盾，候选 VO 已透传 vehicleStatus 供前端展示
测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 语义不变（档期冲突/休整/待激活/停用）。

前端/调用方动作

车辆候选行可按 primaryDriverSeason === "blacklist" 显示"常驻司机已拉黑"标注（可选优化）
自动代入提示按 suggestedDriverReason 展示后端 message（RESIDENT_BLACKLISTED 已有明确文案）
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 + "常驻司机已拉黑，已回退自动代入空闲司机"

4.5 KiB 原始文件 Blame 文件历史 Unescape Escape