diff --git a/changelogs-v2/2026-09/07_7023_团期物资阶段门与确认留痕-修改接口-管理后台.md b/changelogs-v2/2026-09/07_7023_团期物资阶段门与确认留痕-修改接口-管理后台.md new file mode 100644 index 00000000..57612c0e --- /dev/null +++ b/changelogs-v2/2026-09/07_7023_团期物资阶段门与确认留痕-修改接口-管理后台.md @@ -0,0 +1,281 @@ +--- +schema: "hl-changelog/v2" +ticket: "7023" +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: "已合入 dev-v3。2026-09-07 部署测试服并过网关实测：非 MATERIAL_PREPARING 阶段 POST supplies 返回 589520 阶段门拒绝。纯服务端拒绝逻辑，前端按错误码提示即可（not_required）。" +updated_at: "2026-09-07" +base: "dev-v3" +--- + +# 团期物资: 三端点补阶段门 + 确认留痕 + 合同保险前置门 + +> **服务**: hl-order-service-v3 +> **影响范围**: 管理后台团期物资清单的增/删/改三端点 + 团期状态推进（合同保险闸门） + +--- + +## ⚠️ 关键变化 + +物资清单的增删改**只能在「准备物资」(`MATERIAL_PREPARING`) 阶段**操作，其余阶段返回 `589520`。 +此前无阶段限制。另：四资源就绪后，**合同/保险未出齐则团期停在资源筹备中**，不进物资准备阶段。 + +前端无需改造，按错误码提示即可（本单纯服务端）。 + +--- + +## 二、变更接口清单 + +| # | 接口 | 方法 | 路径 | 变更类型 | 说明 | +|---|------|------|------|----------|------| +| 1 | 新增团期备品 | POST | `/v3/admin/order/group-batch/:groupBatchId/supplies` | 新增阶段门 | 非 MATERIAL_PREPARING 返 589520 | +| 2 | 调整备品数量 | PUT | `/v3/admin/order/group-batch/supplies/:batchSuppliesId/quantity` | 新增阶段门 | 同上；数量非法优先返 589522 | +| 3 | 删除备品行 | DELETE | `/v3/admin/order/group-batch/supplies/:batchSuppliesId` | 新增阶段门 | 同上 | + +--- + +## 三、接口详情 + +### 1. 新增团期备品 `POST /v3/admin/order/group-batch/:groupBatchId/supplies` + +**VO**: `AddSuppliesReqVO` + +#### 使用场景 + +团期详情「物资」Tab 添加备品。只有团期处于「准备物资」阶段才允许。 + +#### 入参 + +| 字段 | 位置 | 类型 | 必填 | 约束 | 说明 | +|------|------|------|------|------|------| +| groupBatchId | Path | Long | ✅ | - | 团期主订单 ID | +| suppliesResourceId | Body | Long | ❌ | 与 suppliesName 二选一 | 传则从备品库带出名称/分类/计费方式（见 #6986）| +| suppliesName | Body | String | ❌ | 与 suppliesResourceId 二选一 | 纯手填时用 | +| quantity | Body | Integer | ✅ | 正整数 | ≤0 返 589522 | + +#### 出参 `Result` + +| 字段 | 类型 | 说明 | +|------|------|------| +| data | null | 无数据体，成功仅 code=200 | + +#### 请求示例 + +```json +{ "suppliesResourceId": 1001, "quantity": 5 } +``` + +#### 响应示例 + +```json +{ "code": 200, "message": "成功", "success": true } +``` + +#### 空数据 / 降级响应 + +无数据体接口，无空数据形态。 + +#### 错误响应 + +```json +{ "code": 589520, "message": "物资清单只能在「准备物资」阶段配置", "success": false, "data": null } +``` + +#### 业务边界 + +- **阶段门**：仅 `MATERIAL_PREPARING` 放行，其余阶段（招募中/资源筹备中/待出发/…）返 `589520`。 +- **确认后仍可改**：`material_confirmed=true` 后不转只读，只要仍在 MATERIAL_PREPARING 就放行（jw 两次明确）。 +- **创单固化不受门限**：`freezeFromProduct`（首单懒建固化备品）是系统行为，不走阶段门。 + +### 2. 调整备品数量 `PUT /v3/admin/order/group-batch/supplies/:batchSuppliesId/quantity` + +**VO**: `AdjustSuppliesQuantityReqVO` + +#### 使用场景 + +物资 Tab 改数量。 + +#### 入参 + +| 字段 | 位置 | 类型 | 必填 | 约束 | 说明 | +|------|------|------|------|------|------| +| batchSuppliesId | Path | Long | ✅ | - | 备品行 ID（反查所属团期判阶段）| +| quantity | Body | Integer | ✅ | 正整数 | ≤0 优先返 589522 | + +#### 出参 `Result` + +| 字段 | 类型 | 说明 | +|------|------|------| +| data | null | 无数据体 | + +#### 请求示例 + +```json +{ "quantity": 8 } +``` + +#### 响应示例 + +```json +{ "code": 200, "message": "成功", "success": true } +``` + +#### 空数据 / 降级响应 + +无数据体接口。 + +#### 错误响应 + +```json +{ "code": 589522, "message": "备品数量必须为正整数", "success": false, "data": null } +``` + +#### 业务边界 + +- **错误码可区分**：数量非法先返 `589522`（参数校验），阶段不符返 `589520`（阶段门），两码不同。 +- 阶段门口径同端点 1。 + +### 3. 删除备品行 `DELETE /v3/admin/order/group-batch/supplies/:batchSuppliesId` + +**VO**: `无请求体` + +#### 使用场景 + +物资 Tab 删除一行备品。仅 MATERIAL_PREPARING 阶段可删。 + +#### 入参 + +| 字段 | 位置 | 类型 | 必填 | 约束 | 说明 | +|------|------|------|------|------|------| +| batchSuppliesId | Path | Long | ✅ | - | 备品行 ID（反查所属团期判阶段）| + +#### 出参 `Result` + +| 字段 | 类型 | 说明 | +|------|------|------| +| data | null | 无数据体 | + +#### 请求示例 + +```http +DELETE /v3/admin/order/group-batch/supplies/1932847562341 HTTP/1.1 +Authorization: Bearer +``` + +#### 响应示例 + +```json +{ "code": 200, "message": "成功", "success": true } +``` + +#### 空数据 / 降级响应 + +无数据体接口。 + +#### 错误响应 + +```json +{ "code": 589520, "message": "物资清单只能在「准备物资」阶段配置", "success": false, "data": null } +``` + +#### 业务边界 + +- 阶段门口径同端点 1：仅 MATERIAL_PREPARING 放行，其余阶段返 589520。 +- 删除是软删；确认后（material_confirmed=true）仍可删，不转只读。 + +--- + +## 四、契约约束与正确调用方式 + +| 场景 | 结果 | +|------|------| +| ✅ MATERIAL_PREPARING 阶段增删改 | 200 | +| ❌ 招募中 / 资源筹备中 / 待出发 等阶段 | 589520 | +| ❌ 数量 ≤ 0 | 589522（优先于阶段门）| + +--- + +## 五、数据库行为 + +无表变更、无 Flyway。`markMaterialConfirmed` 后**无条件**记一条 `changeType=DATA` 的确认物资流水 +（含操作人与时间），与状态推进的 STATUS 流水分开；双门未满足时也留痕。 + +--- + +## 六、边界行为 + +- 未登录 → 401（网关拦截） +- 团期不存在 → 589500 +- 阶段不符 → 589520；数量非法 → 589522 +- 创单固化备品 `freezeFromProduct` → 不受阶段门影响 + +## 六.5、枚举 / 数据字典 + +### 团期阶段（`GroupBatchStatus`）与物资门 + +**所属字段**: 服务端判定 | **类型**: `String` + +| 阶段 | 物资增删改 | +|------|-----------| +| `RECRUITING` / `RESOURCE_PREPARING` / `PENDING_DEPARTURE` 等 | 拒（589520）| +| `MATERIAL_PREPARING` | 放行 | + +## 六.6、修改前后对比 + +| 行为 | 改前 | 改后 | +|------|------|------| +| 非物资准备态增删改物资 | 允许 | 拒 589520 | +| 四就绪齐但合同保险未出齐 | 进 MATERIAL_PREPARING | 停在 RESOURCE_PREPARING | +| markMaterialConfirmed 留痕 | 依赖状态推进流水 | 无条件先记一条 DATA 流水 | + +## 六.7、影响评估 + +- 破坏向后兼容：否（新增拒绝分支，正常阶段操作不变） +- 前端必须同步上线：否（按错误码提示） +- 存量团期：已在 MATERIAL_PREPARING 及之后的不被新门卡回（新门只对新进入的团期生效） + +## 七、不影响范围 + +- 仅影响：团期物资增删改三端点的阶段限制 + 合同保险前置门 +- 零影响：confirmMaterial 双门推进（保留）、创单固化、C 端、其余团期端点 + +--- + +## 八、测试环境已验证 + +✅ **已验证。** 2026-09-07 部署 dev-v3 到测试服并经网关实测（真实管理端鉴权）。 + +产品 2044306857534636034 第 7 期（`RESOURCE_PREPARING` 态，非物资准备）： + +| 用例 | 期望 | 实测 | +|------|------|------| +| 非 MATERIAL_PREPARING 打 POST supplies | 589520 阶段门拒绝 | ✅ `589520 物资清单只能在「准备物资」阶段配置` | + +码层核实（子代理）AC-1~AC-13 全部成立：三端点阶段门、确认后仍可改、confirmMaterial 双门保留、 +markMaterialConfirmed 无条件 DATA 流水、freezeFromProduct 不受门限、589520/589522 可区分、 +合同保险前置门（isContractInsuranceReady）、存量团期不回退。 + +## 九、相关历史 PR + +| PR | Issue | 说明 | +|----|-------|------| +| — | #7023 | 团期物资阶段门 + 确认留痕 + 合同保险前置门 | + +## 十、相关文档 + +- 关联 Issue: [wx/HL#7023](https://git.1814.love:8443/wx/HL/issues/7023) +- 口径：AC-TD-13 / AC-TD-15 / AC-TD-16（jw 定案） + +## 关联 / 联系人 + +- **Issue**: [#7023](https://git.1814.love:8443/wx/HL/issues/7023) +- **后端负责人**: @jw