117 行
7.1 KiB
Markdown
117 行
7.1 KiB
Markdown
---
|
||
schema: "hl-changelog/v1"
|
||
ticket: "5186"
|
||
title: "排车中订单恢复派车派人入口并补齐改派上下文"
|
||
consumer: "admin"
|
||
backend: "verified"
|
||
gateway: "verified"
|
||
frontend: "pending"
|
||
base: "dev-v3"
|
||
generated: "2026-07-23T16:10:00+08:00"
|
||
---
|
||
|
||
# Fleet：排车中订单恢复“派车派人”入口
|
||
|
||
> **服务**: hl-fleet-service
|
||
> **Issue**: #5186
|
||
> **日期**: 2026-07-23
|
||
> **影响范围**: 管理后台车务派单看板及订单派车流程
|
||
|
||
---
|
||
|
||
## ⚠️ 关键变化
|
||
|
||
排车状态为 `holding` 或 `holding_urgent` 时，订单并非不可操作：后端现在返回 `canAssign=true`，并在 `availableActionCodes` 中下发 `CHANGE_ASSIGNMENT`，允许车务继续进入“派车派人”流程调整司机或车辆。
|
||
|
||
2026-07-23 契约修订：改派候选查询需要用 `orderId + requirementId + fleetItemIndex` 精确定位当前订单的当前用车需求槽位。看板列表、详情顶层和详情内每个有效派车组现均稳定返回字符串形式的 `requirementId`，前端直接透传，不自行推导。
|
||
|
||
## 变更接口
|
||
|
||
| 接口 | 方法 | 路径 | 变更类型 |
|
||
|------|------|------|----------|
|
||
| 派单看板列表 | GET | `/admin/fleet/board/orders` | 响应字段取值扩展、新增字段 |
|
||
| 派单看板详情 | GET | `/admin/fleet/board/orders/:orderId` | 新增字段 |
|
||
|
||
请求参数和写接口路径均未改变。
|
||
|
||
## 二、响应契约
|
||
|
||
`records[]` 中以下字段按服务端返回值处理：
|
||
|
||
| `assignmentStatus` | `canAssign` | `availableActionCodes` | 前端行为 |
|
||
|---|---:|---|---|
|
||
| `unassigned` | `true` | 包含 `ASSIGN` | 展示“派车派人”，提交既有创建派单接口 |
|
||
| `unassigned_urgent` | `true` | 包含 `ASSIGN` | 展示“派车派人”，提交既有创建派单接口 |
|
||
| `holding` | `true` | 包含 `CHANGE_ASSIGNMENT` | 展示“改派”，提交既有 `changeAssignment` 改派接口 |
|
||
| `holding_urgent` | `true` | 包含 `CHANGE_ASSIGNMENT` | 展示“改派”，提交既有 `changeAssignment` 改派接口 |
|
||
| `assigned` / `completed` / `canceled` | `false` | 不包含上述可派动作 | 不展示入口 |
|
||
|
||
前端不要再用 `assignmentStatus === 'unassigned'` 自行推断入口，也不要因为订单已有司机或车辆就隐藏按钮。入口以 `canAssign === true` 为第一判断，具体提交模式以 `availableActionCodes` 为准。
|
||
|
||
排车中进入流程属于调整当前有效派单，不是新增第二条有效派单；继续复用现有改派请求、基线差异提示、司机车辆档期冲突提示和刷新逻辑。
|
||
|
||
### 改派候选上下文
|
||
|
||
| 响应位置 | 新增字段 | 类型 | 用途 |
|
||
|---|---|---|---|
|
||
| 列表 `data.records[]` | `requirementId` | `string` | 当前卡片所属用车需求 ID |
|
||
| 详情 `data` | `requirementId` | `string` | 当前有效用车需求 ID |
|
||
| 详情 `data.currentAssignment` | `requirementId` | `string` | 当前派车组所属用车需求 ID |
|
||
| 详情 `data.activeAssignments[]` | `requirementId` | `string` | 每个有效派车组所属用车需求 ID |
|
||
|
||
进入改派候选查询时：
|
||
|
||
- `orderId` 取列表返回的数字订单 ID；
|
||
- `requirementId` 优先取详情顶层同名字段，按具体派车组操作时可取该组的同名字段；
|
||
- `fleetItemIndex` 取当前卡片或当前派车组字段；
|
||
- 三者必须原样透传给候选接口，不得使用团号、订单号或数组位置替代；
|
||
- `orderId`、`requirementId` 均按字符串处理，避免 JavaScript 大整数精度丢失。
|
||
|
||
当前 `v2.1` 候选请求组装已经读取 `order.requirementId`；后端部署后，从列表进入并合并详情时会获得该字段，无需前端猜测需求 ID。
|
||
|
||
### 排车中入口与向导状态
|
||
|
||
测试环境现状仍有一处前端状态错位：看板卡片已经显示“排车中”，点击“派车派人”后虽然按 `CHANGE_ASSIGNMENT` 进入 `reassign` 模式，但 `resolveAssignFlowRestoreState(order, mode)` 对所有非 `confirmHold` 模式固定返回 `step: 1`，导致向导错误高亮“订单详情”，底部也显示“下一步 · 排车”。
|
||
|
||
前端需要统一按后端状态和动作码恢复入口语义：
|
||
|
||
- `assignmentStatus=holding/holding_urgent` 且动作码包含 `CHANGE_ASSIGNMENT` 时，卡片按钮文案显示“改派”，不要继续显示“派车派人”；
|
||
- 从该入口打开时保持 `mode=reassign`，向导直接进入第 2 步“排车”，第 1 步“订单详情”显示已完成；
|
||
- 第 2 步带出当前司机、车辆，允许只更换其中一项；提交继续调用既有 `changeAssignment`，不得新增第二条有效派单；
|
||
- “司机已确认/查看待确认”入口仍使用 `confirmHold` 并恢复第 3 或第 4 步，不能被本次改派逻辑影响；
|
||
- 首次待派车订单仍从第 1 步开始，按钮仍为“派车派人”。
|
||
|
||
以上仅是前端状态机和展示文案调整，后端不新增接口或字段。
|
||
|
||
## 三、不影响范围
|
||
|
||
- `canRejectRequirement` 仍只在未派阶段可能为 `true`；排车中不得重新开放“驳回用车需求”。
|
||
- 已派车、已完成、已取消状态不会因本次变更开放派车入口。
|
||
- 无数据库、Redis、MQ、候选请求字段或错误码变更。
|
||
|
||
## 四、前端自测清单
|
||
|
||
- [ ] `holding` 订单显示“改派”按钮，点击后带出当前司机、车辆并进入调整流程。
|
||
- [ ] `holding_urgent` 同样显示“改派”并进入调整流程。
|
||
- [ ] `holding/holding_urgent + CHANGE_ASSIGNMENT` 卡片按钮显示“改派”，打开后直接高亮第 2 步“排车”，第 1 步为已完成。
|
||
- [ ] 首次待派车仍从第 1 步开始；`confirmHold` 仍恢复第 3/4 步，三种入口互不串态。
|
||
- [ ] 打开排车步骤时，候选请求同时携带字符串 `orderId`、`requirementId` 和当前 `fleetItemIndex`，不再出现“改派候选查询必须携带当前订单ID、用车需求ID和车型项索引”。
|
||
- [ ] 提交时调用既有 `changeAssignment`，不调用创建派单接口。
|
||
- [ ] `assigned`、`completed`、`canceled` 不误显示入口。
|
||
- [ ] 调整成功后刷新看板，页面只保留一组当前有效派单。
|
||
|
||
## 验证证据
|
||
|
||
- 后端提交：`aaeb01242`；PR：[wx/HL#5190](https://git.1814.love:8443/wx/HL/pulls/5190)，已合并 `dev-v3`。
|
||
- 状态矩阵、生命周期动作、改派上下文及排车中改派保护已有定向测试覆盖；`BoardOrderServiceTest` 与 `BoardControllerTest` 共 49 项通过。
|
||
- `mvn -f hl-fleet-service/pom.xml spotless:check` 通过。
|
||
- `mvn -pl hl-fleet-service -am verify` 通过。
|
||
- 测试环境 Fleet 滚动部署任务 `3458b3ab` 成功，8087、8187 两实例健康。
|
||
- 网关按团号 `26-7042` 验证：列表与详情 HTTP/code 200，`requirementId` 在列表、详情顶层、`currentAssignment` 和 `activeAssignments[]` 均存在；携带 `orderId + requirementId + fleetItemIndex + excludeAssignmentId` 调用候选接口 HTTP/code 200，返回 19 辆车、19 名司机候选。
|
||
- 当前前端 `v2.1` 已从 `order.requirementId` 组装候选请求；但截至 `v2.1@6e6a11bf`，`resolveAssignFlowRestoreState` 对 `reassign` 仍固定恢复第 1 步，且排车中入口文案仍为“派车派人”，需要按上方状态规则调整。
|
||
|
||
## 六、相关文档
|
||
|
||
- [wx/HL#5186](https://git.1814.love:8443/wx/HL/issues/5186)
|
||
|