docs: hand off fleet transport contract (#5363)

2026-07-30 19:47:32 +08:00 · 2026-07-30 19:47:32 +08:00 · d0a9d794cd
--- a/changelogs-v2/2026-07/30_5363_车务派车详情大交通契约补全-修改接口-管理后台.md
+++ b/changelogs-v2/2026-07/30_5363_车务派车详情大交通契约补全-修改接口-管理后台.md
@ -0,0 +1,134 @@
+---
+schema: "hl-changelog/v2"
+ticket: "5363"
+title: "车务派车详情大交通契约补全"
+consumer: "admin"
+change_type: "修改接口"
+backend_status: "pending"
+gateway_status: "pending"
+frontend_status: "pending"
+frontend_owner: ""
+frontend_ref: ""
+target_release: ""
+verified_at: ""
+status_note: "后端 PR #5365 已创建并等待 fresh review，尚未合并、部署或执行网关验证；本文件仅为前端消费 pending 草稿，不代表发布态。"
+updated_at: "2026-07-30"
+base: "dev-v3"
+---
+
+# 车务：派车详情大交通契约补全 (#5363)
+
+> **服务**：`hl-order-service-v3`、`hl-fleet-service`
+>
+> **PR**：[#5365](https://git.1814.love:8443/wx/HL/pulls/5365)（OPEN，未合并）
+>
+> **Issue**：[#5363](https://git.1814.love:8443/wx/HL/issues/5363)
+>
+> **日期**：2026-07-30
+>
+> **影响范围**：管理后台车务派车详情的大交通整团段与分批批次
+
+## 变更接口
+
+| 接口 | 方法 | 路径 | 变更类型 |
+|---|---|---|---|
+| 查询车务派车订单详情 | `GET` | `/v3/admin/fleet/board/orders/{orderId}` | 响应字段 additive 新增 |
+
+接口路径、HTTP 方法、请求参数、错误码和既有响应字段均不变。
+
+## 二、新增响应字段
+
+以下字段同时新增到：
+
+- `data.transport.arrive`
+- `data.transport.depart`
+- `data.transport.batches[]`
+
+| 字段 | JSON 类型 | 可空 | 来源约束 | 说明 |
+|---|---|---|---|---|
+| `transportType` | `String` | 是 | order-v3 大交通计划原值 | 权威交通方式：`FLIGHT`、`TRAIN`、`SELF_DRIVE`；只有值为 `SELF_DRIVE` 才表示自驾 |
+| `departStation` | `String` | 是 | order-v3 `departStation` 原值，源字段上限 100 字符 | 同一大交通计划的真实出发站；源未提供时为 `null` |
+| `arriveStation` | `String` | 是 | order-v3 `arriveStation` 原值，源字段上限 100 字符 | 同一大交通计划的真实到达站；源未提供时为 `null` |
+
+响应中的 `time` 仍为现有 date-time 字符串或 `null`，本次不改变时间口径。
+
+## 三、兼容与部分路线语义
+
+既有 `station` 保留且只作为方向相关的 legacy compatibility 字段：
+
+- `direction=ARRIVAL`：`station = arriveStation`，它只代表已知到达端；
+- `direction=DEPARTURE`：`station = departStation`，它只代表已知出发端。
+
+滚动发布或旧 payload 只有 `station` 时，前端必须按方向放到已知的一端：
+
+- ARRIVAL：`待补充 → station`；
+- DEPARTURE：`station → 待补充`。
+
+禁止把一个 `station` 同时复制到出发端和到达端，也禁止把单站点伪装成完整路线。新 `departStation` 或 `arriveStation` 任一为空时保持缺失，不得根据 `station`、方向、班次号、时间、备注或接送地点推断或补造。
+
+## 四、交通方式语义
+
+- 仅 `transportType === "SELF_DRIVE"` 表示自驾。
+- `transportNo` 或 `time` 为空不能用于推断自驾。
+- `transportType` 为 `null` 时表示源数据未提供，前端不得自行归类。
+
+## 五、响应示例
+
+```json
+{
+  "code": 200,
+  "data": {
+    "transport": {
+      "arrive": {
+        "direction": "ARRIVAL",
+        "transportType": "FLIGHT",
+        "transportNo": "CA1234",
+        "time": "2026-07-29T10:30:00",
+        "station": "海拉尔东山国际机场",
+        "departStation": "北京首都机场",
+        "arriveStation": "海拉尔东山国际机场"
+      },
+      "depart": null,
+      "batches": [
+        {
+          "direction": "DEPARTURE",
+          "transportType": "TRAIN",
+          "transportNo": "G5678",
+          "time": "2026-07-31T17:20:00",
+          "station": "海拉尔站",
+          "departStation": "海拉尔站",
+          "arriveStation": null
+        }
+      ]
+    }
+  },
+  "success": true
+}
+```
+
+## 六、前端消费动作
+
+1. 路线展示优先使用 `departStation → arriveStation`。
+2. 单端缺失时显示方向正确的部分路线和缺失端占位，不使用 `station` 补齐另一端。
+3. 仅按权威 `transportType=SELF_DRIVE` 进入自驾展示分支。
+4. 保留对仅含 legacy `station` 的滚动发布兼容。
+5. 领取后按标准状态流转回写 `frontend_owner`、`frontend_ref` 和 `frontend_status`。
+
+## 验证证据
+
+- order producer/internal Controller 定向测试：38 tests，0 failure/error/skip。
+- Fleet consumer/admin Controller 定向测试：63 tests，0 failure/error/skip。
+- Fleet Spotless：631 files clean。
+- Fleet reactor verify：2554 tests，0 failure，0 error，1 skip。
+- order-v3 reactor verify：7030 tests，0 failure，0 error，31 skip。
+- oasdiff：`not_configured`；以字段级源码对比和 Controller JSON 测试作为 fallback。
+- Spring Cloud Contract：`not_configured`；以 producer/consumer 测试和两个 reactor verify 作为 fallback。
+
+本草稿不声称后端已合并或部署，也不声称网关已验证；`backend_status` 与 `gateway_status` 保持 `pending`，`frontend_status` 保持 `pending`。
+
+## 八、不影响范围
+
+- 无 DDL、无历史数据迁移。
+- 不改变派车状态机、候选/占用、费用、保险、Outbox 或消息模板。
+- 不包含多司机通知/确认、整段资源应用或需求级原子确认。
+- 不代表 `hl-ui` 已实现、发布或完成页面验证。