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

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

@@ -0,0 +1,63 @@
+---
+schema: "hl-changelog/v2"
+ticket: "5618"
+title: "precheck 补黑名单司机校验，与 batchCreate 校验项对齐"
+consumer: "admin"
+author: "wx"
+change_type: "修改接口"
+backend_status: "deployed"
+gateway_status: "verified"
+frontend_status: "pending"
+frontend_owner: "@wx"
+frontend_ref: "管理后台派单预览页可展示 driver_blacklisted / driver_season_not_registered warning 文案；不处理也不影响既有逻辑（batchCreate 605006/605013 兜底）"
+target_release: ""
+verified_at: "2026-08-06"
+status_note: "后端完成：PR #5625 合并 dev-v3（a1f64877ebcc38869a9cbe18d454aa84dc008f25）并部署 TEST；网关实测黑名单司机 precheck conflict=true + driver_blacklisted(605006) 提前提示，有效司机对照无黑名单提示。"
+updated_at: "2026-08-06"
+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 拦截兜底）。