hl-api-changelog/changelogs-v2/2026-09/28_8481_团期物资确认后改清单自动失效并补全物资留痕-修改接口-管理后台.md

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	8481	团期物资确认后再改清单，物资确认自动失效须重新确认；确认物资流水带清单快照，增删改写入时间线，进入待出发改用专用事件码	admin	jw(GIT)	修改接口	deployed	verified	implemented	mmg	93a784cd0b1b69c00ff112675b44c083496a9593	v2.1	2026-09-29	PR #8487 已合入 dev-v3（22fce5985），TEST 的 hl-order-service-v3 运行 dev-v3 22fce5985（面板任务 45bfb475，两实例经运行字节探针确认）。经网关 api.test.1814.love 用 admin token 实测新增 / 改数量 / 删除后物资确认失效、改成原值不失效、失效后团期确认 589556、重新确认后放行、团期确认后三写口 589598、确认物资流水带清单快照、进入待出发记 BATCH_DEPARTURE_ADMIT，全部通过。前端需接：物资面板改数量 / 删除后要刷新团期详情（现在只有确认物资后才刷新），时间线识别三个新事件码（见第四节），故 frontend_status 记 pending。前端已交付(物资三能力成功补 emit changed+配置节点重检预检),详见 hl-admin v2.1 提交 93a784cd。	2026-09-28	dev-v3

团期物资：确认后改清单自动失效 + 物资留痕补全（管理后台）

服务: hl-order-service-v3（端口 8086） PR: #8487（合入 dev-v3 为 22fce5985） Issue: #8481 日期: 2026-09-28 影响范围: 团期物资清单三个写接口、确认物资、团期状态流水（时间线）

---

⚠️ 关键变化

1. 物资确认后再改清单，确认自动失效：团期在「配置」阶段、物资已确认时，新增一行、改数量（改成不同的数）、删除一行，任何一种都会把团期详情的 materialConfirmed 从 true 变回 false，要重新点「确认物资」。团期「确认」门因此只按最近一次确认过的清单放行。
2. 改数量改成原值不算变更：返回 200，不失效、不写流水、数据不动。
3. 确认物资流水带清单快照：BATCH_MATERIAL_CONFIRM 的 content 改为「确认物资清单（共 N 项）」，extra 带 itemCount 和逐行 items[]，能查到确认的是哪一版清单。
4. 时间线新增三个事件码：BATCH_SUPPLIES_CHANGE「物资清单变更」、BATCH_MATERIAL_CONFIRM_RESET「物资变更·物资确认失效」、BATCH_DEPARTURE_ADMIT「进入待出发」。七项硬门全过进入待出发，原来记成「确认物资」，现在记「进入待出发」。
5. 请求、响应结构一字不改，变的是副作用和时间线内容。前端要配合的两处见第四节「前端交接清单」。

---

一、背景

团期缺口台账 g-072 / g-073，jw 2026-09-28 定案（方案 a）：物资确认后，清单任一增删改，确认自动失效、须重新确认。

改前两个问题：

问题	改前	后果
确认后改清单，确认不失效	三个写口都不碰 material_confirmed	团期「确认」门按一份改过、没人再确认的清单放行
留痕不完整	确认物资流水只有「确认物资清单」几个字；增删改零流水；进入待出发也记成「确认物资」	查不到确认的是哪一版清单、谁改过什么；时间线把准入显示成「确认物资」

---

二、变更接口清单

#	接口	方法	路径	变更类型	说明
1	新增团期物资行	POST	/v3/admin/order/group-batch/{groupBatchId}/supplies	修改行为	物资已确认时确认失效；写「物资清单变更」流水
2	调整团期物资数量	PUT	/v3/admin/order/group-batch/supplies/{batchSuppliesId}/quantity	修改行为	同上；改成原值为无变更
3	删除团期物资行	DELETE	/v3/admin/order/group-batch/supplies/{batchSuppliesId}	修改行为	同上
4	确认团期物资	POST	/v3/admin/order/group-batch/{groupBatchId}/confirm-material	修改行为	流水带清单快照
5	团期状态流水	GET	/v3/admin/order/group-batch/{groupBatchId}/status-logs	取值域扩展	eventType 新增三个值

---

三、接口详情

1. 新增团期物资行 POST /v3/admin/order/group-batch/{groupBatchId}/supplies

VO: AddSuppliesReqVO → Result<Long>

使用场景

