hl-api-changelog/changelogs-v2/2026-08/06_5618_precheck补黑名单司机校验与batchCreate校验项对齐-修改接口-管理后台.md

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	5618	precheck 补黑名单司机校验，与 batchCreate 校验项对齐	admin	wx	修改接口	deployed	verified	not_required					后端完成：PR #5625 合并 dev-v3（a1f64877ebcc38869a9cbe18d454aa84dc008f25）并部署 TEST；网关实测黑名单司机 precheck conflict=true + driver_blacklisted(605006) 提前提示，有效司机对照无黑名单提示。	2026-08-07	dev-v3	2026-08-06T22:45:00+08:00

precheck 补黑名单司机校验（#5618）

背景

E2E 实测：黑名单司机（blacklisted_at 已写）POST /admin/fleet/assignments/precheck 返回 conflict=false 不拦；POST /admin/fleet/assignments/batch 抛 605006 拦截。precheck 缺司机赛季校验，车务在候选/预览阶段看不到黑名单拦截提示，提交时才被拦，前后体验不一致。

变更内容

POST /admin/fleet/assignments/precheck 响应 warnings 新增两种类型（均置 conflict=true 阻断，与 batchCreate 锁内 assertDriverSeasonAssignable 对齐）：

warning.type	触发条件	文案	对齐错误码
driver_blacklisted	司机 season=blacklist	司机已黑名单（605006），提交派单将被拦截	605006
driver_season_not_registered	司机 season=archived/pending 等非 active	司机非在册赛季（605013），提交派单将被拦截	605013

补充说明：

• precheck 仍为只读接口，不抛异常、不写库、不取锁；黑名单以 warning + conflict=true 形式提前阻断提示。
• 非黑名单正常路径行为不变（证件到期等仍为不阻断强提醒）。

关联 / 联系人

• 工单：wx/HL#5618
• PR：wx/HL#5625
• 后端：wx

变更接口或验证证据

接口契约

• 接口路径/方法/请求体：不变。
• 响应 data.warnings[].type 新增枚举值：driver_blacklisted、driver_season_not_registered（前端提示文案随 msg 透传）。

验证证据

• 定向测试：AssignmentServiceTest 382/382（新增 2 例：黑名单阻断提示 605006、非在册阻断提示 605013）。
• 全量 mvn -pl hl-fleet-service -am verify：3231 项 0 失败 4 skipped（含 MySQL 集成）；spotless 通过。
• 部署 TEST 成功（hl-fleet-service, dev-v3, a1f64877）。
• 网关验证 7/7 PASS：巴特尔（season=blacklist）+ 蒙A-E2E01 → conflict=true + driver_blacklisted（605006 文案）；有效司机对照 → 无黑名单/非在册提示、conflict=false。

前端/调用方动作

• 管理后台派单预览页可展示 driver_blacklisted / driver_season_not_registered warning 文案（提前告知车务黑名单拦截原因）；不处理也不影响既有逻辑（提交时 batchCreate 仍按 605006/605013 拦截兜底）。