diff --git a/changelogs-v2/2026-07/23_5186_排车中订单恢复派车派人入口-修改接口-管理后台.md b/changelogs-v2/2026-07/23_5186_排车中订单恢复派车派人入口-修改接口-管理后台.md index 4fc511b..4ff7cc1 100644 --- a/changelogs-v2/2026-07/23_5186_排车中订单恢复派车派人入口-修改接口-管理后台.md +++ b/changelogs-v2/2026-07/23_5186_排车中订单恢复派车派人入口-修改接口-管理后台.md @@ -1,3 +1,15 @@ +--- +schema: "hl-changelog/v1" +ticket: "5186" +title: "排车中订单恢复派车派人入口并补齐改派上下文" +consumer: "admin" +backend: "verified" +gateway: "pending" +frontend: "pending" +base: "dev-v3" +generated: "2026-07-23T16:10:00+08:00" +--- + # Fleet:排车中订单恢复“派车派人”入口 > **服务**: hl-fleet-service @@ -11,13 +23,16 @@ 排车状态为 `holding` 或 `holding_urgent` 时,订单并非不可操作:后端现在返回 `canAssign=true`,并在 `availableActionCodes` 中下发 `CHANGE_ASSIGNMENT`,允许车务继续进入“派车派人”流程调整司机或车辆。 +2026-07-23 补充:改派候选查询需要用 `orderId + requirementId + fleetItemIndex` 精确定位当前订单的当前用车需求槽位。看板列表、详情顶层和详情内每个有效派车组现均稳定返回字符串形式的 `requirementId`,前端直接透传,不自行推导。 + ## 一、变更接口 | 接口 | 方法 | 路径 | 变更类型 | |------|------|------|----------| -| 派单看板列表 | GET | `/v3/admin/fleet/board/orders` | 响应字段取值扩展 | +| 派单看板列表 | GET | `/v3/admin/fleet/board/orders` | 响应字段取值扩展、新增字段 | +| 派单看板详情 | GET | `/v3/admin/fleet/board/orders/{orderId}` | 新增字段 | -请求参数、响应结构和写接口路径均未改变。 +请求参数和写接口路径均未改变。 ## 二、响应契约 @@ -35,23 +50,43 @@ 排车中进入流程属于调整当前有效派单,不是新增第二条有效派单;继续复用现有改派请求、基线差异提示、司机车辆档期冲突提示和刷新逻辑。 +### 改派候选上下文 + +| 响应位置 | 新增字段 | 类型 | 用途 | +|---|---|---|---| +| 列表 `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。 + ## 三、不影响范围 - `canRejectRequirement` 仍只在未派阶段可能为 `true`;排车中不得重新开放“驳回用车需求”。 - 已派车、已完成、已取消状态不会因本次变更开放派车入口。 -- 无数据库、Redis、MQ、请求字段或错误码变更。 +- 无数据库、Redis、MQ、候选请求字段或错误码变更。 ## 四、前端自测清单 - [ ] `holding` 订单显示“派车派人”按钮,点击后带出当前司机、车辆并进入调整流程。 - [ ] `holding_urgent` 同样可进入调整流程。 +- [ ] 打开排车步骤时,候选请求同时携带字符串 `orderId`、`requirementId` 和当前 `fleetItemIndex`,不再出现“改派候选查询必须携带当前订单ID、用车需求ID和车型项索引”。 - [ ] 提交时调用既有 `changeAssignment`,不调用创建派单接口。 - [ ] `assigned`、`completed`、`canceled` 不误显示入口。 - [ ] 调整成功后刷新看板,页面只保留一组当前有效派单。 ## 五、后端验证 -- 状态矩阵、生命周期动作及排车中改派保护已有定向测试覆盖。 +- 状态矩阵、生命周期动作、改派上下文及排车中改派保护已有定向测试覆盖。 - `mvn -f hl-fleet-service/pom.xml spotless:check` 通过。 - `mvn -pl hl-fleet-service -am verify` 通过。