hl-api-changelog/changelogs-v2/2026-09/15_7441_团期用车内部回调认团车完成-内部接口-修改接口-管理后台.md

schema, ticket, title, consumer, author, 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	author	change_type	backend_status	gateway_status	frontend_status	frontend_owner	frontend_ref	target_release	verified_at	status_note	updated_at	base
hl-changelog/v2	7441	团期用车内部回调——团车配完/清零双向回写户级需求状态（内部接口分册）	internal	wx(GIT)	修改接口	deployed	verified	not_required					两个端点均为 /v3/internal/** Feign 接口，经网关访问返回 403（JwtAuthFilter 按设计拒绝），取证走直连 order-v3 服务端口（192.168.100.236:8086）+ X-Internal-Token，与 hl-fleet-service 实际调用路径一致。正向（vehicle-ready）与反向（vehicle-ready-reset）均有四次真实调用的完整前后快照（S1-S4，见第八节，见工单 #7441 验收评论）。被测服务：order-v3 = dev-v3 64c3f72a3（2026-09-15 12:06:01 部署），行为在 870610927（含 PR-3）上未再变化。	2026-09-15	dev-v3

order-v3: 团期用车内部回调——团车完成双向回写（内部接口分册）

本文件是分册。 本单（#7441）同批还有 3 份面向前端的 changelog（正式用车需求声明四端点、确认行程清单房车安排短路判定、结算核单车侧闸门升级），本册收件人是后端与 fleet 侧，不是 mmg——两个端点均为跨服务 Feign 调用，hl-ui 调不到。拆分依据 BACKEND_CHANGELOG_DELIVERY_GUIDE.md 2.5 节：/v3/internal/* 必须单独成篇，不许和 admin/mp 接口塞同一份。

服务: hl-order-service-v3 (端口 8083) 消费方: hl-fleet-service（Feign，/v3/internal/**，不经 JWT，靠网关不暴露该前缀做隔离） PR: #7742（PR-2） Issue: #7441 日期: 2026-09-15 影响范围: 既有内部端点 POST /v3/internal/group-batch/{groupBatchId}/vehicle-ready 与 POST .../vehicle-ready-reset，路径/参数/响应结构/错误码均未改，新增户级用车需求状态双向回写副作用

---

⚠️ 关键变化

1. 团级配车完成回调（vehicle-ready）从此会连带把在团户的行程用车（TRAVEL）需求状态回写为完成——改前该回调只置团级 vehicle_ready=true 一列，户级需求行一行不动；改后同一次调用内，未经逐户 DAILY_V3 快照完成的在团户，会被批量推到"已完成"状态并同步订单镜像列。
2. 团级配车清零回调（vehicle-ready-reset）从此会连带把"由团车路径完成"的户打回"处理中"——只接管由本回调正向产出的那批户，已经由逐户 DAILY_V3 快照完成的户、以及完成来源标识为空的历史行，一律不动。
3. 两个端点自身的请求/响应契约完全不变（Result<Void>，团期不存在也返回 200 幂等友好），fleet 侧调用代码无需任何改动。

---

一、背景

fleet 团级配车完成后经 Outbox → Feign 回调 vehicle-ready；团级清零/释放（取消成团、流团、fleet 侧整团释放）后回调 vehicle-ready-reset。改前这两个回调只维护团期聚合根自己的 vehicle_ready 标志位，户级用车需求（order_vehicle_requirement）一行都不碰——全仓唯一把户级需求置完成的生产者是逐户 DAILY_V3 派车快照回调，而团期用车此时已经走团级配车（不逐户派车），于是"整团车已配好、各户需求仍停在待处理"，被 #7445 的结算闸拦死且无任何运营操作能解开。本单补上这个双向回写。

---

二、变更接口清单

#	接口	方法	路径	变更类型	说明
1	回填配车就绪（正向）	POST	/v3/internal/group-batch/{groupBatchId}/vehicle-ready	行为变化	新增在团户 TRAVEL 需求批量完成回写，契约不变
2	重置配车就绪（反向）	POST	/v3/internal/group-batch/{groupBatchId}/vehicle-ready-reset	行为变化	新增"由团车完成"的户打回处理中，契约不变

---

三、接口详情

1. 回填配车就绪（正向） POST /v3/internal/group-batch/{groupBatchId}/vehicle-ready

VO: 无请求体 → Result<Void>

使用场景

fleet-service 整团配车完成后回调。仅限内部 Feign 调用，不经网关（JwtAuthFilter 按设计拒绝 /v3/internal/**），fleet 侧走服务发现直连。幂等：重复调用安全。回填成功后内部自动检测四项资源就绪门，满足则推进团期状态。

入参字段表

字段	位置	类型	必填	约束	说明
groupBatchId	Path	Long	是	-	团期主订单 ID（不变）

（无请求体，不变。）

出参字段表

字段	类型	说明
data	null	结构完全不变，Result<Void>

请求示例

POST /v3/internal/group-batch/2099716821799047169/vehicle-ready HTTP/1.1
X-Internal-Token: ***

（无请求体。测试环境经服务端口直连，生产环境由 fleet-service 经 Feign LB 直连。）

响应示例

（测试服真实响应，2026-09-15 12:28:19，直连 order-v3:8086，见工单 #7441 验收评论）

{ "code": 200, "message": "成功", "data": null, "traceId": null, "success": true }

空数据 / 降级响应

团期不存在时仍返回上述成功结构（幂等友好，不抛错），仅记 WARN 日志，不做任何户级回写。

{ "code": 200, "success": true, "data": null }

错误响应

本单不新增错误码。团期不存在按幂等成功处理（见上），不返回错误响应；其余异常沿用全局异常处理，无本单专属错误码。

{ "code": 500, "message": "系统异常，请稍后重试", "success": false, "data": null }

业务边界

• 同一事务内先置团级 vehicle_ready=true，再取在团户，把 kind=TRAVEL 且状态在"待处理/处理中"的 active 需求 CAS 推进为"已完成"，并同步订单镜像列；团期状态推进在事务外进行。
• 已由逐户 DAILY_V3 快照完成的户跳过、不覆盖：这类户是更权威的完成来源（带逐日车辆/司机明细），团车回写不覆盖它。
• 仍停在"待审核"（配车后才入团、尚未经整团放行）的户跳过并记 WARN，不强推。
• 重复回调幂等：已完成的户读侧直接跳过、不发 CAS；CAS 命中 0 行（读到未完成后被并发推进）记 WARN 跳过，不抛错。
• 团期不存在只记 WARN，不抛错，不影响 Outbox 重投语义。
• 本次回写只改状态与完成来源标识两列，不写任何逐户配车明细列（不产生逐户车辆/司机数据）——车与司机在团级承担，任何逐户配车行都只可能是历史残留。

---

2. 重置配车就绪（反向） POST /v3/internal/group-batch/{groupBatchId}/vehicle-ready-reset

VO: 无请求体 → Result<Void>

使用场景

fleet-service 整团清零、或取消成团/流团释放后回调，把 vehicle_ready 重置为与当前有效计划一致的值。仅限内部 Feign 调用，同上不经网关。幂等：重复调用安全。不触发任何团期状态推进（与置位方向相反）。

入参字段表

字段	位置	类型	必填	约束	说明
groupBatchId	Path	Long	是	-	团期主订单 ID（不变）

（无请求体，不变。）

出参字段表

字段	类型	说明
data	null	结构完全不变，Result<Void>

请求示例

POST /v3/internal/group-batch/2099716821799047169/vehicle-ready-reset HTTP/1.1
X-Internal-Token: ***

响应示例

（测试服真实响应，2026-09-15 12:28:20，直连 order-v3:8086，见工单 #7441 验收评论）

{ "code": 200, "message": "成功", "data": null, "traceId": null, "success": true }

空数据 / 降级响应

团期不存在时仍返回成功结构，仅记 WARN，不做任何户级回写。

{ "code": 200, "success": true, "data": null }

错误响应

本单不新增错误码，异常处理同「三、1」。

{ "code": 500, "message": "系统异常，请稍后重试", "success": false, "data": null }

业务边界

• 同一事务内先重置团级 vehicle_ready=false，再取在团户逐一按行锁 + 锁内复读判定资格后打回"处理中"：只接管"完成来源标识为团车"且"非逐户 DAILY_V3 契约版本"的户——这是必要条件，不是可选加强。
• 两类户一律跳过、三列一字不改：①已由逐户 DAILY_V3 快照完成的户；②完成来源标识为空的历史 legacy 完成行（这类行即使表面状态与团车形态相同，也不会被本回调碰）。测试服实测两类对照户在四步（基线 → reset → ready）全程逐列不变。
• 反向不清"完成来源"标识列：只把状态打回"处理中"，完成来源标识保留，供下一次团车正向回写复用同一判据（幂等）。
• 锁内复读：判定资格必须在拿到需求行锁之后重新读取，不能用取锁前的内存值判断——避免与并发的逐户 DAILY 回调交错时把刚完成的快照户误判打回。
• 团期不存在只记 WARN，不抛错。

---

四、契约约束与正确调用方式

fleet-service 侧调用代码无需任何改动——两个端点的路径、方法、请求体（均无）、响应结构（均为 Result<Void>）与调用时机（配车完成后调正向、清零释放后调反向）全部不变。本单的行为变化完全由 order-v3 内部消化，不要求消费方感知或配合。

---

五、数据库行为

正向回调新增的写行为：同一事务内，在置团级就绪标志之后，把符合条件的在团户行程用车需求状态由"待处理/处理中"推进为"已完成"，同步一列"完成来源"标识，并同步订单侧的用车控制状态镜像列；不写入任何逐户配车明细（车辆/司机/座位等）。反向回调新增的写行为：把"完成来源标识为团车"且"非逐户快照契约"的户由"已完成"打回"处理中"，同步镜像列；"完成来源"标识本身不清空。两个方向均在各自既有事务内完成，不额外引入跨服务同步写。

---

六、边界行为

• 团期不存在 → 两个端点均只记 WARN，返回成功结构，不抛错（不变）
• 已由逐户 DAILY_V3 快照完成的户 → 正向跳过不覆盖，反向跳过不动
• 完成来源标识为空的历史 legacy 完成行 → 反向跳过不动（正向不适用，因为该状态本就不是"待处理/处理中"）
• 仍在"待审核"的户 → 正向跳过并记 WARN，不强推
• 重复调用（Outbox 重投）→ 两个方向均幂等，不抛错、不重复产生副作用

---

六.6、修改前后对比

字段级对比

本单不改两个端点的请求/响应字段结构。

行为级对比

场景	改前	改后
团车配完回调（正向）	只置团级 vehicle_ready=true，户级需求一行不动	同一事务内追加：在团户 TRAVEL 需求批量推进为已完成，同步镜像列
户已由逐户 DAILY_V3 快照完成	不适用（正向改前不碰户级）	跳过、不覆盖
户仍在"待审核"	不适用	跳过并记 WARN，不强推
团车清零回调（反向）	只置团级 vehicle_ready=false	同一事务内追加：把"由团车完成"的户打回处理中
逐户 DAILY_V3 快照户 / 历史 legacy 完成行	不适用（反向改前不碰户级）	一律跳过，三列不变
重复回调	幂等（改前无户级副作用可言）	仍幂等：已完成的户直接跳过不发 CAS

---

六.7、影响评估

• 是否破坏向后兼容: 否，端点契约完全不变，fleet 侧零改动。
• 前端是否必须同步上线: 不适用（frontend_status: not_required，本册收件人是后端与 fleet 侧，hl-ui 调不到这两个端点）。
• 前端 workaround 清理点: 无。

---

七、不影响范围

• 仅影响: 两个内部端点在"团车配完/清零"场景下的户级用车需求状态副作用，端点本身契约不变。
• 零影响:
  • GET /v3/internal/group-batch/{groupBatchId}/dispatch-baseline——同 Controller 第三个端点，本单未改。
  • 逐户 DAILY_V3 派车快照回调链路——完全独立，本单不改其任何代码。
  • fleet-service 自身代码——零改动，仅消费方数据（户级需求状态）随之变化。
  • hl-gateway 路由——/v3/internal/** 本就不上网关，本单不涉及网关配置。

---

八、测试环境已验证

取证环境：order-v3 = dev-v3 64c3f72a3（2026-09-15 12:06:01 部署），经直连服务端口 192.168.100.236:8086 + X-Internal-Token 调用（与 fleet-service 实际调用路径一致；经 hl-gateway 访问 /v3/internal/** 返回 403，非本单行为，属既有设计）。

四组户级快照对照（S1→S4，见工单 #7441 验收评论）：

快照	操作	团车户（GV/MIX）	DAILY_V3 快照户（DV）
S1→S2	正向 vehicle-ready	待处理 → 已完成，完成来源写入	逐列不变（含 update_time）
S2→S3	反向 vehicle-ready-reset	已完成 → 处理中，完成来源保留	仅 update_time 变化（取锁刷新），其余不变
S3→S4	再次正向 vehicle-ready	处理中 → 已完成，完成来源仍为团车	幂等跳过，逐列不变

历史 legacy 完成行（LEG 户，SQL 构造成"已完成+完成来源为空"）在同一组四步全程三列逐字不变，反向回调按"跳过并记 WARN"处理，日志打出了具体判定值。

---

十、相关文档

• 关联 Issue: wx/HL#7441
• 关联 PR: #7742
• 前置依赖：#7439（户级需求表与状态枚举）、#5319（vehicle-ready-reset 端点首次交付）、#3857（vehicle-ready 端点首次交付）
• 相关分册：#7441 正式用车需求声明四端点、确认行程清单房车安排短路判定（消费本单产出的完成状态）、结算核单车侧闸门升级（同样消费本单产出的完成状态）

关联 / 联系人

链接

• Issue: #7441
• PR: #7742

联系人

• 后端负责人: @wx