jw和Claude Opus 5
41f3f69500
changelog-filename-gate / validate (push) Successful in 2s
POST /v3/admin/order/group-batch/:groupBatchId/group 新增副作用：成团时把 该团活跃子订单从 AWAITING_PROFILE 推进到 RESOURCE_PREPARING，由既有 syncFlowTodos 产生配房/配车待办派给定制师。 接口路径、入参、出参均未变，前端无需改动；变化在服务端副作用。 调用方若缓存过子订单状态需刷新。 边界：只从 AWAITING_PROFILE 推进，AWAITING_PAY 不越过支付闸门；重复成团 幂等（CAS）；待办派发走独立事务，失败不回滚成团。 2026-09-06 测试环境造数补验，6 组用例通过。核心两条在真实数据上确证： 成团后子订单 flowStatus 由 AWAITING_PROFILE 变为 RESOURCE_PREPARING； 另一单成团时为 AWAITING_PAY，成团后未被推进。 backend_status=deployed / gateway_status=verified。 Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
236 行
8.6 KiB
Markdown
236 行
8.6 KiB
Markdown
---
|
||
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<Void>`（无请求体）
|
||
|
||
#### 使用场景
|
||
|
||
团期管理员在「团期详情」点「成团」。团期由 `RECRUITING` 进入 `RESOURCE_PREPARING`，同时把该团活跃子订单推进到资源准备态，触发定制师的配房 / 配车待办。
|
||
|
||
#### 入参
|
||
|
||
| 字段 | 位置 | 类型 | 必填 | 约束 | 说明 |
|
||
|------|------|------|------|------|------|
|
||
| `groupBatchId` | Path | Long | ✅ | — | 运营团期 ID（`order_group_batch` 主键） |
|
||
|
||
#### 出参 `Result<Void>`
|
||
|
||
| 字段 | 类型 | 说明 |
|
||
|------|------|------|
|
||
| `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 ｜ **前端**: 无需改动
|