团期管理员在物资面板从备品库选一个备品（或手填临时物资）加进本团清单。只在「招募」「配置」两个阶段可调。

入参

字段	位置	类型	必填	约束	说明
groupBatchId	Path	Long	✅	雪花 ID	团期主订单 ID
suppliesResourceId	Body	Long	否	备品库上架备品	传了从备品库取名称、分类、计费方式、默认单价
suppliesName	Body	String	条件必填	-	不传 suppliesResourceId 时手填
quantity	Body	Integer	✅	≥1	数量
unitPrice	Body	BigDecimal	否	-	覆盖备品库默认单价
其余字段	Body	-	-	-	category / hasCost / billingType / sortOrder / remark，与现有契约一致，本次不变

出参 Result<Long>

字段	类型	说明
data	Long	新建物资行 ID（batchSuppliesId），不变

请求示例

{
  "suppliesResourceId": "2023438566624866411",
  "quantity": 2
}

响应示例

{ "code": 200, "message": "成功", "data": "2104513829419560962" }

空数据 / 降级响应

无空数据形态；失败时 data=null，见错误响应。

错误响应

{ "code": 589598, "message": "团期已确认，配置不可修改", "data": null }

{ "code": 589523, "message": "该备品已在本团期物资清单中，请直接调整数量", "data": null }

业务边界

• 物资已确认时新增成功：material_confirmed 置回 false，时间线依次多两条：BATCH_SUPPLIES_CHANGE「新增物资：折叠桌椅套装 ×2」、BATCH_MATERIAL_CONFIRM_RESET「物资清单已变更，物资确认失效，需重新确认」。
• 物资未确认时新增成功：只多一条 BATCH_SUPPLIES_CHANGE。
• 阶段不对（团期已确认、已取消）返回 589598，零写入、不记流水。
• 备品库查询仍在事务外；备品不存在或已下架 589519、备品库不可用 589518，与改前相同。

2. 调整团期物资数量 PUT /v3/admin/order/group-batch/supplies/{batchSuppliesId}/quantity

VO: AdjustSuppliesQuantityReqVO → Result<Void>

使用场景

物资面板里改某一行的数量。只在「招募」「配置」两个阶段可调。

入参

字段	位置	类型	必填	约束	说明
batchSuppliesId	Path	Long	✅	雪花 ID	物资行 ID
quantity	Body	Integer	✅	≥1	新数量；等于原值时视为无变更

出参 Result<Void>

字段	类型	说明
data	null	不变

请求示例

{ "quantity": 6 }

响应示例

{ "code": 200, "message": "成功", "data": null }

空数据 / 降级响应

无空数据形态。

错误响应

{ "code": 589598, "message": "团期已确认，配置不可修改", "data": null }

{ "code": 589521, "message": "备品行不存在", "data": null }

业务边界

• 数量真的变了：物资已确认时确认失效，时间线多两条（「修改物资数量：定制遮阳帽 4→6」+ 失效）；未确认时只多一条变更。
• 改成原值：返回 200，不写行、不失效、不记流水。
• 数量 ≤0 仍是参数校验拒绝，与改前相同。
• 两人同时删同一行时，后到的一笔在锁内读不到行，返回 589521（改前静默返回 200）。

3. 删除团期物资行 DELETE /v3/admin/order/group-batch/supplies/{batchSuppliesId}

VO: Result<Void>（无请求体）

使用场景

物资面板里删掉一行（逻辑删除）。只在「招募」「配置」两个阶段可调。

入参

字段	位置	类型	必填	约束	说明
batchSuppliesId	Path	Long	✅	雪花 ID	物资行 ID

出参 Result<Void>

字段	类型	说明
data	null	不变

请求示例

DELETE /v3/admin/order/group-batch/supplies/2104513829419560962

响应示例

{ "code": 200, "message": "成功", "data": null }

空数据 / 降级响应

无空数据形态。

错误响应

{ "code": 589598, "message": "团期已确认，配置不可修改", "data": null }

业务边界

• 物资已确认时删除：确认失效，时间线多「删除物资：折叠桌椅套装 ×2」+ 失效两条；未确认时只多一条变更。
• 行不存在或已删：589521。

4. 确认团期物资 POST /v3/admin/order/group-batch/{groupBatchId}/confirm-material

VO: Result<Void>（无请求体）

使用场景

团期管理员在「配置」阶段确认物资清单。物资已确认是团期「确认」的门条件之一。清单改过之后需要再点一次。

