---
schema: "hl-changelog/v2"
ticket: "5618"
title: "precheck 补黑名单司机校验，与 batchCreate 校验项对齐"
consumer: "admin"
author: "wx"
change_type: "修改接口"
backend_status: "deployed"
gateway_status: "verified"
frontend_status: "not_required"
frontend_owner: ""
frontend_ref: ""
target_release: ""
verified_at: ""
status_note: "后端完成：PR #5625 合并 dev-v3（a1f64877ebcc38869a9cbe18d454aa84dc008f25）并部署 TEST；网关实测黑名单司机 precheck conflict=true + driver_blacklisted(605006) 提前提示，有效司机对照无黑名单提示。"
updated_at: "2026-08-07"
base: "dev-v3"
generated: "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` 形式提前阻断提示。
- 非黑名单正常路径行为不变（证件到期等仍为不阻断强提醒）。

## 关联 / 联系人

- 工单：https://git.1814.love:8443/wx/HL/issues/5618
- PR：https://git.1814.love:8443/wx/HL/pulls/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 拦截兜底）。
