docs(changelog): precheck对不存在车辆/司机返回明确conflict原因（#5629）

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 提示兜底）。