docs(api): 修正派车大交通开放合同 (#5363)

2026-07-30 21:31:39 +08:00 · 2026-07-30 21:31:39 +08:00 · 9254671fbe
--- a/changelogs-v2/2026-07/30_5363_车务派车详情大交通契约补全-修改接口-管理后台.md
+++ b/changelogs-v2/2026-07/30_5363_车务派车详情大交通契约补全-修改接口-管理后台.md
@ -11,7 +11,7 @@ frontend_owner: ""
 frontend_ref: ""
 target_release: ""
 verified_at: ""
-status_note: "后端 PR #5365 已创建并等待 fresh review，尚未合并、部署或执行网关验证；本文件仅为前端消费 pending 草稿，不代表发布态。"
+status_note: "后端 PR #5365 正在处置 fresh review findings，尚未合并、部署或执行网关验证；前端跟踪 #5366 仍为 0/20，本文件仅为 pending 草稿。"
 updated_at: "2026-07-30"
 base: "dev-v3"
 ---
@ -22,7 +22,9 @@ base: "dev-v3"
 >
 > **PR**：[#5365](https://git.1814.love:8443/wx/HL/pulls/5365)（OPEN，未合并）
 >
-> **Issue**：[#5363](https://git.1814.love:8443/wx/HL/issues/5363)
+> **Backend Issue**：[#5363](https://git.1814.love:8443/wx/HL/issues/5363)
+>
+> **Frontend tracking**：[#5366](https://git.1814.love:8443/wx/HL/issues/5366)（OPEN，0/20；本草稿不代表前端验收完成）
 >
 > **日期**：2026-07-30
 >
@ -32,7 +34,7 @@ base: "dev-v3"

 | 接口 | 方法 | 路径 | 变更类型 |
 |---|---|---|---|
-| 查询车务派车订单详情 | `GET` | `/v3/admin/fleet/board/orders/{orderId}` | 响应字段 additive 新增 |
+| 查询车务派车订单详情 | `GET` | `/admin/fleet/board/orders/:orderId` | 响应字段 additive 新增 |

 接口路径、HTTP 方法、请求参数、错误码和既有响应字段均不变。

@ -46,7 +48,7 @@ base: "dev-v3"

 | 字段 | JSON 类型 | 可空 | 来源约束 | 说明 |
 |---|---|---|---|---|
-| `transportType` | `String` | 是 | order-v3 大交通计划原值 | 权威交通方式：`FLIGHT`、`TRAIN`、`SELF_DRIVE`；只有值为 `SELF_DRIVE` 才表示自驾 |
+| `transportType` | `String` | 是 | order-v3 大交通计划开放字符串原值 | 当前已知 `FLIGHT`、`TRAIN`、`SELF_DRIVE`、`BUS`、`OTHER`；未来未知非空值也原样透传；只有精确 `SELF_DRIVE` 表示自驾 |
 | `departStation` | `String` | 是 | order-v3 `departStation` 原值，源字段上限 100 字符 | 同一大交通计划的真实出发站；源未提供时为 `null` |
 | `arriveStation` | `String` | 是 | order-v3 `arriveStation` 原值，源字段上限 100 字符 | 同一大交通计划的真实到达站；源未提供时为 `null` |

@ -59,18 +61,26 @@ base: "dev-v3"
 - `direction=ARRIVAL`：`station = arriveStation`，它只代表已知到达端；
 - `direction=DEPARTURE`：`station = departStation`，它只代表已知出发端。

-滚动发布或旧 payload 只有 `station` 时，前端必须按方向放到已知的一端：
+路线展示只认两个新增端点：

- ARRIVAL：`待补充 → station`；
- DEPARTURE：`station → 待补充`。
+- 两端都有值：显示 `departStation → arriveStation`；
+- 只有到达端：显示 `未知 → arriveStation`；
+- 只有出发端：显示 `departStation → 未知`；
+- 两端都没有而只有 legacy `station`：仅显示独立字段 `旧数据站点（路线不完整）：station`，禁止箭头和完整路线语义。

-禁止把一个 `station` 同时复制到出发端和到达端，也禁止把单站点伪装成完整路线。新 `departStation` 或 `arriveStation` 任一为空时保持缺失，不得根据 `station`、方向、班次号、时间、备注或接送地点推断或补造。
+禁止把 `station` 放入或复制到任一真实端点。新 `departStation` 或 `arriveStation` 为空时保持缺失，不得根据 `station`、方向、班次号、时间、备注或接送地点推断或补造。

 ## 四、交通方式语义

- 仅 `transportType === "SELF_DRIVE"` 表示自驾。
- `transportNo` 或 `time` 为空不能用于推断自驾。
- `transportType` 为 `null` 时表示源数据未提供，前端不得自行归类。
+`transportType` 是 nullable/open `String`，不是 closed enum。当前可观测值与稳定文案为：
+
+- `FLIGHT`：飞机；
+- `TRAIN`：火车；
+- `SELF_DRIVE`：自驾；
+- `BUS`：大巴；
+- `OTHER`：其他。
+
+只有精确 `transportType === "SELF_DRIVE"` 表示自驾。`null` 显示“未提供”；未来未知非空值显示“未知交通方式”并 fail-closed，不得丢弃原值、归并为已知类型，也不得从 `transportNo`、`time`、站点或备注推断交通类型。

 ## 五、响应示例

@ -80,7 +90,9 @@ base: "dev-v3"
  "data": {
    "transport": {
      "arrive": {
+        "planId": "9007199254740993",
        "direction": "ARRIVAL",
+        "travelerIds": ["9007199254740995"],
        "transportType": "FLIGHT",
        "transportNo": "CA1234",
        "time": "2026-07-29T10:30:00",
@ -91,7 +103,9 @@ base: "dev-v3"
      "depart": null,
      "batches": [
        {
+          "planId": "9007199254740997",
          "direction": "DEPARTURE",
+          "travelerIds": ["9007199254740999"],
          "transportType": "TRAIN",
          "transportNo": "G5678",
          "time": "2026-07-31T17:20:00",
@ -108,26 +122,34 @@ base: "dev-v3"

 ## 六、前端消费动作

-1. 路线展示优先使用 `departStation → arriveStation`。
-2. 单端缺失时显示方向正确的部分路线和缺失端占位，不使用 `station` 补齐另一端。
-3. 仅按权威 `transportType=SELF_DRIVE` 进入自驾展示分支。
-4. 保留对仅含 legacy `station` 的滚动发布兼容。
+1. 路线只使用真实 `departStation` 与 `arriveStation`；单端缺失显示明确“未知”，legacy-only `station` 仅显示为独立“旧数据站点（路线不完整）”。
+2. 仅按权威 `transportType=SELF_DRIVE` 进入自驾展示；`BUS`/`OTHER` 使用稳定文案，`null` 与未知字符串按上节 fail-closed。
+3. `planId` 与 `travelerIds[]` 均为 JSON `String`，必须端到端保持字符串，禁止转为 JavaScript `Number`；精度安全用例使用示例中的超大 ID。
+4. 前端实现与具名 negative tests 以 [#5366](https://git.1814.love:8443/wx/HL/issues/5366) 为准；该单仍为 OPEN、0/20，当前 `frontend_status` 保持 `pending`。
 5. 领取后按标准状态流转回写 `frontend_owner`、`frontend_ref` 和 `frontend_status`。

+## 七、Shared Java / Internal Feign 影响
+
+面向前端的公开管理端契约是 `GET /admin/fleet/board/orders/:orderId`。order-v3 producer 与 Fleet consumer 之间另有内部契约 `GET /v3/internal/order/orders/:orderId/transport`，响应共享 Java DTO `OrderTransportForFleetDTO.TransportSegment/TransportBatch`。
+
+- `transportType`、`departStation`、`arriveStation` 都是 additive nullable/open `String`；旧 consumer 可忽略新增 JSON key，旧 producer 缺 key 时 Fleet 按 `null` 消费。
+- 滚动发布顺序应先保证 order-v3 producer 兼容，再由 Fleet consumer 使用；不允许把 oasdiff/SCC 的 `not_configured` 写成 PASS。
+- shared DTO 的非 board 消费者包括 assignment、H5 itinerary、通知快照/模板与 `OrderQueryFacade` 读路径；本次仅增加它们可忽略的字段，不改变其既有行为，也不授权它们推断路线或交通类型。
+
 ## 验证证据

- order producer/internal Controller 定向测试：38 tests，0 failure/error/skip。
- Fleet consumer/admin Controller 定向测试：63 tests，0 failure/error/skip。
+- order producer/internal Controller 定向测试：39 tests，0 failure/error/skip。
+- Fleet consumer/admin Controller 定向测试：64 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。
+- Fleet reactor verify：2555 tests，0 failure，0 error，1 skip。
+- order-v3 reactor verify：7031 tests，0 failure，0 error，31 skip。
 - oasdiff：`not_configured`；以字段级源码对比和 Controller JSON 测试作为 fallback。
 - Spring Cloud Contract：`not_configured`；以 producer/consumer 测试和两个 reactor verify 作为 fallback。
 - changelog 草稿门禁：仓库单元测试 46/46、文件名校验、path aliases 校验及 workflow `lint --allow-pending` 均通过。

 `--allow-pending` 只证明 pending 草稿结构合法，不是发布态 lint 证据。后端未合并/部署且网关未验证，因此本分支不创建指向 `main` 的 changelog PR；`backend_status` 与 `gateway_status` 保持 `pending`，`frontend_status` 保持 `pending`。

-## 八、不影响范围
+## 九、不影响范围

 - 无 DDL、无历史数据迁移。
 - 不改变派车状态机、候选/占用、费用、保险、Outbox 或消息模板。