8.8 KiB
8.8 KiB
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 | 7023 | 团期物资三端点补阶段门，合同保险作为进物资准备的前置门 | admin | jw(GIT) | 修改接口 | deployed | verified | not_required | 后端标 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 会自带后端「物资清单只能在准备物资阶段配置」等文案浮出,符合「按错误码提示即可」;契约请求/响应结构不变。无需前端改动。 | 2026-09-07 | 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 |
请求示例
{ "suppliesResourceId": 1001, "quantity": 5 }
响应示例
{ "code": 200, "message": "成功", "success": true }
空数据 / 降级响应
无数据体接口，无空数据形态。
错误响应
{ "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 | 无数据体 |
请求示例
{ "quantity": 8 }
响应示例
{ "code": 200, "message": "成功", "success": true }
空数据 / 降级响应
无数据体接口。
错误响应
{ "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 | 无数据体 |
请求示例
DELETE /v3/admin/order/group-batch/supplies/1932847562341 HTTP/1.1
Authorization: Bearer <admin-token>
响应示例
{ "code": 200, "message": "成功", "success": true }
空数据 / 降级响应
无数据体接口。
错误响应
{ "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
- 口径：AC-TD-13 / AC-TD-15 / AC-TD-16（jw 定案）