From 4fbf5ec2c05b062c8ac2133ee3062088de751f8d Mon Sep 17 00:00:00 2001 From: API Changelog Bot Date: Mon, 21 Sep 2026 16:16:07 +0800 Subject: [PATCH] =?UTF-8?q?docs(changelog):=2020=5F7443=20=E5=88=A0?= =?UTF-8?q?=E6=8E=89=E6=8A=8A=E5=89=8D=E7=AB=AF=E6=8E=A8=E5=90=91=E3=80=8C?= =?UTF-8?q?=E9=97=AE=E4=B8=8A=E7=BA=BF=E6=97=B6=E9=97=B4=E3=80=8D=E7=9A=84?= =?UTF-8?q?=E4=B8=A4=E5=A4=84=E6=8E=AA=E8=BE=9E?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 「生产环境未开」暗示生产上存在这个开关、只是关着——实际 order-v3 根本没上生产 （2026-09-21 探生产网关，/v3/** 与 /admin/fleet/** 全 404，一期 /admin/order/page 与 /admin/product/page 同时 200 做阳性对照）。前端据此来问「请后端把生产开关打开」， 是照本文档做的。 「上生产前请与后端确认这个开关的状态」是一条派给前端、他查不了、且只影响 「什么时候开始写」而非「怎么写代码」的动作项，整句删除。 一并去掉两处部署时间戳（2026-09-19 15:33）——交接件不写上线/部署时间。 改后只留环境无关的契约事实：默认 false、关闭时返 809009、测试服已开。 ⚠️ E_WAIT_LANGUAGE 没能拦住这两句：它按词表匹配「等/待/另发」，而这两句一个都没用上， 靠的是把不确定性包装成「请你去确认」。词表拦不住换了语法的同一件事。 Co-Authored-By: Claude Opus 5 (1M context) --- ...页同页提交行程与接送机两类用车需求-修改接口-管理后台.md | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-) diff --git a/changelogs-v2/2026-09/20_7443_调整订单车辆安排页同页提交行程与接送机两类用车需求-修改接口-管理后台.md b/changelogs-v2/2026-09/20_7443_调整订单车辆安排页同页提交行程与接送机两类用车需求-修改接口-管理后台.md index 4a06d76f..62b1bf12 100644 --- a/changelogs-v2/2026-09/20_7443_调整订单车辆安排页同页提交行程与接送机两类用车需求-修改接口-管理后台.md +++ b/changelogs-v2/2026-09/20_7443_调整订单车辆安排页同页提交行程与接送机两类用车需求-修改接口-管理后台.md @@ -28,7 +28,7 @@ base: "dev-v3" ## ⚠️ 关键变化 -**接口契约已闭环，同步车务链路也已端到端实测打通**（提交 → 双槽回显 → 车务侧 RECONCILE 命令 TRAVEL / TRANSFER 双双 `SUCCEEDED`，读数见「六、边界行为」§「同步车务链路：已端到端实测」）。唯一要记住的语义差别：提交接口返回 200 代表**订单侧**落库成功，车务侧的确认由异步 outbox 命令在其后完成，两者之间有一个异步间隔——不要拿 200 去断言"车务此刻已收到派车任务"。三条调用时会实际撞上的限定（单槽写口 `kind` 默认值、`809002` 触发条件、生产开关状态）与已知的下游消费方缺口见「六、边界行为」及其后的「2026-09-21 补充」。 +**接口契约已闭环，同步车务链路也已端到端实测打通**（提交 → 双槽回显 → 车务侧 RECONCILE 命令 TRAVEL / TRANSFER 双双 `SUCCEEDED`，读数见「六、边界行为」§「同步车务链路：已端到端实测」）。唯一要记住的语义差别：提交接口返回 200 代表**订单侧**落库成功，车务侧的确认由异步 outbox 命令在其后完成，两者之间有一个异步间隔——不要拿 200 去断言"车务此刻已收到派车任务"。三条调用时会实际撞上的限定（单槽写口 `kind` 默认值、`809002` 触发条件、环境开关状态）与已知的下游消费方缺口见「六、边界行为」及其后的「2026-09-21 补充」。 --- @@ -260,7 +260,7 @@ GET /v3/admin/order/2101219133700952066/adjustment/snapshot?scope=VEHICLE_REQ | ✅ 只提交接送机用车（订单已录大交通） | `{"updates":{"transferRequirement":{"fleet":[...]}}}` | 200，落 1 条 `TRANSFER` 需求 | | ✅ 同页两类都提交 | `{"updates":{"vehicleRequirement":{...},"transferRequirement":{...}}}` | 200，落 2 条 active 需求（见「八」②实测） | | ❌ 提交接送机用车但订单未录大交通 | `{"updates":{"transferRequirement":{"fleet":[...]}}}` | `809002`，整笔回滚（见「八」④实测） | -| ❌ 提交接送机用车但开关未开（生产默认） | 同上 | `809009` | +| ❌ 提交接送机用车但开关未开（默认关闭） | 同上 | `809009` | | ❌ 期望通过入参指定 `serviceDates` | `{"updates":{"transferRequirement":{"serviceDates":[...]}}}` | **无效**——该字段不在 `VehicleRequirementBodyVO` 定义内，传了也会被忽略，服务日仍按后端派生规则计算 | ### 前端必须处理的前置：没有大交通时提交接送机需求会失败 @@ -276,13 +276,13 @@ GET /v3/admin/order/2101219133700952066/adjustment/snapshot?scope=VEHICLE_REQ | 错误码 | 触发条件 | 前端应做的下一步 | |---|---|---| | `809002` | 该订单尚未录入大交通行程，却提交了 `transferRequirement` | **去补大交通**——引导用户先在大交通模块录入行程，而不是重试提交 | -| `809009` | `hl.order.requirement.transfer-kind-submit-enabled` 开关未开（生产环境默认关闭） | **找后端开开关**——这不是数据问题，重试/补数据都无效，需要后端改配置并重启实例 | +| `809009` | 当前环境的 `hl.order.requirement.transfer-kind-submit-enabled` 开关未开启 | **找后端确认该环境的开关**——这不是数据问题，重试/补数据都无效，需要后端改配置并重启实例 | ### 环境开关 `hl.order.requirement.transfer-kind-submit-enabled` -- **代码默认 `false`**；生产环境未开，提交 `kind=TRANSFER` 返 `809009` -- **测试服已置 `true`**（2026-09-19 15:33:32 发布，随 order-v3 重启生效） +- **代码默认 `false`**：未显式置 `true` 的环境上，提交 `kind=TRANSFER` 返 `809009` +- **测试服已置 `true`**（随 order-v3 重启生效） - ⚠️ 该配置无 `@RefreshScope`（源码 `RequirementService` 注释确认），改完必须重启服务才生效，Nacos 热推不生效 --- @@ -338,7 +338,7 @@ GET /v3/admin/order/2101219133700952066/adjustment/snapshot?scope=VEHICLE_REQ 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 打开。生产环境的开关是**独立的运维动作**，不会随代码上线自动打开——上生产前请与后端确认这个开关的状态，否则前端功能会表现为"提交后台无响应/被拒绝"。 +3. **环境开关是独立配置项**：接送机需求提交受开关 `hl.order.requirement.transfer-kind-submit-enabled` 控制，**代码默认 `false`**，关闭时提交 `kind=TRANSFER` 一律返 `809009`（写口直接拒绝，一行都不落库）。**测试服已开启**，本文所有实测读数都是在开关打开的前提下取得的。收到 `809009` 即表示所在环境的开关没开，属配置问题，重试与补数据均无效。 另外，工单 **#8056**（TRANSFER-only 订单在若干下游消费方上静默出不了数——「取当前需求恒取 TRAVEL」这一类缺陷的剩余落点）**仍处于 open 状态**：只提交 TRANSFER、不提交 TRAVEL 的订单，在部分下游消费方上可能仍会静默缺数据。这条不影响本文描述的提交/回显契约，但请知悉，遇到"只提了接送机、下游看不到数据"的反馈时可以先对号排查这条。