---
schema: "hl-changelog/v2"
ticket: "5629"
title: "precheck 对不存在车辆/司机返回明确 conflict 原因"
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 #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 提示兜底）。
