From b14ababc3d0141a90ed8d299d42687a72cad8e6e Mon Sep 17 00:00:00 2001 From: API Changelog Bot Date: Mon, 3 Aug 2026 19:32:58 +0800 Subject: [PATCH] =?UTF-8?q?chore(changelog):=20=E5=9B=A2=E6=9C=9F=E9=85=8D?= =?UTF-8?q?=E8=BD=A6=E5=B0=B1=E7=BB=AA=E9=97=A8=E7=A6=81=E4=B8=8E=E6=B8=85?= =?UTF-8?q?=E9=9B=B6=E9=87=8A=E6=94=BE=E5=86=85=E9=83=A8=E5=A5=91=E7=BA=A6?= =?UTF-8?q?=20(#5319)?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- ...绪门禁与清零释放内部契约-修改接口-内部服务.md | 58 +++++++++++++++++++ 1 file changed, 58 insertions(+) create mode 100644 changelogs-v2/2026-08/03_5319_团期配车就绪门禁与清零释放内部契约-修改接口-内部服务.md diff --git a/changelogs-v2/2026-08/03_5319_团期配车就绪门禁与清零释放内部契约-修改接口-内部服务.md b/changelogs-v2/2026-08/03_5319_团期配车就绪门禁与清零释放内部契约-修改接口-内部服务.md new file mode 100644 index 0000000..26de11b --- /dev/null +++ b/changelogs-v2/2026-08/03_5319_团期配车就绪门禁与清零释放内部契约-修改接口-内部服务.md @@ -0,0 +1,58 @@ +--- +schema: "hl-changelog/v2" +ticket: "5319" +title: "团期配车就绪门禁与清零释放内部契约" +consumer: "internal" +change_type: "修改接口" +backend_status: "deployed" +gateway_status: "not_required" +frontend_status: "not_required" +frontend_owner: "" +frontend_ref: "" +target_release: "" +verified_at: "" +status_note: "PR #5432 已合并 dev-v3（c3c78ea8f）；fleet 4b1ab397 / order-v3 5bc5d247 已部署测试环境并经服务直连验证。internal 契约仅供服务间 Feign 消费，前端不涉及。" +updated_at: "2026-08-03" +base: "dev-v3" +--- + +# 团期配车就绪门禁与清零释放内部契约（#5319） + +> **服务**: hl-fleet-service（8087）/ hl-order-service-v3（8086） +> **PR**: #5432 +> **Issue**: #5319 +> **日期**: 2026-08-03 +> **影响范围**: 团期配车重配就绪校验、整团清零/释放、vehicle_ready 双向回填（服务间 internal Feign） + +--- + +## ⚠️ 关键变化 + +- Fleet `POST /internal/fleet/dispatch/group-batch/reconfigure` 重配前新增 order-v3 权威基线校验： + - 服务日必须完整覆盖团期 departDate..endDate（缺首日/末日/中间日、越界、空洞原子失败） + - 仅 `RESOURCE_PREPARING`（成团后资源配置阶段）可配，已流团/终态及出行后状态拒绝 + - 新增 `clearAll=true` 显式整团清零语义（软删全部活跃配车 + vehicle_ready=false） +- `GROUP_READY` 意图按团期级 planVersion 去重（新表 fleet_group_dispatch_plan），相同计划重复提交不新增意图 + +## 变更接口 + +| # | 接口 | 方法 | 路径 | 变更类型 | 说明 | +|---|------|------|------|----------|------| +| 1 | 团期配车重配 | POST | `/internal/fleet/dispatch/group-batch/reconfigure`（Fleet，Feign 入向） | 修改接口 | 新增权威基线校验 + clearAll 清零；请求体新增 `clearAll` 字段（可空） | +| 2 | 团期配车占用释放 | POST | `/internal/fleet/dispatch/group-batch/:groupBatchId/release`（Fleet，Feign 入向） | 新增接口 | 幂等软删全部活跃配车 + vehicle_ready=false | +| 3 | 团期配车权威基线 | GET | `/v3/internal/group-batch/:groupBatchId/dispatch-baseline`（order-v3，Feign 出向） | 新增接口 | 返回服务日集合 + 生命周期可配判定；团期不存在返 589500 | +| 4 | 重置配车就绪 | POST | `/v3/internal/group-batch/:groupBatchId/vehicle-ready-reset`（order-v3，Feign 出向） | 新增接口 | vehicle_ready=false 幂等重置 | +| 5 | 回填配车就绪 | POST | `/v3/internal/group-batch/:groupBatchId/vehicle-ready`（order-v3，Feign 出向） | 修改接口 | 语义不变（置 true 幂等），配合清零/释放双向闭环 | + +## 调用方动作（internal） + +- order-v3 团期配车编排方：重配请求按权威服务日提交完整计划；需清零时置 `clearAll=true`（demands 可空） +- 共享 DTO：`GroupBatchDispatchBaselineDTO`（hl-common-core）新增 +- 前端不消费任何 internal 端点，无前端动作 + +## 验证证据 + +- 定向测试：Fleet `GroupDispatchServiceTest`（29 用例）+ writer/effect/listener；order-v3 `GroupBatchServiceTest`/Outbox processor/service/listener/controller 契约 +- reactor verify：Fleet 2870 用例（仅 Testcontainers MySQL 无 Docker 环境失败，基线同样失败）；order-v3 全量 verify 通过；fleet spotless:check 通过 +- 网关验证：internal 路径经网关 403 为设计行为（JwtAuthFilter 全局阻断）；经服务直连验证 release=200、dispatch-baseline=589500（失败关闭）、vehicle-ready-reset=200、vehicle-ready=200（证据 `tmp/5319-gateway-evidence.md`） +- 兼容性结论：既有 `vehicle-ready`（置 true）契约不变；重配请求在完整覆盖校验下语义收紧（此前不完整计划可提交），调用方须按权威服务日提交