From d0a9d794cd56d4be0aeebb7edea50ccceb10c3be Mon Sep 17 00:00:00 2001 From: API Changelog Bot Date: Thu, 30 Jul 2026 19:47:32 +0800 Subject: [PATCH 1/5] docs: hand off fleet transport contract (#5363) --- ...派车详情大交通契约补全-修改接口-管理后台.md | 134 ++++++++++++++++++ 1 file changed, 134 insertions(+) create mode 100644 changelogs-v2/2026-07/30_5363_车务派车详情大交通契约补全-修改接口-管理后台.md diff --git a/changelogs-v2/2026-07/30_5363_车务派车详情大交通契约补全-修改接口-管理后台.md b/changelogs-v2/2026-07/30_5363_车务派车详情大交通契约补全-修改接口-管理后台.md new file mode 100644 index 0000000..3930fda --- /dev/null +++ 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` 已实现、发布或完成页面验证。 -- 2.43.0 From 93e127454256988c976705d3d7deea6c268929b0 Mon Sep 17 00:00:00 2001 From: API Changelog Bot Date: Thu, 30 Jul 2026 19:50:00 +0800 Subject: [PATCH 2/5] docs: clarify changelog draft gate (#5363) --- .../30_5363_车务派车详情大交通契约补全-修改接口-管理后台.md | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/changelogs-v2/2026-07/30_5363_车务派车详情大交通契约补全-修改接口-管理后台.md b/changelogs-v2/2026-07/30_5363_车务派车详情大交通契约补全-修改接口-管理后台.md index 3930fda..a914955 100644 --- a/changelogs-v2/2026-07/30_5363_车务派车详情大交通契约补全-修改接口-管理后台.md +++ b/changelogs-v2/2026-07/30_5363_车务派车详情大交通契约补全-修改接口-管理后台.md @@ -123,8 +123,9 @@ base: "dev-v3" - 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。 +- changelog 草稿门禁：仓库单元测试 46/46、文件名校验、path aliases 校验及 workflow `lint --allow-pending` 均通过。 -本草稿不声称后端已合并或部署，也不声称网关已验证；`backend_status` 与 `gateway_status` 保持 `pending`，`frontend_status` 保持 `pending`。 +`--allow-pending` 只证明 pending 草稿结构合法，不是发布态 lint 证据。后端未合并/部署且网关未验证，因此本分支不创建指向 `main` 的 changelog PR；`backend_status` 与 `gateway_status` 保持 `pending`，`frontend_status` 保持 `pending`。 ## 八、不影响范围 -- 2.43.0 From 9254671fbecd4514d79ebbf4e9e17d2e265c3937 Mon Sep 17 00:00:00 2001 From: API Changelog Bot Date: Thu, 30 Jul 2026 21:31:39 +0800 Subject: [PATCH 3/5] =?UTF-8?q?docs(api):=20=E4=BF=AE=E6=AD=A3=E6=B4=BE?= =?UTF-8?q?=E8=BD=A6=E5=A4=A7=E4=BA=A4=E9=80=9A=E5=BC=80=E6=94=BE=E5=90=88?= =?UTF-8?q?=E5=90=8C=20(#5363)?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- ...派车详情大交通契约补全-修改接口-管理后台.md | 62 +++++++++++++------ 1 file changed, 42 insertions(+), 20 deletions(-) diff --git a/changelogs-v2/2026-07/30_5363_车务派车详情大交通契约补全-修改接口-管理后台.md b/changelogs-v2/2026-07/30_5363_车务派车详情大交通契约补全-修改接口-管理后台.md index a914955..fe77c0c 100644 --- 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 或消息模板。 -- 2.43.0 From 480949ec456f78bb0a327d3c5ccbfdf9cd433c5e Mon Sep 17 00:00:00 2001 From: API Changelog Bot Date: Fri, 31 Jul 2026 20:15:17 +0800 Subject: [PATCH 4/5] docs(changelog): record #5363 backend merge --- ...派车详情大交通契约补全-修改接口-管理后台.md | 18 ++++++++++-------- 1 file changed, 10 insertions(+), 8 deletions(-) diff --git a/changelogs-v2/2026-07/30_5363_车务派车详情大交通契约补全-修改接口-管理后台.md b/changelogs-v2/2026-07/30_5363_车务派车详情大交通契约补全-修改接口-管理后台.md index fe77c0c..124949d 100644 --- 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 findings，尚未合并、部署或执行网关验证；前端跟踪 #5366 仍为 0/20，本文件仅为 pending 草稿。" +status_note: "后端 PR #5365 已合并至 dev-v3（merge e8e654a482），但尚未部署或执行网关验证；前端跟踪 #5366 仍为 0/20，本文件继续保持 pending。" updated_at: "2026-07-30" base: "dev-v3" --- @@ -20,7 +20,7 @@ base: "dev-v3" > **服务**：`hl-order-service-v3`、`hl-fleet-service` > -> **PR**：[#5365](https://git.1814.love:8443/wx/HL/pulls/5365)（OPEN，未合并） +> **PR**：[#5365](https://git.1814.love:8443/wx/HL/pulls/5365)（已合并，merge `e8e654a482`） > > **Backend Issue**：[#5363](https://git.1814.love:8443/wx/HL/issues/5363) > @@ -138,16 +138,18 @@ base: "dev-v3" ## 验证证据 -- 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：2555 tests，0 failure，0 error，1 skip。 -- order-v3 reactor verify：7031 tests，0 failure，0 error，31 skip。 +- 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 证据。后端未合并/部署且网关未验证，因此本分支不创建指向 `main` 的 changelog PR；`backend_status` 与 `gateway_status` 保持 `pending`，`frontend_status` 保持 `pending`。 +`--allow-pending` 只证明 pending 草稿结构合法，不是发布态 lint 证据。后端已合并但未部署，网关亦未验证，因此本分支不创建指向 `main` 的 changelog PR；`backend_status` 与 `gateway_status` 保持 `pending`，`frontend_status` 保持 `pending`。 ## 九、不影响范围 -- 2.43.0 From 8ff70b4efd06b77da26870fc7b8a32ec97d355c2 Mon Sep 17 00:00:00 2001 From: API Changelog Bot Date: Fri, 31 Jul 2026 21:11:08 +0800 Subject: [PATCH 5/5] docs(changelog): refresh #5363 handoff date --- ...口-管理后台.md => 31_5363_车务派车详情大交通契约补全-修改接口-管理后台.md} | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) rename changelogs-v2/2026-07/{30_5363_车务派车详情大交通契约补全-修改接口-管理后台.md => 31_5363_车务派车详情大交通契约补全-修改接口-管理后台.md} (99%) diff --git a/changelogs-v2/2026-07/30_5363_车务派车详情大交通契约补全-修改接口-管理后台.md b/changelogs-v2/2026-07/31_5363_车务派车详情大交通契约补全-修改接口-管理后台.md similarity index 99% rename from changelogs-v2/2026-07/30_5363_车务派车详情大交通契约补全-修改接口-管理后台.md rename to changelogs-v2/2026-07/31_5363_车务派车详情大交通契约补全-修改接口-管理后台.md index 124949d..0a0fb3f 100644 --- a/changelogs-v2/2026-07/30_5363_车务派车详情大交通契约补全-修改接口-管理后台.md +++ b/changelogs-v2/2026-07/31_5363_车务派车详情大交通契约补全-修改接口-管理后台.md @@ -12,7 +12,7 @@ frontend_ref: "" target_release: "" verified_at: "" status_note: "后端 PR #5365 已合并至 dev-v3（merge e8e654a482），但尚未部署或执行网关验证；前端跟踪 #5366 仍为 0/20，本文件继续保持 pending。" -updated_at: "2026-07-30" +updated_at: "2026-07-31" base: "dev-v3" --- -- 2.43.0