hl-api-changelog/changelogs-v2/2026-08/03_5319_团期配车就绪门禁与清零释放内部契约-修改接口-内部服务.md

schema, ticket, title, consumer, change_type, backend_status, gateway_status, frontend_status, frontend_owner, frontend_ref, target_release, verified_at, status_note, updated_at, base

schema	ticket	title	consumer	change_type	backend_status	gateway_status	frontend_status	frontend_owner	frontend_ref	target_release	verified_at	status_note	updated_at	base
hl-changelog/v2	5319	团期配车就绪门禁与清零释放内部契约	internal	修改接口	deployed	not_required	not_required					PR #5432 已合并 dev-v3（c3c78ea8f）；fleet 4b1ab397 / order-v3 5bc5d247 已部署测试环境并经服务直连验证。internal 契约仅供服务间 Feign 消费，前端不涉及。	2026-08-03	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）契约不变；重配请求在完整覆盖校验下语义收紧（此前不完整计划可提交），调用方须按权威服务日提交

关联 / 联系人

联系人

• 后端负责人: @wx