hl-api-changelog/changelogs-v2/2026-09/06_7060_成团驱动子订单流程推进-修改接口-管理后台.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	7060	成团驱动子订单流程推进，打通定制师配房配车待办	admin	jw(GIT)	修改接口	deployed	verified	not_required					PR #7104 已合入 dev-v3（合并提交 1289f63d4）；2026-09-06 测试环境造数补验，成团扇出与支付闸门守卫均实测通过	2026-09-06	dev-v3

团期成团: 成团后自动推进子订单流程并派发定制师待办

服务: hl-order-service-v3 ｜ PR: #7104 ｜ Issue: #7060 ｜ 合并提交: 1289f63d4 影响范围: 管理后台「团期详情 → 成团」动作的服务端行为

---

⚠️ 关键变化

POST /v3/admin/order/group-batch/:groupBatchId/group（成团）现在会额外推进子订单状态。

• 变更前：成团只写团期自身的 needs_guide / needs_photographer，完全不碰子订单。定制师那边不会产生任何配房 / 配车待办。
• 变更后：成团时把该团活跃子订单从 AWAITING_PROFILE 推进到 RESOURCE_PREPARING，由既有 syncFlowTodos 自然产生 ASSIGN_ROOM / ASSIGN_VEHICLE 待办。

接口路径、入参、出参均未变，前端无需改动；变化在服务端副作用。

---

一、背景

定制师代办链路此前是断的：成团之后不会有任何待办派给定制师，配房配车需求无从发起。根因是 GroupBatchService#group() 不写子订单。

方案甲（jw 2026-09-03 定案）：复用既有待办链路，只补「推进 flow_status」这一步，待办的开 / 关 / 打回全套复用。 方案乙（批量派发待办、不动 flow_status）已否决——待办自动完成依赖 flow_status rank 触发 completeSystemTodo，走乙会「发得出、关不掉」。

---

二、变更接口清单

#	接口	方法	路径	变更类型	说明
1	团期成团	POST	/v3/admin/order/group-batch/:groupBatchId/group	行为变更	新增子订单流程推进与待办派发副作用；路径/入参/出参不变

---

三、接口详情

1. 团期成团 POST /v3/admin/order/group-batch/:groupBatchId/group

VO: Result<Void>（无请求体）

使用场景

团期管理员在「团期详情」点「成团」。团期由 RECRUITING 进入 RESOURCE_PREPARING，同时把该团活跃子订单推进到资源准备态，触发定制师的配房 / 配车待办。

入参

字段	位置	类型	必填	约束	说明
groupBatchId	Path	Long	✅	—	运营团期 ID（order_group_batch 主键）

出参 Result<Void>

字段	类型	说明
code	Integer	200 成功
data	null	无返回体

请求示例

POST /v3/admin/order/group-batch/2096511923947282434/group

响应示例

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

空数据 / 降级响应

团期无活跃子订单时成团照常成功，仅不产生任何推进与待办。

待办派发失败不影响成团：派发走独立事务，单单失败只记 WARN，成团已提交的结果不回滚。

错误响应

团期不在 RECRUITING 状态：

{
  "code": 589501,
  "message": "团期状态不允许当前操作",
  "success": false,
  "data": null
}

业务边界

• 只从 AWAITING_PROFILE 推进：AWAITING_PAY（未支付）不被推进，不越过支付闸门
• 已在 RESOURCE_PREPARING 及之后的子订单 CAS 天然 miss，重复成团幂等
• 已取消子订单不参与（活跃口径仅排除 CANCELLED）
• 待办派发失败不阻断成团，可由后续任一次 syncForOrder 补发

---

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

• 成团不再是纯团期侧动作，会连带改子订单 flow_status。调用方若在成团前后缓存过子订单状态，需要刷新。
• 待办派给订单的定制师（order.consultant_id）。管理端直接建单若未指定定制师，待办的 assignee 为空，不会出现在任何人的「我的待办」中——这是既有行为，非本次引入。
• 成团返回 200 只代表团期状态推进成功；待办派发是尽力而为，失败不体现在返回码里，需查日志 WARN。

---

五、数据库行为

仅描述外部可观察行为：

