diff --git a/changelogs-v2/2026-07/27_5299_车务矩阵车辆司机预选与常驻标记-修改接口-管理后台.md b/changelogs-v2/2026-07/27_5299_车务矩阵车辆司机预选与常驻标记-修改接口-管理后台.md new file mode 100644 index 0000000..8e227d2 --- /dev/null +++ b/changelogs-v2/2026-07/27_5299_车务矩阵车辆司机预选与常驻标记-修改接口-管理后台.md @@ -0,0 +1,133 @@ +--- +schema: "hl-changelog/v2" +ticket: "5299" +title: "车务矩阵车辆司机预选与常驻标记" +consumer: "admin" +change_type: "修改接口" +backend_status: "deployed" +gateway_status: "verified" +frontend_status: "pending" +frontend_owner: "" +frontend_ref: "" +target_release: "" +verified_at: "2026-07-27T22:12:19+08:00" +status_note: "后端 PR #5300 已合并并部署测试环境,矩阵新增字段经真实网关验证;前端待认领预选、司机展示和 #5292 逐日表单改造" +updated_at: "2026-07-27" +base: "dev-v3" +--- + +# Fleet:矩阵车辆司机预选与常驻标记 + +> **服务**:`hl-fleet-service` +> **Issue**:#5299 +> **影响页面**:管理后台车务管理 → 矩阵派单 +> **兼容性**:仅新增响应字段,旧客户端可继续忽略 + +## 问题与目标 + +当前矩阵车辆行虽然已有常驻司机姓名,但缺少常驻司机稳定 ID;订单甘特条也没有直接返回该派车组的实际车辆、司机及常驻关系。页面因此无法稳定完成以下行为: + +- 从具体车辆上下文发起派单时自动带出车辆和可派常驻司机; +- 行头展示车辆常驻司机; +- 已排订单条块展示实际执行司机,并区分常驻/临时司机。 + +本次后端补齐稳定读契约。前端不得按姓名判断常驻关系,也不得复制相邻订单的临时司机作为新派单默认值。 + +## 变更接口 + +### `GET /admin/fleet/matrix/grid` + +`data.vehicles[]` 新增: + +| 字段 | 类型 | 空值规则 | 说明 | +|---|---|---|---| +| `primaryDriverId` | `String(Long)` | 无常驻司机为 `null` | 车辆主档的权威常驻司机 ID | + +既有 `primaryDriverName`、`primaryDriverPhone` 继续返回;手机号保持脱敏。三个字段共同用于行头展示,常驻判断以 ID 为准。 + +`data.vehicles[].assignments[]` 新增: + +| 字段 | 类型 | 空值规则 | 说明 | +|---|---|---|---| +| `vehicleId` | `String(Long)` | 未派为空 | 该甘特条对应派车组的实际车辆 ID | +| `vehiclePlate` | `String` | 未派为空 | 实际车牌 | +| `driverId` | `String(Long)` | 未派为空 | 该派车组实际司机 ID | +| `driverName` | `String` | 未派为空 | 该派车组实际司机姓名 | +| `residentMatch` | `Boolean` | 无实际司机为 `null` | `true`=实际司机是该车常驻司机;`false`=实际司机存在但不是该车常驻司机或车辆无常驻 | + +矩阵继续排除取消切片;同一派车组存在取消日缺口时按有效连续服务段拆成多个甘特条,不得把外包络日期当作司机持续占用。 + +## 前端必须调整 + +### 1. 从矩阵车辆上下文发起派单 + +1. 将所在行 `vehicles[].id` 直接作为当前选择车辆,并在候选请求中传 `selectedVehicleId`。 +2. 候选接口 `POST /admin/fleet/assignments/candidates` 会返回既有字段 `selectedVehicleResidentDriver`。 +3. 仅当该快照存在且 `available=true` 时,才把其司机 ID 作为默认司机。 +4. 无常驻司机、常驻司机冲突或不可派时,车辆仍保持预选,司机保持“待选择”,并展示候选返回的不可用原因。 +5. 不得取前后相邻订单的实际司机作为新订单默认司机。 + +### 2. 矩阵司机展示 + +- 车辆行头: + - `primaryDriverId != null`:展示 `primaryDriverName(常驻)`;可按需展示脱敏手机号。 + - `primaryDriverId == null`:展示“无常驻司机”,不要继续统一显示“待派司机”。 +- 已排订单条块:展示本条 `driverName`。 + - `residentMatch=true`:标记“常驻”。 + - `residentMatch=false`:标记“临时”。 + - `residentMatch=null`:显示“待派司机”。 + +不要从 `drivers` 页面列表或姓名/车牌文本反推常驻关系;使用本接口稳定 ID 与 `residentMatch`。 + +### 3. 同步完成 #5292 页面改造 + +用户截图仍出现“收取车费日期”,说明当前测试页面仍在使用旧构建或旧逻辑。新页面必须继续执行 #5292: + +- 删除“收取车费日期”及旧免费日期提交逻辑; +- 使用 `dailyVehiclePlan` 渲染“服务日期 × 稳定车辆槽位”; +- 保存时只提交 `dailyPlan`,不得同时提交旧 `items`、`chargeableServiceDates`、`vehicleFeeWaiverReason` 或 `confirmAllServiceDatesFree`。 + +## 响应示例 + +```json +{ + "id": "9007199254740993", + "plate": "蒙A-88888", + "primaryDriverId": "9007199254740994", + "primaryDriverName": "王师傅", + "primaryDriverPhone": "138****1234", + "assignments": [ + { + "id": "9007199254740995", + "assignmentGroupId": "9007199254740996", + "vehicleId": "9007199254740993", + "vehiclePlate": "蒙A-88888", + "driverId": "9007199254740994", + "driverName": "王师傅", + "residentMatch": true + } + ] +} +``` + +所有 Long ID 仍按 JSON 字符串处理,禁止转为 JS `Number`。 + +## 不影响范围 + +- 不修改派单状态机、车辆/司机占用、保险、对账或常驻关系写入。 +- 不自动选择不可派司机,不绕过候选接口与最终派单锁内校验。 +- 不修改 `hl-ui` 仓库;前端消费状态独立流转。 + +## 验证证据 + +- 后端 PR [wx/HL#5300](https://git.1814.love:8443/wx/HL/pulls/5300) 已 squash 合并至 `dev-v3`,合并提交 `fca8cedc6`。 +- `hl-fleet-service` 已滚动部署测试环境,8087/8187 双实例健康。 +- 定向矩阵测试:43 tests,0 failures,0 errors,0 skipped。 +- Fleet reactor verify:2456 tests,0 failures,0 errors,1 skipped;模块 Spotless、Jar、JaCoCo 成功。 +- 真实测试网关 `GET /admin/fleet/matrix/grid?year=2026&month=8&season=active`:HTTP/code 200;返回 19 辆车、38 个派车段,新增车辆/司机字段完整,Long ID 均为字符串,`residentMatch` 三态合法,常驻司机手机号全部脱敏,无业务写入。 +- 网关证据:`D:/work2/HL-v3/.tmp/5299-gateway.json`,SHA-256 `d94ee78fbe52cc193a28e5bf182e1353d2eca9d87824b1c2eb526c62a4fe645d`。 +- OpenAPI/oasdiff:项目尚未配置可复现 Swagger2→OAS3 与 oasdiff,状态为 `not_configured`;使用源码字段对比、Controller 序列化测试及真实网关响应作为人工回退证据,未冒充工具通过。 + +当前状态:后端已部署、网关已验证,前端消费保持 `pending`。 + +关联:#5299、#5292。