From 1042d7ad62b6b787b95ee18fa1c455023c9b4226 Mon Sep 17 00:00:00 2001 From: API Changelog Bot Date: Fri, 7 Aug 2026 12:05:55 +0800 Subject: [PATCH] =?UTF-8?q?docs(changelog):=20precheck=E5=AF=B9=E4=B8=8D?= =?UTF-8?q?=E5=AD=98=E5=9C=A8=E8=BD=A6=E8=BE=86/=E5=8F=B8=E6=9C=BA?= =?UTF-8?q?=E8=BF=94=E5=9B=9E=E6=98=8E=E7=A1=AEconflict=E5=8E=9F=E5=9B=A0?= =?UTF-8?q?=EF=BC=88#5629=EF=BC=89?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- ...司机返回明确conflict原因-修改接口-管理后台.md | 65 +++++++++++++++++++ 1 file changed, 65 insertions(+) create mode 100644 changelogs-v2/2026-08/07_5629_precheck不存在车辆司机返回明确conflict原因-修改接口-管理后台.md diff --git a/changelogs-v2/2026-08/07_5629_precheck不存在车辆司机返回明确conflict原因-修改接口-管理后台.md b/changelogs-v2/2026-08/07_5629_precheck不存在车辆司机返回明确conflict原因-修改接口-管理后台.md new file mode 100644 index 0000000..f5ebf19 --- /dev/null +++ b/changelogs-v2/2026-08/07_5629_precheck不存在车辆司机返回明确conflict原因-修改接口-管理后台.md @@ -0,0 +1,65 @@ +--- +schema: "hl-changelog/v2" +ticket: "5629" +title: "precheck 对不存在车辆/司机返回明确 conflict 原因" +consumer: "admin" +author: "wx" +change_type: "修改接口" +backend_status: "deployed" +gateway_status: "verified" +frontend_status: "pending" +frontend_owner: "" +frontend_ref: "" +target_release: "" +verified_at: "" +status_note: "后端完成：PR #5637 合并 dev-v3（d621d25471a1c75652e19bd4c471bb61fb0dea95）并部署 TEST；网关实测不存在车/司机 precheck conflict=true 且 conflicts 含 vehicle_not_found(车辆不存在)/driver_not_found(司机不存在)，有效资源对照 conflicts 为空不误报。" +updated_at: "2026-08-07" +base: "dev-v3" +generated: "2026-08-07T12:10:00+08:00" +--- + +# precheck 对不存在车辆/司机返回明确 conflict 原因（#5629） + +## 背景 + +E2E 实测：`POST /admin/fleet/assignments/precheck` 对**不存在的车辆/司机**（如 vehicleId/driverId=999999999999999999）返回 `code=200, conflict=true`，但 **`conflicts=[]` 为空**——原因只埋在 `warnings`（`vehicle_unavailable`/`driver_unavailable`，msg=「车辆不存在或已删除」/「司机不存在或已删除」），车务预览在冲突明细区看不到"车辆不存在/司机不存在"的明确提示。 + +## 变更内容 + +`POST /admin/fleet/assignments/precheck` 响应 `conflicts` 新增两种类型（资源不存在时置 `conflict=true` 阻断，与既有 `resourceUnavailable` 行为一致，仅把原因从仅 warnings 补进 conflicts）： + +| conflict.type | 触发条件 | msg 文案 | +|---|---|---| +| `vehicle_not_found` | 车辆不存在（`vehicle==null`） | 车辆不存在 | +| `driver_not_found` | 司机不存在（`driver==null`） | 司机不存在 | + +补充说明： + +- `conflicts[].msg` 字段此前对重叠冲突（`vehicle`/`driver`）留空由前端结构化自渲染，本次对不存在类冲突填入明确文案；`PrecheckResult.ConflictItem` BO 新增 `msg` 字段并由 converter 透传。 +- 车辆/司机**存在但不可用**（维保/停用、休假/待激活）仍只进 `warnings`（`vehicle_unavailable`/`driver_unavailable`），不新增 conflicts 项，行为不变。 +- `warnings` 中 `vehicle_unavailable`/`driver_unavailable`（含"不存在或已删除"文案）保留，向后兼容。 +- precheck 仍为只读接口，不抛异常、不写库、不取锁。 + +## 关联 / 联系人 + +- 工单：https://git.1814.love:8443/wx/HL/issues/5629 +- PR：https://git.1814.love:8443/wx/HL/pulls/5637 +- 后端：wx + +## 变更接口或验证证据 + +### 接口契约 + +- 接口路径/方法/请求体：不变。 +- 响应 `data.conflicts[].type` 新增枚举值：`vehicle_not_found`、`driver_not_found`；此两种类型 `conflictAssignmentId/conflictOrderNo/conflictDateRange` 为空，`msg` 为明确原因文案。 + +### 验证证据 + +- 定向测试：`AssignmentServiceTest#precheck_notFoundResources_returnsExplicitConflictReason`（不存在车/司机 → conflicts 含两 not_found 类型+msg）、`AssignmentConverterTest#toPrecheckRespVO_notFoundConflictMsgPassthrough`（msg 透传）。 +- 全量 `mvn -pl hl-fleet-service -am verify`：3242 项 0 失败 4 skipped（含 MySQL 集成）；spotless:check 通过。 +- 部署 TEST 成功（hl-fleet-service, dev-v3, d621d254）。 +- 网关验证 10/10 PASS：不存在车+不存在司机 → conflict=true + vehicle_not_found(车辆不存在)+driver_not_found(司机不存在)；有效车+不存在司机 → 仅 driver_not_found；不存在车+存在司机 → 仅 vehicle_not_found；有效车+存在司机对照 → conflicts=[] 不误报。 + +## 前端/调用方动作 + +- 管理后台派单预览页冲突明细区可直接展示 `vehicle_not_found`/`driver_not_found` 的 `msg` 文案（车辆不存在/司机不存在）；不处理也不影响既有逻辑（`conflict=true` 仍会阻断，warnings 仍含 unavailable 提示兜底）。