• 团期 batch_status：RECRUITING → RESOURCE_PREPARING
• 该团活跃子订单 flow_status：AWAITING_PROFILE → RESOURCE_PREPARING（CAS，其余状态不动）
• 待办表按既有 syncFlowTodos 逻辑新增 ASSIGN_ROOM / ASSIGN_VEHICLE 行
• 不涉及表结构调整，无迁移、无回填

---

六、边界行为

• 团期非 RECRUITING → 589501
• 子订单为 AWAITING_PAY → 不推进
• 重复成团 → 幂等，不重复推进、不重复派发
• 待办派发异常 → 成团仍成功，日志 WARN

---

六.5、枚举 / 数据字典

子订单 flow_status（本次涉及的两个值）

取值	含义
AWAITING_PROFILE	待补全信息（已支付、成团推进的起点）
RESOURCE_PREPARING	资源准备（成团推进的目标，待办在此态产生）

---

六.6、修改前后对比

项	变更前	变更后
成团对子订单的影响	无，完全不碰	活跃子订单 AWAITING_PROFILE → RESOURCE_PREPARING
定制师待办	成团后不产生	成团后自动产生配房 / 配车待办
接口路径 / 入参 / 出参	—	均未变
未支付子订单	—	不受影响，不越过支付闸门

六.7、影响评估

维度	评估
兼容性	接口契约零变化，前端无需改动
行为	成团新增副作用；调用方若缓存子订单状态需刷新
数据	无 DDL、无迁移；仅运行时状态推进
幂等	CAS 保证，重复成团安全
失败隔离	待办派发独立事务，失败不回滚成团
回滚	移除推进调用即可，已推进的子订单状态需人工评估

---

七、不影响范围

• 零影响：成团接口的路径、入参、出参
• 零影响：未支付（AWAITING_PAY）子订单
• 零影响：已取消子订单
• 零影响：待办的开 / 关 / 打回逻辑（全部复用既有实现）

---

八、测试环境已验证

✅ 2026-09-06 于测试环境网关实测，真实鉴权（管理端 admin）。

• 网关 https://api.test.1814.love，合并提交 1289f63d4（特性分支部署后验收，再合入 dev-v3）
• 部署：双实例滚动更新，各 10s 就绪，零停机

#	用例	期望	实测
1	部署启动	新 bean 装配成功	✅ 双实例 UP（装配失败应用起不来）
2	非 RECRUITING 成团	拒绝	✅ 589501 团期状态不允许当前操作
3	既有团期端点无回归	均 200	✅ 列表 / 详情 / 子订单 / 需求摘要 / 物资清单
4	造数：首单懒建	产生 RECRUITING 团期	✅ groupBatchId 2096511923947282434
5	成团推进子订单	AWAITING_PROFILE → RESOURCE_PREPARING	✅ 实测 flowStatus 已变为 RESOURCE_PREPARING
6	支付闸门守卫	AWAITING_PAY 不被推进	✅ 另一单成团后仍为 AWAITING_PROFILE，未越闸

造数路径：POST /v3/admin/order（注意必填 productBatchId，非前端注释所写的 groupBatchId）在团期看板「未命中」排期上建单 → 首单懒建产生 RECRUITING 团期 → manual-receipt 线下收款过支付闸门 → 成团。

待办行未直接观测：待办派给 order.consultant_id，本次造的单未指定定制师，assignee 为空，/order-todos/my/page 查不到；且无按 orderId 查待办的管理端接口。M1 的动作是推进 flow_status，已确证到位；待办由既有 syncFlowTodos 依 flow_status 产生，本单未改该链路。

本地单测：GroupBatchTodoDispatchServiceTest 5 例 + group() 接线 2 例；全量 8119 例 0 failures。

---

九、相关历史 PR

• #7104 本次变更
• 口径定案：jw 2026-09-03「成团驱动待办走甲」

---

十、相关文档

• docs/group/团期模块3天开发计划.md §三 M1
• 团期需求文档：docs/group/（dev-v3 分支）

---

关联 / 联系人

• Issue: #7060 ｜ PR: #7104（合并提交 1289f63d4）
• 服务: hl-order-service-v3
• 后端: jw ｜ 前端: 无需改动