From 033d60adc9d5ae2ffc850ecdf1ecc878c02b8fd3 Mon Sep 17 00:00:00 2001 From: API Changelog Bot Date: Wed, 22 Jul 2026 17:16:38 +0800 Subject: [PATCH] docs(fleet): expand candidate handoff (#5156) --- ...板与矩阵主标识显示团号-前端待处理-管理后台.md | 168 ++++++++++++------ 1 file changed, 111 insertions(+), 57 deletions(-) diff --git a/changelogs-v2/2026-07/85_5156_车务看板与矩阵主标识显示团号-前端待处理-管理后台.md b/changelogs-v2/2026-07/85_5156_车务看板与矩阵主标识显示团号-前端待处理-管理后台.md index 474bea1..cfef3c8 100644 --- 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` 覆盖指定常驻司机集合内的姓名/完整手机号查询，明文手机号不离开司机域。