# 【修改接口·管理后台】车务派单详情新增动态状态、接送与详细操作记录

> **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`。

