docs(fleet): expand candidate handoff (#5156)

2026-07-22 17:16:38 +08:00 · 2026-07-22 17:16:38 +08:00 · 033d60adc9
--- a/changelogs-v2/2026-07/85_5156_车务看板与矩阵主标识显示团号-前端待处理-管理后台.md
+++ b/changelogs-v2/2026-07/85_5156_车务看板与矩阵主标识显示团号-前端待处理-管理后台.md
@ -1,57 +1,33 @@
-# 【前端待处理·管理后台】#5156 车务看板与矩阵主标识显示团号
+# 【前端待处理·管理后台】#5156 车务团号、中文状态与常驻关系筛选

-> **服务**: `hl-fleet-service`  
-> **Issue**: [wx/HL#5156](https://git.1814.love:8443/wx/HL/issues/5156)  
-> **日期**: 2026-07-22  
-> **影响范围**: 管理后台车务派单看板、车务矩阵中的可见订单标识
+> **服务**: `hl-fleet-service`
+> **Issue**: [wx/HL#5156](https://git.1814.love:8443/wx/HL/issues/5156)
+> **日期**: 2026-07-22
+> **影响范围**: 管理后台车务派单看板、订单详情、车务矩阵、派单候选弹窗

 ---

 ## 关键结论

-后端现有看板与矩阵接口均已返回订单当前 `teamNo`，本次不新增或修改接口。管理后台需将截图标注的订单主标识改为团号，并将同类车务展示收口为一致规则：
+1. 看板与矩阵的可见订单主标识统一使用完整团号：

-```js
-const visibleOrderCode = teamNo?.trim() || orderNo?.trim() || '—'
-```
+   ```js
+   const visibleOrderCode = teamNo?.trim() || orderNo?.trim() || '—'
+   ```

- `teamNo` 有值：主要业务标识展示完整团号，不截取尾号。
- `teamNo` 为空：才回退展示 `orderNo`。
- 该规则只用于可见文案；不得用 `teamNo` 替换 `id`、`orderNumericId`、`assignmentId` 或 `assignmentGroupId`，不得改变行键、路由和派单接口入参。
+   该规则只替换可见文案，不得用 `teamNo` 替换 `id`、`orderNumericId`、`assignmentId` 或 `assignmentGroupId`，不得改变行键、路由和派单接口入参。

-## 前端处理范围
+2. 订单详情 `activeAssignments[]` 新增 `assignmentStatusLabel`。页面只展示中文标签，例如 `assignmentStatus=assigned` 对应 `assignmentStatusLabel=已派车`；`assignmentStatus` 继续用于程序判断，不直接显示英文状态码。

-### 1. 车务派单看板 `/fleet/board`
+3. 派单候选支持双向常驻关系展示和筛选：

- 列表卡片首行当前使用 `o.id`（适配层实际填入 `orderNo`）作为主标识，改为显示 `teamNo || orderNo`。
- 订单详情抽屉标题当前使用 `order.orderNo || order.id`，改为显示 `teamNo || orderNo`。
- 基本信息区保留明确的“团号”字段；如仍需诊断订单号，可作为次要字段保留，但不再作为抽屉标题和卡片主标识。
- 确认、拒接、取消等对话框中的可见订单标识同步使用上述规则，不得把 Long ID 或派单 ID 显示给车务人员。
+   - 车辆候选有常驻司机时，展示 `primaryDriverName` 和 `primaryDriverMaskedPhone`；`vehicleKeyword` 支持车牌、车型、常驻司机姓名或 11 位完整手机号。
+   - 司机候选有常驻车辆时，展示 `residentVehiclePlate`；`driverKeyword` 支持司机姓名、11 位完整手机号或常驻车牌。
+   - 完整手机号只作为精确筛选入参，响应仍只返回脱敏手机号。

-当前前端重点位置：
+## 接口契约

- `src/views/fleet/board/index.vue`
- `src/views/fleet/board/components/OrderRowList.vue`
- `src/views/fleet/board/components/OrderDrawer.vue`
-
-### 2. 车务矩阵 `/fleet/matrix`
-
- 矩阵数据适配层必须保留后端 `teamNo`，不能在 `adaptMatrixAssignment` 或页面二次适配时丢失。
- 订单甘特图左侧标识、占用条悬浮文案、未派订单池、单日订单清单中的主标识统一显示完整 `teamNo`。
- 移除 `String(o.id).slice(-4)` 这类内部 ID/订单号尾号展示；团号不截断。
- 点击、拖拽、派单和改派仍使用现有稳定 ID，只替换文字展示值。
-
-当前前端重点位置：
-
- `src/views/fleet/matrix/composables/useFleetMatrixData.js`
- `src/views/fleet/matrix/index.vue`
- `src/views/fleet/_shared/gantt/components/OrderGantt.vue`
- `src/views/fleet/_shared/gantt/components/OrderBar.vue`
- `src/views/fleet/_shared/gantt/components/VehicleGantt.vue`
- `src/views/fleet/_shared/gantt/components/UnassignedPool.vue`
- `src/views/fleet/matrix/components/DayListModal.vue`
-
-## 现有接口字段
+### 1. 看板、详情与矩阵团号

 | 页面场景 | 接口 | 团号字段 |
 | --- | --- | --- |
@ -61,31 +37,109 @@ const visibleOrderCode = teamNo?.trim() || orderNo?.trim() || '—'
 | 矩阵未派清单 | `GET /admin/fleet/matrix/unassigned-orders` | `data[].teamNo` |
 | 矩阵单日清单 | `GET /admin/fleet/matrix/day-orders` | `data[].teamNo` |

-示例：
+前端处理位置：
+
+- `src/views/fleet/board/index.vue`
+- `src/views/fleet/board/components/OrderRowList.vue`
+- `src/views/fleet/board/components/OrderDrawer.vue`
+- `src/views/fleet/matrix/composables/useFleetMatrixData.js`
+- `src/views/fleet/_shared/gantt/components/OrderGantt.vue`
+- `src/views/fleet/_shared/gantt/components/OrderBar.vue`
+- `src/views/fleet/_shared/gantt/components/UnassignedPool.vue`
+- `src/views/fleet/matrix/components/DayListModal.vue`
+
+### 2. 订单详情中文状态
+
+`GET /admin/fleet/board/orders/{orderId}` 的每个 `data.activeAssignments[]` 新增：
+
+| 字段 | 类型 | 说明 |
+| --- | --- | --- |
+| `assignmentStatus` | `string` | 稳定状态码，供逻辑判断 |
+| `assignmentStatusLabel` | `string` | 后端统一解析的中文状态标签，供页面展示 |

 ```json
 {
-  "orderNumericId": "2000000000000000101",
-  "orderNo": "HL20260708144557879",
-  "teamNo": "26-7218"
+  "assignmentStatus": "assigned",
+  "assignmentStatusLabel": "已派车"
 }
 ```

-前端可见主标识应为 `26-7218`；详情请求仍使用 `orderNumericId=2000000000000000101`。
+`OrderDrawer.vue` 中有效派车组右侧标签改为 `assignment.assignmentStatusLabel || '—'`，不要再以 `assignmentStatus` 作为可见兜底。
+
+### 3. 派单候选常驻关系
+
+接口：`POST /admin/fleet/assignments/candidates`
+
+请求关键词：
+
+| 字段 | 新口径 |
+| --- | --- |
+| `vehicleKeyword` | 车牌/车型包含匹配；常驻司机姓名包含匹配；常驻司机 11 位完整手机号精确匹配 |
+| `driverKeyword` | 司机姓名包含匹配；司机 11 位完整手机号精确匹配；常驻车牌包含匹配 |
+
+车辆候选 `data.vehicles.records[]`：
+
+| 字段 | 类型 | 说明 |
+| --- | --- | --- |
+| `primaryDriverId` | `string \| null` | 常驻司机 ID |
+| `primaryDriverName` | `string \| null` | 常驻司机姓名 |
+| `primaryDriverMaskedPhone` | `string \| null` | 常驻司机脱敏手机号 |
+
+司机候选 `data.drivers.records[]` 继续返回：
+
+| 字段 | 类型 | 说明 |
+| --- | --- | --- |
+| `residentVehicleId` | `string \| null` | 常驻车辆 ID |
+| `residentVehiclePlate` | `string \| null` | 常驻车牌 |
+
+前端处理要求：
+
+- `VehiclePickerList.vue`：有常驻司机时显示“常驻司机：姓名 脱敏手机号”，无常驻时显示“无常驻”；搜索提示改为“搜索车牌/车型/常驻司机姓名/完整手机号”。
+- `DriverPickerList.vue`：保留现有“常驻 {residentVehiclePlate}”展示；搜索提示改为“搜索姓名/完整手机号/常驻车牌”。
+- `useVehicleDriverPicker.js`：关键词变化后分别重置对应页码为 1，并将原值传给 `vehicleKeyword` / `driverKeyword`；不在前端对当前页二次过滤。
+- 所有雪花 ID 保持字符串处理。
+
+## 示例
+
+```json
+{
+  "vehicles": {
+    "records": [
+      {
+        "vehicleId": "2000000000000000101",
+        "plate": "蒙A77777",
+        "primaryDriverId": "2000000000000000201",
+        "primaryDriverName": "张师傅",
+        "primaryDriverMaskedPhone": "138****5678"
+      }
+    ]
+  },
+  "drivers": {
+    "records": [
+      {
+        "driverId": "2000000000000000201",
+        "name": "张师傅",
+        "maskedPhone": "138****5678",
+        "residentVehicleId": "2000000000000000101",
+        "residentVehiclePlate": "蒙A77777"
+      }
+    ]
+  }
+}
+```

 ## 验收清单

- [ ] 车务看板卡片主标识显示完整团号。
- [ ] 车务订单详情抽屉标题和基本信息区显示团号。
- [ ] 车务矩阵甘特图、占用条、未派池和单日清单显示完整团号，不再显示订单号尾 4 位。
- [ ] `teamNo` 为 `null`/空字符串时回退显示 `orderNo`，页面无 `undefined` 或空白标识。
- [ ] 有团号和无团号两类数据的详情、拖拽、派单、改派、取消操作均使用原稳定 ID，不串单。
- [ ] 相关前端单元测试覆盖“团号优先”与“空团号回退订单号”。
- [ ] 在测试环境以车务角色完成看板和矩阵截图验收。
+- [ ] 看板卡片、详情标题和矩阵各订单入口优先显示完整 `teamNo`，空值回退 `orderNo`。
+- [ ] 有效派车组状态只显示 `assignmentStatusLabel` 中文文案，不再出现 `assigned` 等英文状态码。
+- [ ] 有常驻司机的车辆显示姓名和脱敏手机号；可按姓名或完整手机号筛到对应车辆。
+- [ ] 有常驻车辆的司机显示常驻车牌；可按常驻车牌筛到对应司机。
+- [ ] 车牌/车型搜索和司机姓名/完整手机号搜索保持有效，关键词变化后分页正确重置。
+- [ ] 团号展示不改变详情、拖拽、派单、改派、取消等操作使用的稳定 ID。
+- [ ] 前端单元测试覆盖团号回退、中文状态、双向常驻关系显示与筛选参数。

 ## 后端核查证据

- `BoardOrderServiceTest` 已包含看板列表和当前订单上下文 `teamNo` 断言。
- `MatrixServiceTest` 已覆盖矩阵当前团号映射；2026-07-22 定向执行 35 个测试，0 失败、0 错误。
- 本次后端源码、数据库和接口契约无变更；不需要后端部署。
-
+- `BoardOrderServiceTest` 覆盖 `assigned -> 已派车`。
+- `AssignmentCandidateServiceTest` 覆盖车辆按常驻司机姓名/完整手机号筛选、司机按常驻车牌筛选及双向关系回显。
+- `DriverServiceTest` 覆盖指定常驻司机集合内的姓名/完整手机号查询，明文手机号不离开司机域。