diff --git a/changelogs-v2/2026-08/06_5618_precheck补黑名单司机校验与batchCreate校验项对齐-修改接口-管理后台.md b/changelogs-v2/2026-08/06_5618_precheck补黑名单司机校验与batchCreate校验项对齐-修改接口-管理后台.md new file mode 100644 index 0000000..b805b5a --- /dev/null +++ b/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 拦截兜底)。