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

## 关联 / 联系人

### 联系人

- **后端负责人**: @wx