docs: 交接 Fleet 矩阵车辆司机预选契约 (#5299) (#50)

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。