API Changelog Bot d0a9d794cd docs: hand off fleet transport contract (#5363 )

2026-07-30 19:47:32 +08:00

5.1 KiB

原始文件 Blame 文件历史

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	pending					后端 PR #5365 已创建并等待 fresh review，尚未合并、部署或执行网关验证；本文件仅为前端消费 pending 草稿，不代表发布态。	2026-07-30	dev-v3

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

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

PR：#5365（OPEN，未合并）

Issue：#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 时表示源数据未提供，前端不得自行归类。

五、响应示例

{
  "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
}

六、前端消费动作

路线展示优先使用 departStation → arriveStation。
单端缺失时显示方向正确的部分路线和缺失端占位，不使用 station 补齐另一端。
仅按权威 transportType=SELF_DRIVE 进入自驾展示分支。
保留对仅含 legacy station 的滚动发布兼容。
领取后按标准状态流转回写 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 已实现、发布或完成页面验证。

5.1 KiB 原始文件 Blame 文件历史 Unescape Escape