chore(changelog): 团期配车就绪门禁与清零释放内部契约 (#5319)

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）契约不变；重配请求在完整覆盖校验下语义收紧（此前不完整计划可提交），调用方须按权威服务日提交