diff --git a/changelogs-v2/2026-09/06_7060_成团驱动子订单流程推进-修改接口-管理后台.md b/changelogs-v2/2026-09/06_7060_成团驱动子订单流程推进-修改接口-管理后台.md new file mode 100644 index 00000000..b1b14699 --- /dev/null +++ b/changelogs-v2/2026-09/06_7060_成团驱动子订单流程推进-修改接口-管理后台.md @@ -0,0 +1,235 @@ +--- +schema: "hl-changelog/v2" +ticket: "7060" +title: "成团驱动子订单流程推进，打通定制师配房配车待办" +consumer: "admin" +author: "jw(GIT)" +change_type: "修改接口" +backend_status: "deployed" +gateway_status: "verified" +frontend_status: "not_required" +frontend_owner: "" +frontend_ref: "" +target_release: "" +verified_at: "" +status_note: "PR #7104 已合入 dev-v3（合并提交 1289f63d4）；2026-09-06 测试环境造数补验，成团扇出与支付闸门守卫均实测通过" +updated_at: "2026-09-06" +base: "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`（无请求体） + +#### 使用场景 + +团期管理员在「团期详情」点「成团」。团期由 `RECRUITING` 进入 `RESOURCE_PREPARING`，同时把该团活跃子订单推进到资源准备态，触发定制师的配房 / 配车待办。 + +#### 入参 + +| 字段 | 位置 | 类型 | 必填 | 约束 | 说明 | +|------|------|------|------|------|------| +| `groupBatchId` | Path | Long | ✅ | — | 运营团期 ID（`order_group_batch` 主键） | + +#### 出参 `Result` + +| 字段 | 类型 | 说明 | +|------|------|------| +| `code` | Integer | 200 成功 | +| `data` | null | 无返回体 | + +#### 请求示例 + +```http +POST /v3/admin/order/group-batch/2096511923947282434/group +``` + +#### 响应示例 + +```json +{ + "code": 200, + "message": "成功", + "success": true, + "data": null +} +``` + +#### 空数据 / 降级响应 + +团期无活跃子订单时成团照常成功，仅不产生任何推进与待办。 + +**待办派发失败不影响成团**：派发走独立事务，单单失败只记 WARN，成团已提交的结果不回滚。 + +#### 错误响应 + +团期不在 `RECRUITING` 状态： + +```json +{ + "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 ｜ **前端**: 无需改动