diff --git a/changelogs-v2/2026-07/23_4747_车务派单详情动态状态行程接送操作记录-修改接口-管理后台.md b/changelogs-v2/2026-07/23_4747_车务派单详情动态状态行程接送操作记录-修改接口-管理后台.md new file mode 100644 index 0000000..bc9e198 --- /dev/null +++ b/changelogs-v2/2026-07/23_4747_车务派单详情动态状态行程接送操作记录-修改接口-管理后台.md @@ -0,0 +1,187 @@ +# 【修改接口·管理后台】车务派单详情新增动态状态、接送与详细操作记录 + +> **Issue**: [wx/HL#4747](https://git.1814.love:8443/wx/HL/issues/4747) +> **服务**: hl-fleet-service + hl-order-service-v3 +> **日期**: 2026-07-05 +> **影响范围**: 管理后台车务管理 / 派单看板 / 派单详情弹窗 + +--- + +## 1. 关键变化 + +- 派单详情接口 `GET /admin/fleet/board/orders/{orderId}` 新增: + - `transport`:订单大交通接/送信息,接和送都返回。 + - `progressSteps`:后端按派单状态动态返回步骤状态,前端不要再写死。 + - `operationLog`:详细操作记录,口径对齐房务操作记录。 +- `itinerary.days[]` 明确只取订单行程表 `order_itinerary_day`。前端不要从产品快照或产品模板取派单详情行程。 +- 订单行程天标题/简介为空时,后端会用同一天 `order_itinerary_node` 节点叙事兜底;有 `order_itinerary_day.day_title/description` 时,节点数据不会覆盖订单行程天。 + +--- + +## 2. 变更接口 + +```http +GET /admin/fleet/board/orders/{orderId} +``` + +响应 VO:`BoardOrderDetailVO` + +### 2.1 新增字段 `transport` + +```json +{ + "transport": { + "arrive": { + "transportNo": "CA1234", + "time": "2026-05-13T14:30:00", + "station": "海拉尔机场", + "remark": "T3 举牌接机" + }, + "depart": { + "transportNo": "CA5678", + "time": "2026-05-18T17:00:00", + "station": "海拉尔机场", + "remark": null + }, + "batches": [], + "pickupRequired": true + } +} +``` + +字段说明: + +| 字段 | 类型 | 说明 | +|------|------|------| +| `transport.arrive` | object/null | 到达接团段,来源大交通到达方向 | +| `transport.depart` | object/null | 返程送站段,来源大交通离开方向 | +| `transport.batches` | array | 分批到达/返程的批次 | +| `transport.pickupRequired` | boolean/null | 是否需要平台派车接送;无大交通时为 null | + +> 前端展示接送时同时读取 `arrive` 和 `depart`,不要只显示接机。 + +### 2.2 新增字段 `progressSteps` + +```json +{ + "progressSteps": [ + { "step": 1, "code": "ORDER_DETAIL", "label": "订单详情", "status": "DONE", "statusLabel": "已完成", "active": false, "time": "2026-07-05T12:00:00" }, + { "step": 2, "code": "DISPATCH", "label": "排车", "status": "DONE", "statusLabel": "已完成", "active": false, "time": "2026-07-05T13:00:00" }, + { "step": 3, "code": "DRIVER_CONFIRM", "label": "待确认", "status": "PROCESSING", "statusLabel": "进行中", "active": true, "time": "2026-07-05T13:00:00" }, + { "step": 4, "code": "CONFIRM_EXECUTE", "label": "确认执行", "status": "WAITING", "statusLabel": "待处理", "active": false, "time": null } + ] +} +``` + +`status` 枚举: + +| 值 | 说明 | +|----|------| +| `DONE` | 已完成 | +| `PROCESSING` | 当前进行中 | +| `WAITING` | 待处理 | +| `CANCELED` | 已取消 | + +> 前端按后端返回渲染步骤,不再根据旧静态流程自行推断。 + +### 2.3 新增字段 `operationLog` + +```json +{ + "operationLog": { + "total": 2, + "summary": { "totalCount": 2 }, + "records": [ + { + "time": "2026-07-05T13:00:00", + "opType": "HOLD_SENT", + "opTypeLabel": "发起排车", + "summary": "发起排车,蒙A-100,王师傅,排车锁定", + "operator": { "userId": "10001", "name": "车务" }, + "detail": { + "assignmentId": "1", + "orderId": "10", + "requirementId": "900", + "requiredVehicleType": "商务车", + "requiredSeats": 7, + "vehiclePlate": "蒙A-100", + "driverName": "王师傅", + "tripRange": "2026-05-06 至 2026-05-11", + "note": "排车锁定,蒙A-100,王师傅" + } + } + ] + } +} +``` + +`opType` 当前可能值: + +| 值 | 说明 | +|----|------| +| `REQUIREMENT_RECEIVED` | 收到用车需求 | +| `HOLD_SENT` | 发起排车 | +| `DRIVER_CONFIRMED` | 司机确认 | +| `CONFIRMED` | 确认执行 | +| `CANCELED` | 取消派单 | +| `COMPLETED` | 完结派单 | + +--- + +## 3. 行程数据源要求 + +派单详情页左侧“每日安排”必须读取本接口返回的: + +```json +{ + "itinerary": { + "days": [ + { "title": "抵达呼和浩特", "detail": "专车机场/高铁站接站..." } + ] + } +} +``` + +后端数据源: + +1. 优先 `order_itinerary_day.day_title` +2. 优先 `order_itinerary_day.description` +3. 若标题/简介为空,再用同一天 `order_itinerary_node` 的节点名/描述兜底 + +禁止前端从产品快照、产品模板或产品详情接口拿这块数据。订单行程会被调整,产品快照不是派单详情页的事实源。 + +--- + +## 4. 内部接口说明(前端无需调用) + +后端新增 order-v3 内部 Feign: + +```http +GET /v3/internal/order/orders/{orderId}/fleet-detail-context +``` + +用于 fleet 服务一次拉取订单摘要、`order_itinerary_day` 行程和大交通接送。该接口不对管理后台前端开放,前端仍只调用 `GET /admin/fleet/board/orders/{orderId}`。 + +--- + +## 5. 验收标准 + +| 场景 | 期望 | +|------|------| +| 派单详情弹窗打开 | 步骤条按 `progressSteps` 后端返回渲染 | +| 有到达和返程大交通 | `transport.arrive` 与 `transport.depart` 都能展示 | +| 分批接送 | 读取 `transport.batches[]` | +| 每日安排 | 使用 `itinerary.days[]`,不得读产品快照 | +| `order_itinerary_day` 有标题/简介 | 按订单行程天展示,不被节点或产品数据覆盖 | +| 操作记录展开 | 使用 `operationLog.records[]` 展示详细记录 | + +--- + +## 6. 验证状态 + +- 后端编译已通过。 +- 已补单测覆盖: + - `ItineraryServiceTest`: `listDaysForFleet` 优先 `order_itinerary_day`,空值才节点兜底。 + - `OrderFleetProviderServiceTest`: 聚合上下文返回订单详情、行程和接送。 + - `BoardOrderServiceTest`: 派单详情返回 `transport/progressSteps/operationLog`。 +