docs: add fleet detail context changelog

2026-07-05 16:34:31 +08:00 · 2026-07-05 16:34:31 +08:00 · e11300080b
--- a/changelogs-v2/2026-07/23_4747_车务派单详情动态状态行程接送操作记录-修改接口-管理后台.md
+++ 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`。
+