hl-api-changelog/changelogs-v2/2026-07/31_5363_车务派车详情大交通契约补全-修改接口-管理后台.md

schema, ticket, title, consumer, change_type, backend_status, gateway_status, frontend_status, frontend_owner, frontend_ref, target_release, verified_at, status_note, updated_at, base

schema	ticket	title	consumer	change_type	backend_status	gateway_status	frontend_status	frontend_owner	frontend_ref	target_release	verified_at	status_note	updated_at	base
hl-changelog/v2	5363	车务派车详情大交通契约补全	admin	修改接口	pending	pending	implemented	Pi	v2.1@f4cac12fff3297fb42e6a217b1764b5408339133		2026-07-31	管理后台已补全大交通交通方式、真实双端路线与 legacy-only fail-closed 展示，checkpoint 通过并推送 f4cac12fff3297fb42e6a217b1764b5408339133；后端 PR #5365 虽已合并，但尚未部署或执行网关验证，因此 backend/gateway 继续保持 pending，前端不宣称页面联调 verified。	2026-08-01	dev-v3

车务：派车详情大交通契约补全 (#5363)

服务：hl-order-service-v3、hl-fleet-service

PR：#5365（已合并，merge e8e654a482）

Backend Issue：#5363

Frontend tracking：#5366（管理后台已实现静态契约与回归测试；后端未部署前不宣称页面联调完成）

日期：2026-07-30

影响范围：管理后台车务派车详情的大交通整团段与分批批次

变更接口

接口	方法	路径	变更类型
查询车务派车订单详情	GET	/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、BUS、OTHER；未来未知非空值也原样透传；只有精确 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，它只代表已知出发端。

路线展示只认两个新增端点：

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

禁止把 station 放入或复制到任一真实端点。新 departStation 或 arriveStation 为空时保持缺失，不得根据 station、方向、班次号、时间、备注或接送地点推断或补造。

四、交通方式语义

transportType 是 nullable/open String，不是 closed enum。当前可观测值与稳定文案为：

• FLIGHT：飞机；
• TRAIN：火车；
• SELF_DRIVE：自驾；
• BUS：大巴；
• OTHER：其他。

只有精确 transportType === "SELF_DRIVE" 表示自驾。null 显示“未提供”；未来未知非空值显示“未知交通方式”并 fail-closed，不得丢弃原值、归并为已知类型，也不得从 transportNo、time、站点或备注推断交通类型。

五、响应示例

{
  "code": 200,
  "data": {
    "transport": {
      "arrive": {
        "planId": "9007199254740993",
        "direction": "ARRIVAL",
        "travelerIds": ["9007199254740995"],
        "transportType": "FLIGHT",
        "transportNo": "CA1234",
        "time": "2026-07-29T10:30:00",
        "station": "海拉尔东山国际机场",
        "departStation": "北京首都机场",
        "arriveStation": "海拉尔东山国际机场"
      },
      "depart": null,
      "batches": [
        {
          "planId": "9007199254740997",
          "direction": "DEPARTURE",
          "travelerIds": ["9007199254740999"],
          "transportType": "TRAIN",
          "transportNo": "G5678",
          "time": "2026-07-31T17:20:00",
          "station": "海拉尔站",
          "departStation": "海拉尔站",
          "arriveStation": null
        }
      ]
    }
  },
  "success": true
}

六、前端消费动作

1. 路线只使用真实 departStation 与 arriveStation；单端缺失显示明确“未知”，legacy-only station 仅显示为独立“旧数据站点（路线不完整）”。
2. 仅按权威 transportType=SELF_DRIVE 进入自驾展示；BUS/OTHER 使用稳定文案，null 与未知字符串按上节 fail-closed。
3. planId 与 travelerIds[] 均为 JSON String，必须端到端保持字符串，禁止转为 JavaScript Number；精度安全用例使用示例中的超大 ID。
4. 前端已在 v2.1@f4cac12fff3297fb42e6a217b1764b5408339133 完成实现与具名 negative tests，frontend_status 为 implemented；后端未部署前不升级为页面联调 verified。
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 读路径；本次仅增加它们可忽略的字段，不改变其既有行为，也不授权它们推断路线或交通类型。

验证证据

• blocker focused：30 tests，0 failure/error，4 个无 Docker 条件 skip。
• order producer/internal Controller 定向测试：54 tests，0 failure/error/skip。
• Fleet consumer/admin Controller 定向测试：65 tests，0 failure/error/skip。
• Fleet Spotless：BUILD SUCCESS。
• Fleet reactor verify：2730 tests，0 failure，0 error，2 skips。
• order-v3 reactor verify：7210 tests，0 failure，0 error，35 skips。
• 最终证据索引：hl-5363-final-ac493-evidence-index.json，safe=true，7 files。
• 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 证据。后端已合并但未部署，网关亦未验证，因此 backend_status 与 gateway_status 保持 pending；前端仅以 checkpoint 与已推送业务提交收口为 implemented，不表述为已联调或 verified。

九、不影响范围

• 无 DDL、无历史数据迁移。
• 不改变派车状态机、候选/占用、费用、保险、Outbox 或消息模板。
• 不包含多司机通知/确认、整段资源应用或需求级原子确认。
• 不代表 hl-ui 已实现、发布或完成页面验证。