入参

字段	位置	类型	必填	约束	说明
groupBatchId	Path	Long	✅	雪花 ID	团期主订单 ID

出参 Result<Void>

字段	类型	说明
data	null	不变

请求示例

POST /v3/admin/order/group-batch/2104490621953794050/confirm-material

响应示例

{ "code": 200, "message": "成功", "data": null }

空数据 / 降级响应

清单为空也可以确认，流水记「确认物资清单（共 0 项）」，items 为空数组。

错误响应

{ "code": 589501, "message": "团期状态不允许当前操作", "data": null }

业务边界

• 只在「配置」（RESOURCE_PREPARING）可调，与改前相同；库里状态值认不出时也返回 589501（改前是 500）。
• 可以反复确认，每次都记一条带快照的流水。
• 与三个写口拿同一把团期行锁，快照一定是被确认的那一版清单。

5. 团期状态流水 GET /v3/admin/order/group-batch/{groupBatchId}/status-logs

VO: GroupBatchStatusLogItemVO（返回 Result<List<GroupBatchStatusLogItemVO>>，无请求体）

使用场景

团期详情的时间线（GB-ADM-096）。本次结构不变，eventType 多了三个取值，确认物资那条的 content / extra 有内容了。

入参

字段	位置	类型	必填	约束	说明
groupBatchId	Path	Long	✅	雪花 ID	团期主订单 ID

出参 Result<List<GroupBatchStatusLogItemVO>>

字段	类型	说明
eventType	String	新增 BATCH_SUPPLIES_CHANGE / BATCH_MATERIAL_CONFIRM_RESET / BATCH_DEPARTURE_ADMIT，见六.5
eventTypeName	String	对应「物资清单变更」/「物资变更·物资确认失效」/「进入待出发」
changeType	String	前两个是 DATA，BATCH_DEPARTURE_ADMIT 是 STATUS
content	String	展示文本，前端直接渲染
extra	Object	结构化快照，按事件类型不同，见六.5
其余字段	-	logId / fromStatus / toStatus / operatorName / changedAt 等，不变

请求示例

GET /v3/admin/order/group-batch/2104490621953794050/status-logs

响应示例

{
  "code": 200,
  "message": "成功",
  "data": [
    {
      "eventType": "BATCH_MATERIAL_CONFIRM",
      "eventTypeName": "确认物资",
      "changeType": "DATA",
      "content": "确认物资清单（共 4 项）",
      "operatorName": "admin",
      "extra": {
        "itemCount": 4,
        "items": [
          { "batchSuppliesId": "2104513816161357826", "suppliesName": "定制遮阳帽", "category": "personal_gear", "quantity": 4, "unitPrice": 15.00, "billingType": "PER_PERSON", "hasCost": true }
        ]
      },
      "changedAt": "2026-09-28 18:09:31"
    },
    {
      "eventType": "BATCH_SUPPLIES_CHANGE",
      "eventTypeName": "物资清单变更",
      "changeType": "DATA",
      "content": "新增物资：折叠桌椅套装 ×2",
      "extra": { "action": "ADD", "batchSuppliesId": "2104513829419560962", "suppliesName": "折叠桌椅套装", "quantityBefore": 0, "quantityAfter": 2 },
      "changedAt": "2026-09-28 18:09:32"
    },
    {
      "eventType": "BATCH_MATERIAL_CONFIRM_RESET",
      "eventTypeName": "物资变更·物资确认失效",
      "changeType": "DATA",
      "content": "物资清单已变更，物资确认失效，需重新确认",
      "extra": { "triggerAction": "ADD", "batchSuppliesId": "2104513829419560962" },
      "changedAt": "2026-09-28 18:09:32"
    },
    {
      "eventType": "BATCH_DEPARTURE_ADMIT",
      "eventTypeName": "进入待出发",
      "changeType": "STATUS",
      "fromStatus": "MATERIAL_PREPARING",
      "toStatus": "PENDING_DEPARTURE",
      "content": "七项硬门全部通过，进入待出发",
      "extra": null,
      "changedAt": "2026-09-28 18:11:55"
    }
  ]
}

空数据 / 降级响应

无流水时 data=[]，与改前相同。

错误响应

{ "code": 589507, "message": "无操作权限（当前角色未授予团期权限，或该团期不在您名下）", "data": null }

业务边界

