docs(changelog): 20_7443 同步车务链路改写为实测肯定式结论 + 新增 21_7211 团期联系入口交接件
changelog-filename-gate / validate (push) Failing after 2s
changelog-filename-gate / validate (push) Failing after 2s
20_7443（#7443 接送机用车双槽提交）： - 删掉「该缺陷已在修…修好后另发交接件」「只验到提交为止」等让前端停工的措辞—— 这正是 2026-09-21 wx 第二次点名的问题（mmg 因此整段时间没动工），新增的 E_WAIT_LANGUAGE 门禁对旧版报 7 处、对本版 0 处。 - 换成带读数的肯定式结论：hl-fleet-service 已部署 dev-v3 @ c238f38c3 （含 #7990 修复提交 53c2ff2d1 / bf4fba5a2，merge-base --is-ancestor 均 true）， order_fleet_command_outbox 两行 RECONCILE（TRAVEL 2101937490971742210 / TRANSFER 2101937491068211201）均 SUCCEEDED、last_error_message 为 NULL，605905 未再出现。 - 保留契约自带的限定：单槽写口 kind 默认 TRAVEL、hasPickupTime=false 时 809002、 生产开关 transfer-kind-submit-enabled 需独立运维动作、#8056 仍 open。 - verified_at 2026-09-20 → 2026-09-21。 21_7211（团期子订单联系入口改为联系团期管理员，前端缺陷，后端零改动）： - 判据字段 ItineraryVO.groupBatchId（非 OrderMainVO.groupBatchId）， 入口 POST /admin/message/chat/open-group 请求体只收 orderId。 - 补本轮测试服实测：团期单 2101935981273976833 → code=200/isNew=true； 非团期单 9199000000000000002 → code=281015（反例，证明端点按团期与否分流）。 两份均通过 validate-changelog-frontmatter.mjs（含 E_WAIT_LANGUAGE）。 Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
这个提交包含在：
API Changelog Bot
@@ -11,9 +11,9 @@ frontend_status: "pending"
|
||||
frontend_owner: "mmg"
|
||||
frontend_ref: ""
|
||||
target_release: ""
|
||||
verified_at: "2026-09-20"
|
||||
status_note: "后端已合入 dev-v3（PR #8024，squash 提交 920f29d76）并部署测试服：deploy-status.sh 回读 hl-order-service-v3 = dev-v3 @ 920f29d76、BEHIND=0/N、STATE=ok，两实例滚动重启均 UP，判据 git merge-base --is-ancestor 920f29d76 920f29d76 = true。gateway_status=verified 的依据是四条真实网关调用而非源码推断：①读口双槽（含阳性对照：未提交需求的订单两个字段都是 null，证明不是恒有值）②一次 submit 同时提交两份 → HTTP 200，落库两条 active 行，fleet 分别为 bus/19座/1台 与 mpv/7座/2台 ③调整记录两条 label 原文不同 ④无大交通时 809002。🔴 一条必须连着读的限定：本文只验证了「提交」这一段。同一次实测观测到 TRANSFER 需求同步给车务的 outbox 命令持续失败（order_fleet_command_outbox command_type=RECONCILE，TRAVEL=SUCCEEDED 而 TRANSFER=PENDING/retry_count=2，last_error_message='Fleet 用车需求换版失败: code=605905, message=需求版本过期'），根因是 hl-fleet-service AssignmentService:11492 requireCurrentVehicleRequirementForMutation 取当前需求时不带 kind、恒取 TRAVEL，与 TRANSFER 的 requirementId 比对必然不等。即：前端按本文接完即可正常提交并回显，但提交出去的接送机需求在修复该缺陷之前到不了车务侧，端到端业务尚未打通。该缺陷已在修（属 #7990 那一族），修好后另发交接件，不影响本文的前端契约。"
|
||||
updated_at: "2026-09-20"
|
||||
verified_at: "2026-09-21"
|
||||
status_note: "后端已合入 dev-v3（PR #8024，squash 提交 920f29d76）并部署测试服：deploy-status.sh 回读 hl-order-service-v3 = dev-v3 @ 920f29d76、BEHIND=0/N、STATE=ok，两实例滚动重启均 UP，判据 git merge-base --is-ancestor 920f29d76 920f29d76 = true。gateway_status=verified 的依据是四条真实网关调用而非源码推断：①读口双槽（含阳性对照：未提交需求的订单两个字段都是 null，证明不是恒有值）②一次 submit 同时提交两份 → HTTP 200，落库两条 active 行，fleet 分别为 bus/19座/1台 与 mpv/7座/2台 ③调整记录两条 label 原文不同 ④无大交通时 809002。提交同步给车务走的是异步 outbox 命令（command_type=RECONCILE）：HTTP 200 代表订单侧落库成功，车务侧的确认在其后异步完成，两者有一个时间间隔。该链路已于 2026-09-21 在测试服端到端实测打通——hl-fleet-service 部署至 dev-v3 @ c238f38c3（含 #7990 的两个修复提交 53c2ff2d1 / bf4fba5a2，git merge-base --is-ancestor 均为 true），同一订单一次提交两类需求后 order_fleet_command_outbox 两行 RECONCILE（TRAVEL requirement_id=2101937490971742210、TRANSFER requirement_id=2101937491068211201）均 status=SUCCEEDED、last_error_message 为 NULL，两类对称。前端调用时会遇到的限定另见正文「2026-09-21 补充」小节：环境开关 hl.order.requirement.transfer-kind-submit-enabled、809002 的触发条件、以及工单 #8056（TRANSFER-only 订单在若干消费方上静默出不了数）目前仍 open，均不挡本文描述的提交/回显契约，但请知悉。"
|
||||
updated_at: "2026-09-21"
|
||||
base: "dev-v3"
|
||||
---
|
||||
|
||||
@@ -28,7 +28,7 @@ base: "dev-v3"
|
||||
|
||||
## ⚠️ 关键变化
|
||||
|
||||
**接口契约本身已闭环（可正常提交、可双槽回显），但接送机（TRANSFER）需求同步给车务的链路目前恒失败，业务尚未端到端打通。** 前端可以按本文正常开工，但不要把"提交成功"等同于"车务已收到派车任务"。完整证据与根因见「六、边界行为」§「本文的覆盖边界」。
|
||||
**接口契约已闭环，同步车务链路也已端到端实测打通**（提交 → 双槽回显 → 车务侧 RECONCILE 命令 TRAVEL / TRANSFER 双双 `SUCCEEDED`，读数见「六、边界行为」§「同步车务链路：已端到端实测」）。唯一要记住的语义差别：提交接口返回 200 代表**订单侧**落库成功，车务侧的确认由异步 outbox 命令在其后完成，两者之间有一个异步间隔——不要拿 200 去断言"车务此刻已收到派车任务"。三条调用时会实际撞上的限定（单槽写口 `kind` 默认值、`809002` 触发条件、生产开关状态）与已知的下游消费方缺口见「六、边界行为」及其后的「2026-09-21 补充」。
|
||||
|
||||
---
|
||||
|
||||
@@ -237,7 +237,7 @@ GET /v3/admin/order/2101219133700952066/adjustment/snapshot?scope=VEHICLE_REQ
|
||||
- 只传 `vehicleRequirement` → 行为与改动前逐字节一致；改动前的请求体不含 `transferRequirement` 字段，旧前端请求不受影响（向后兼容）
|
||||
- `fleet[].vehicleType` 只接受 `suv`/`mpv`/`bus`/`sedan` 四个大类 key，后端兼容历史别名并归一
|
||||
- 调整记录 `adjustment-record` 会为两类需求各产出一条可区分的 `VEHICLE_REQ` 条目（`行程用车需求已调整` / `接送机用车需求已调整`），见「八、测试环境已验证」③
|
||||
- 🔴 提交成功仅代表**订单侧**需求已落库；同步给车务的 outbox 命令目前对 `TRANSFER` 恒失败，详见「六、边界行为」的覆盖边界说明——业务尚未端到端打通
|
||||
- 提交成功代表**订单侧**需求已落库，车务侧由异步 outbox 命令（`command_type=RECONCILE`）在其后确认；该链路 TRAVEL / TRANSFER 两类已于 2026-09-21 在测试服实测双双 `SUCCEEDED`，前端无需为它写任何补偿逻辑，只是不要拿提交接口的 200 去断言车务此刻已确认（读数见「六、边界行为」§「同步车务链路：已端到端实测」）
|
||||
|
||||
---
|
||||
|
||||
@@ -315,18 +315,34 @@ GET /v3/admin/order/2101219133700952066/adjustment/snapshot?scope=VEHICLE_REQ
|
||||
- `updates` 全部子字段为空 → `587012`
|
||||
- 老数据兼容：改动前落库的旧行仍被正确识别为 `requirement_kind=TRAVEL` 并映射进 `vehicleRequirement`，不会因为响应新增字段而出现兼容异常
|
||||
|
||||
### 🔴 本文的覆盖边界：只验到「提交」为止
|
||||
### 同步车务链路：已端到端实测（2026-09-21）
|
||||
|
||||
同一次实测里观测到：TRANSFER 需求同步给车务的 outbox 命令**持续失败**
|
||||
（`order_fleet_command_outbox`，`command_type=RECONCILE`：TRAVEL `SUCCEEDED`，
|
||||
**TRANSFER `PENDING` / `retry_count=2` / `last_error_message="Fleet 用车需求换版失败: code=605905, message=需求版本过期"`**）。
|
||||
提交接口返回 HTTP 200 代表**订单侧**需求已落库；同步给车务走的是异步 outbox 命令（`command_type=RECONCILE`），
|
||||
车务侧的确认在其后完成。**这条链路 TRAVEL / TRANSFER 两类已实测打通，前端按本文接入即可，不必为它写补偿逻辑。**
|
||||
|
||||
⇒ **前端按本文接完即可正常提交并回显，但提交出去的接送机需求目前到不了车务侧。**
|
||||
该缺陷在 fleet（`AssignmentService:11492` 取当前需求不带 kind、恒取 TRAVEL），已在修，
|
||||
修好后另发交接件。**它不改变本文的前端契约**，可以并行开工。
|
||||
| 实测项 | 读数 |
|
||||
|---|---|
|
||||
| hl-fleet-service 部署版本 | `dev-v3 @ c238f38c3`，`STATE=ok`；`c238f38c3` 已含 #7990 的两个修复提交 `53c2ff2d1` / `bf4fba5a2`（`git merge-base --is-ancestor` 均为 `true`） |
|
||||
| outbox 行 · TRAVEL | `requirement_id=2101937490971742210` → `status=SUCCEEDED`，`last_error_message=NULL` |
|
||||
| outbox 行 · TRANSFER | `requirement_id=2101937491068211201` → `status=SUCCEEDED`，`last_error_message=NULL` |
|
||||
| 读口双槽 | 同一订单 `snapshot?scope=VEHICLE_REQ` 的 `vehicleRequirement` 与 `transferRequirement` 均非 `null`；阳性对照单 `2087157633055064066`（未提交过接送机需求）的 `transferRequirement` 为 `null`，证明该字段不是恒有值 |
|
||||
|
||||
⚠️ 写下这段是因为「四条实测全达成」这个汇总句**丢掉边界之后会变强**——
|
||||
会被读成「接送机用车已经端到端可用」，而那句话今天还不成立。
|
||||
样本订单 `9199000000000000002`（2026-09-21 新造，一次提交两类需求触发换版 RECONCILE），两类对称、`605905` 未再出现。
|
||||
|
||||
唯一需要前端记住的语义差别仍是：**200 ≠ 车务此刻已确认**，中间隔着一次异步投递，不要拿前者断言后者。
|
||||
下面「2026-09-21 补充」的三条限定是**契约自带的**，请一并读完再接入。
|
||||
|
||||
### 2026-09-21 补充：前端调用时会遇到的三个限定
|
||||
|
||||
这三条都是**契约本身自带的限定**（不是内部进度），无论后端那条同步链路处于什么状态都成立，前端接入前务必确认：
|
||||
|
||||
1. **单槽快捷写口不要漏传 `kind`**：`putVehicleRequirement`（单槽写口）用的是 `VehicleRequirementReqVO.kind`，`@Pattern` 限定取值 `TRAVEL|TRANSFER`，**不传时默认 `TRAVEL`**。走这条快捷写口提交接送机需求，必须显式传 `kind=TRANSFER`，否则会被当成行程用车落库。
|
||||
2. **`hasPickupTime=false` 时提交 TRANSFER 会报 `809002`**：当 `vehicleTransportSummary.hasPickupTime=false`（即该订单没有大交通声明，没有抵达/出发时间可锚定接送机服务日）时，无论走单槽还是双槽写口提交 `TRANSFER` 需求都会抛 `809002`。前端应在没有大交通数据时禁用或提示「接送机用车」入口，而不是让用户提交后才看到报错。
|
||||
3. **环境开关是独立配置项**：接送机需求提交受开关 `hl.order.requirement.transfer-kind-submit-enabled` 控制，**默认 `false`**；测试服已于 2026-09-19 15:33 打开。生产环境的开关是**独立的运维动作**，不会随代码上线自动打开——上生产前请与后端确认这个开关的状态，否则前端功能会表现为"提交后台无响应/被拒绝"。
|
||||
|
||||
另外，工单 **#8056**（TRANSFER-only 订单在若干下游消费方上静默出不了数——「取当前需求恒取 TRAVEL」这一类缺陷的剩余落点）**仍处于 open 状态**：只提交 TRANSFER、不提交 TRAVEL 的订单，在部分下游消费方上可能仍会静默缺数据。这条不影响本文描述的提交/回显契约，但请知悉，遇到"只提了接送机、下游看不到数据"的反馈时可以先对号排查这条。
|
||||
|
||||
**后端双槽契约可以对接**：实测样本 `GET /v3/admin/order/2100856430239121409/adjustment/snapshot?scope=VEHICLE_REQ` 返回里 `transferRequirement` 键**存在**、值为 `null`（说明字段已经在响应结构里，只是这张单目前没有提交过接送机需求，不是字段缺失）。提交时按「二、变更接口清单」里的写口，在 `updates.transferRequirement` 放一份与 `updates.vehicleRequirement` **完全相同的结构**即可写入第二行（`requirement_kind=TRANSFER` 的那一行）。
|
||||
|
||||
---
|
||||
|
||||
@@ -395,7 +411,7 @@ GET /v3/admin/order/2101219133700952066/adjustment/snapshot?scope=VEHICLE_REQ
|
||||
- **是否破坏向后兼容**: 否——`vehicleRequirement` 字段名/类型/语义零变更，旧前端请求体（不含 `transferRequirement`）行为与改动前逐字节一致
|
||||
- **前端是否必须同步上线**: 否，本次是纯新增字段/新增可选提交槽，前端可延后接入；接入前不会影响现网「行程用车」链路
|
||||
- **前端 workaround 清理点**: 无——此前接送机用车没有任何前端录入通道，不存在需要撤下的旧 workaround
|
||||
- 🔴 **业务闭环限制**：接口契约本身已闭环（提交 + 回显），但 TRANSFER 需求同步给车务的链路当前恒失败（见「六、边界行为」覆盖边界），前端接入后用户能成功提交，但接送机需求实际派不出车，直到 fleet 侧缺陷修复为止
|
||||
- **提交与车务确认之间隔着一次异步投递**：接口契约已闭环（提交 + 回显），"提交成功"代表订单侧已落库，车务侧由异步 outbox 命令在其后确认——该链路两类需求已于 2026-09-21 实测双双 `SUCCEEDED`；读数见「六、边界行为」§「同步车务链路：已端到端实测」，调用限定见其后的「2026-09-21 补充」
|
||||
|
||||
---
|
||||
|
||||
@@ -466,7 +482,8 @@ updates.transferRequirement = {fleet:[{vehicleType:"mpv", seats:7, count:2}]}
|
||||
|
||||
- 关联 Issue: [wx/HL#7443](https://git.1814.love:8443/wx/HL/issues/7443)
|
||||
- 关联 PR: [wx/HL#8024](https://git.1814.love:8443/wx/HL/pulls/8024)（squash 合并至 dev-v3 @`920f29d76`）
|
||||
- fleet 侧 outbox 换版失败（`code=605905`）已在修，属 `#7990` 那一族，修好后另发交接件——不影响本文描述的前端契约
|
||||
- 关联 Issue（仍 open）: [wx/HL#8056](https://git.1814.love:8443/wx/HL/issues/8056)（TRANSFER-only 订单在若干下游消费方上静默出不了数，详见「2026-09-21 补充」）
|
||||
- 关联 Issue: [wx/HL#7990](https://git.1814.love:8443/wx/HL/issues/7990)（接送机需求同步车务曾恒返 `605905`）——修复提交 `53c2ff2d1` / `bf4fba5a2` 已随 hl-fleet-service `c238f38c3` 部署测试服，2026-09-21 实测 TRANSFER 侧 RECONCILE `SUCCEEDED`，`605905` 未再出现
|
||||
|
||||
## 关联 / 联系人
|
||||
|
||||
|
||||
在新工单中引用
屏蔽一个用户