---
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: "后端标 not_required,前端 mmg grep 复核确认:三端点仅 POST supplies 前端有真实调用(addGroupBatchSupplies,orderV2GroupBatch.js:182→SuppliesPickerModal),PUT quantity/DELETE 前端无封装不可达。POST 调用方 catch 按 code 分支、未知码兜底 err?.message 透后端原文(request.js 统一把 data.message 塞进 err.message),新增 589520/589522 会自带后端「物资清单只能在准备物资阶段配置」等文案浮出,符合「按错误码提示即可」;契约请求/响应结构不变。无需前端改动。"
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<Void>`

| 字段 | 类型 | 说明 |
|------|------|------|
| 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<Void>`

| 字段 | 类型 | 说明 |
|------|------|------|
| 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<Void>`

| 字段 | 类型 | 说明 |
|------|------|------|
| data | null | 无数据体 |

#### 请求示例

```http
DELETE /v3/admin/order/group-batch/supplies/1932847562341 HTTP/1.1
Authorization: Bearer <admin-token>
```

#### 响应示例

```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