• 历史流水不回补：本次上线前「进入待出发」写的是 BATCH_MATERIAL_CONFIRM（changeType=STATUS，toStatus=PENDING_DEPARTURE），这些旧行仍显示「确认物资」。
• 同一秒写入的「变更」「失效」两条按 changedAt 排序，秒级相同时靠库的自然顺序返回；实测为「变更」在前。

---

四、契约约束与正确调用方式

本节只写后端接受/拒绝的规则和前端必须跟着做的事。

✅ 正确 / ❌ 错误用法对照

场景	做法
✅ 改完清单后判断能不能点团期「确认」	重新拉团期详情的 materialConfirmed，或调 confirm-check 看 MATERIAL_CONFIRMED
❌ 改完清单后沿用页面上缓存的「物资已确认」	后端已经失效，点团期「确认」会返回 589556「团期尚不满足确认条件：物资未确认」
✅ 时间线按 eventTypeName 渲染，未知码回落 eventType 原值	三个新码后端已带中文标签

前端交接清单

1. 物资面板改数量 / 删除之后刷新团期详情：hl-ui origin/v2.1 @ 501c4258 的 SuppliesPanel.vue 现在只在确认物资后 emit('changed')，新增 / 改数量 / 删除后不刷新，页头和进度条「配物资·已确认」要手动刷新页面才会变。
2. 时间线认三个新事件码：BATCH_SUPPLIES_CHANGE / BATCH_MATERIAL_CONFIRM_RESET / BATCH_DEPARTURE_ADMIT。若时间线有按事件码配图标或筛选，需要补上。

---

五、数据库行为

情形	order_batch_supplies	order_group_batch.material_confirmed	group_batch_status_log
物资已确认时增 / 改（新值）/ 删	写入	1 → 0	+BATCH_SUPPLIES_CHANGE +BATCH_MATERIAL_CONFIRM_RESET
物资未确认时增 / 改（新值）/ 删	写入	保持 0	+BATCH_SUPPLIES_CHANGE
改数量为原值	不动	不动	不写
阶段不对（589598）	不动	不动	不写
确认物资	不动	→ 1	+BATCH_MATERIAL_CONFIRM（extra 带快照）

• 三个写口的「写物资行 + 失效标记」在同一个事务里：失效那一步失败时物资行一起回滚。流水写失败只告警、不回滚业务（与 #7023 口径一致）。
• 三个写口和确认物资都先锁团期行（SELECT ... FOR UPDATE），彼此串行。
• 无 DDL；新事件码是 event_type 列的新取值。

---

六、边界行为

• 未登录 → 网关返回 code=401（HTTP 200）。
• 无团期管理权限 → 589507，与改前相同。
• 团期创建时从产品带入的物资（系统固化）不写流水、不动确认标记。
• 本单只在写口一侧加锁；团期「确认」本身的读法没改。

---

六.5、枚举 / 数据字典

eventType 新增取值（GroupBatchLogEventType）

值	中文	changeType	extra
BATCH_SUPPLIES_CHANGE	物资清单变更	DATA	action（ADD / ADJUST_QUANTITY / DELETE）、batchSuppliesId（字符串）、suppliesName、quantityBefore、quantityAfter（新增时 before=0，删除时 after=0）
BATCH_MATERIAL_CONFIRM_RESET	物资变更·物资确认失效	DATA	triggerAction、batchSuppliesId（字符串）
BATCH_DEPARTURE_ADMIT	进入待出发	STATUS	null

BATCH_MATERIAL_CONFIRM 的 extra

字段	类型	说明
itemCount	Integer	确认时清单行数
items[].batchSuppliesId	String	物资行 ID（雪花，按字符串）
items[].suppliesName	String	名称
items[].category	String	分类原值（字典码或历史中文，不翻译）
items[].quantity	Integer	数量
items[].unitPrice	BigDecimal	单价，可空
items[].billingType	String	PER_PERSON / PER_QUANTITY，可空
items[].hasCost	Boolean	是否计费

---

六.6、修改前后对比

字段级对比

字段	改前	改后
五个接口的请求 / 响应字段	-	不变
确认物资流水 content	「确认物资清单」	「确认物资清单（共 N 项）」
确认物资流水 extra	null	itemCount + items[]
确认物资流水 changeType	DATA	DATA（枚举定义由 STATUS 改正为 DATA，写入值不变）

行为级对比

行为	改前	改后
物资已确认后增 / 改 / 删	materialConfirmed 仍为 true	置回 false，须重新确认
改数量为原值	照写一次	不写、不失效、不记流水
物资增删改的时间线	无	BATCH_SUPPLIES_CHANGE（+ 失效时 BATCH_MATERIAL_CONFIRM_RESET）
七项硬门全过进入待出发	记 BATCH_MATERIAL_CONFIRM「确认物资」	记 BATCH_DEPARTURE_ADMIT「进入待出发」
两人同时删同一行，后到的一笔	200	589521
确认物资遇到认不出的状态值	500	589501

六.7、影响评估

• 是否破坏向后兼容: 否（结构不变；时间线新增的是取值，旧前端按原值回落显示）
• 前端是否必须同步上线: 否，但不改的话，改完清单后页面上的「物资已确认」会一直显示到手动刷新（点团期「确认」时后端会拦住并提示）
• 前端 workaround 清理点: 无

---

七、不影响范围

• 仅影响: 上面五个接口的副作用与时间线内容
• 零影响:
  • 五个接口的请求 / 响应结构
  • 物资可写阶段（仍是「招募」「配置」两态，团期确认后 589598）
  • 团期「确认」门的判定口径（仍是四项 ready + 物资已确认 + 逐户预检）
  • 物资候选列表、物资列表两个读接口
  • 团期创建时的物资固化

---

八、测试环境已验证

部署：hl-order-service-v3 dev-v3 @ 22fce5985，面板任务 45bfb475，两实例经运行字节探针确认加载的是本次代码（新文案命中、阴性对照未命中）。经网关 api.test.1814.love 用 admin token 实测，团期 2104490621953794050（两户全款、四项资源就绪），另用团期 2104514146831904769 补证团期详情：

POST confirm-material（清单 4 项）                 → 200，material_confirmed 0→1，流水「确认物资清单（共 4 项）」extra.itemCount=4 ✓
POST supplies 已确认后新增 折叠桌椅套装×2          → 200，material_confirmed 1→0，流水 BATCH_SUPPLIES_CHANGE + BATCH_MATERIAL_CONFIRM_RESET ✓
GET  confirm-check                                  → MATERIAL_CONFIRMED passed=false「物资未确认」，其余四项 true ✓
POST confirm（团期确认）                            → 589556「团期尚不满足确认条件：物资未确认」，团期行 / 物资行 / 流水零变化 ✓
POST confirm-material                               → 200，快照「共 5 项」，与上一份不同 ✓
PUT  quantity 定制遮阳帽 4→6（已确认）              → 200，1→0，流水「修改物资数量：定制遮阳帽 4→6」+ 失效 ✓
PUT  quantity 6→6（已确认）                         → 200，标记仍 1，零流水，物资行不变 ✓
DELETE supplies 折叠桌椅套装（已确认）              → 200，1→0，流水「删除物资：折叠桌椅套装 ×2」+ 失效 ✓
PUT  quantity 晕车贴+口罩 4→5（未确认）             → 200，只多 BATCH_SUPPLIES_CHANGE ✓
POST confirm-material → GET confirm-check           → ready=true，五项全部通过 ✓
POST confirm（团期确认）                            → 200，RESOURCE_PREPARING→MATERIAL_PREPARING ✓
POST supplies / PUT quantity / DELETE（团期确认后） → 三个都是 589598「团期已确认，配置不可修改」，零变化 ✓
POST recheck-departure-gate                         → 七门全过，MATERIAL_PREPARING→PENDING_DEPARTURE，流水 BATCH_DEPARTURE_ADMIT「进入待出发」✓
GET  团期详情（另一团期）确认后 / 新增一行后        → materialConfirmed true→false，进度条「配物资·已确认」→「配物资·未确认」✓
POST supplies 不带 token                            → code=401，物资行 4→4 ✓

所有新流水 operatorType=ADMIN、operatorName=admin、changedAt 有值。

---

九、相关历史 PR

• #7023：物资阶段门与确认留痕（确认物资无条件记流水）
• #8268：团期人工「确认」
• #8269：团期确认后锁定配置
• #8478：团期详情分叉进度条（「配物资」分支读 materialConfirmed）

---

十、相关文档

• 关联 Issue: wx/HL#8481
• 关联 PR: wx/HL#8487

关联 / 联系人

链接

• Issue: #8481
• PR: #8487
• Merge commit: 22fce5985

联系人

• 后端负责人: @jw