wx/hl-api-changelog

派生 0

文件

T

Mimingguang 1f48714187

changelog-filename-gate / validate (push) Failing after 2s

详情

chore(changelog): #7456 前端 no-op 回写 not_required

2026-09-10 18:21:26 +08:00

17 KiB

原始文件 Blame 文件历史

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	7456	团期生命周期后半段打通：核团开工自动推进 + 验团归档 + 验团反确认	admin	jw(GIT)	修改接口	deployed	verified	not_required	mmg			2026-09-10	团期生命周期此前在「出行完毕」之后就断了——核团（REVIEWING）与验团（SETTLED）两个状态是死枚举，全 order-v3 没有任何代码能推进到它们，看板的「核团中」「已验团」两个桶恒为 0，团期共享成本录入端点因状态门写死 REVIEWING 而根本调不通。本次照订单核单范式补上两跳：① 首次录团期共享成本时把团期从「出行完毕」自动推进到「核团中」（不靠定时任务、不靠日期，与订单侧 advanceSettlementReviewing 同构）；② 新增验团归档端点把「核团中」推到「已验团」终态；③ 新增验团反确认端点，验错了能退回核团中。前端三条必看：① 录共享成本这个既有端点现在有了状态副作用，调用后请重取团期详情刷新状态；② 验团与反确认走财务口径（超管/管理员/财务），与订单核单的 finalize/confirm 同一套角色判据；③ 已验团是终态，流团、改容量、录成本都会被既有状态门挡住。⚠️ 已知缺口：验团前置目前只校验到「状态是 REVIEWING」，原型要求的「核团提交」依赖尚未建的核团四表（GB-ADM-050~052），在那之前验团可能在成本没录完时被点掉，反确认端点兜住一部分。无表变更、无 Flyway，新增错误码 589555。前端实证 no-op:两验团端点未封装零消费方;共享成本端点前端无消费方;看板核团中/已验团桶出数已由 batchLifecycle 九态映射(REVIEWING→AUDITING/SETTLED→CHECKED)覆盖;已验团置灰 canDisband/canAdjustCapacity 白名单早已排除 SETTLED;589555 拦截器透 message。	2026-09-10	dev-v3

团期生命周期后半段：核团开工 + 验团归档 + 反确认

一、给前端的一句话

团期以前走到「出行完毕」就卡死了——核团、验团两个状态在代码里推不进去，看板那两个桶永远是 0。现在通了：首次录团期共享成本会自动把团期推进到「核团中」，新增的验团归档端点把它推到「已验团」终态，验错了还有反确认端点能退回去。

二、变更接口清单

#	接口	方法	路径	变更类型	说明
1	团期验团归档	POST	`/v3/admin/order/group-batch/:groupBatchId/settle`	新增	核团中 → 已验团（终态）
2	团期验团反确认	POST	`/v3/admin/order/group-batch/:groupBatchId/settle/reopen`	新增	已验团 → 核团中，给验错了留退路
3	录入团期共享成本	POST	`/v3/admin/order/group-batch/:groupBatchId/settlement/cost`	修改	新增状态副作用：团期处于「出行完毕」时，首次录入会先把它推进到「核团中」

三、接口详情

1. 团期验团归档 `POST /v3/admin/order/group-batch/:groupBatchId/settle`

VO: 无请求体，返回 Result<Void>

使用场景

核团完成后，团期管理员或财务在团期详情页点「验团归档」，团期进入终态。对应原型状态生命周期表的阶段六：责任人「团期管理员 / 财务」，期间「整团验团复核，确认无误，归档结束」，退出「— 终态」。

入参

字段	位置	类型	必填	约束	说明
`groupBatchId`	path	Long	是	雪花 ID，按字符串传	团期 ID

无 body。

出参

Result<Void>。

字段	类型	说明
`data`	null	无返回体；状态变化请重取团期详情

请求示例

POST /v3/admin/order/group-batch/2089713777065832450/settle
Authorization: Bearer <admin token>

响应示例

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

空数据 / 降级响应

写口，无空数据形态。团期不存在报 589500。 验团时间不落新列——order_group_batch 没有 settled_at（那是 order_main 的列），验团时间从 GET .../status-logs 里 BATCH_SETTLE「验团结算」那条的 changedAt 读，#7304 已开了这个读端点。

错误响应

团期已验团归档，重复调用：

{ "code": 589555, "message": "该团期已验团归档，不可重复验团", "data": null, "success": false }

团期状态不是「核团中」：

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

无权限（非超管 / 管理员 / 财务）：

{ "code": 589507, "message": "无操作权限（非团期管理员 / 非本定制师名下）", "data": null, "success": false }

业务边界

前置：团期状态必须是 REVIEWING（核团中），CAS 推进，并发下只有一个请求成功。
同事务写一条 group_batch_status_log，事件类型 BATCH_SETTLE「验团结算」，REVIEWING → SETTLED。
已验团是终态：流团报 589544、改容量报 589538、录成本报 589501——都是既有状态门，本次一行未补。
⚠️ 已知缺口：前置目前只校验「状态是 REVIEWING」。原型要求的「核团提交」依赖尚未建的核团四表（GB-ADM-050~052），在那之前验团可能在成本没录完时被点掉，靠下面的反确认端点兜。
判权借用订单核单 SettlementWriteGuard 的角色判据（超管 / 管理员 / 财务），错误码用团期域的 589507。

2. 团期验团反确认 `POST /v3/admin/order/group-batch/:groupBatchId/settle/reopen`

VO: 无请求体，返回 Result<Void>

使用场景

验团点早了、或归档后发现成本有误，把团期退回「核团中」继续处理。形状照订单核单的 final-snapshots/reopen——那边验错了有退路，团期这边不该没有。

入参

字段	位置	类型	必填	约束	说明
`groupBatchId`	path	Long	是	雪花 ID，按字符串传	团期 ID

无 body。

出参

Result<Void>。

字段	类型	说明
`data`	null	无返回体；状态变化请重取团期详情

请求示例

POST /v3/admin/order/group-batch/2089713777065832450/settle/reopen
Authorization: Bearer <admin token>

响应示例

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

空数据 / 降级响应

写口，无空数据形态。团期不存在报 589500。

错误响应

团期不是「已验团」状态（比如已经被别人退回过）：

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

无权限：

{ "code": 589507, "message": "无操作权限（非团期管理员 / 非本定制师名下）", "data": null, "success": false }

业务边界

前置：团期状态必须是 SETTLED，CAS 推进，并发下只有一个请求成功。
同事务写 group_batch_status_log，SETTLED → REVIEWING。
退回后可继续录共享成本、可再次验团（TEST 已实测走通一整圈）。
判权与验团归档同一套角色判据。

3. 录入团期共享成本 `POST /v3/admin/order/group-batch/:groupBatchId/settlement/cost`

VO: RecordBatchCostReqVO

使用场景

核团阶段录整团共享成本（大巴 / 领队 / 摄影 / 其它），后续按户分摊。 这个端点本身不是新的，本次变的是它的状态副作用——在此之前，团期根本进不到 REVIEWING，而这个端点的状态门写死「仅 REVIEWING 允许」，所以它实际上一直调不通。

入参

字段	位置	类型	必填	约束	说明
`groupBatchId`	path	Long	是	雪花 ID	团期 ID
`costType`	body	String(枚举)	是	`BUS` / `LEADER` / `PHOTOGRAPHER` / `OTHER`	成本分类
`amount`	body	BigDecimal	是	—	金额
`source`	body	String	是	—	来源
`remark`	body	String	否	—	备注

出参

Result<Long>。

字段	类型	说明
`data`	String	成本行 ID（雪花，按字符串下发）

请求示例

POST /v3/admin/order/group-batch/2089713777065832450/settlement/cost
Authorization: Bearer <admin token>
Content-Type: application/json

{"costType":"BUS","amount":1200.00,"source":"MANUAL","remark":"大巴费用"}

响应示例

{ "code": 200, "message": "成功", "data": "2097990074078580737", "success": true }

空数据 / 降级响应

写口，无空数据形态。入参、出参、既有错误码本次一律未变，变的只是状态副作用。

错误响应

团期既不是「出行完毕」也不是「核团中」：

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

无权限（该端点走 group-batch:finance:advance，#7411 已接）：

{ "code": 589507, "message": "无操作权限（非团期管理员 / 非本定制师名下）", "data": null, "success": false }

业务边界

新增副作用：团期处于 TRIP_FINISHED（出行完毕）时，本端点会先把它 CAS 推进到 REVIEWING（核团中），再执行原有的成本录入。同事务写 BATCH_TRIP_END「返团核团」时间线。
团期已在 REVIEWING 时不重复推进、不重复写时间线（幂等）。
推进不靠定时任务、不靠日期——与订单侧「第一次录核单明细自动把订单从待核单转成核单中」逐字同构。
⚠️ 前端请注意：调用成功后团期状态可能已经变了，请重取团期详情刷新状态与按钮可用性。
已验团（SETTLED）的团期调本端点报 589501，不会被带回核团中（有单测钉住）。

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

录共享成本之后要重取团期详情。它现在有状态副作用，页面上的阶段条、按钮可用性都会变。
验团 / 反确认走财务口径：超管 / 管理员 / 财务，与订单核单的 finalize / confirm 同一套角色判据。定制师、房务、车务等角色会拿到 589507。
验团时间不要找 settled_at 字段——团期表没有这一列。从 GET .../status-logs 里 BATCH_SETTLE 那条的 changedAt 读。
已验团是终态：流团 589544、改容量 589538、录成本 589501。界面上这些按钮应当置灰。
589555 是「已验团归档，不可重复验团」，与 589501「状态不允许」分开——前者告诉用户「已经做过了」，后者告诉用户「现在这个阶段做不了」，提示文案建议区分。
雪花 ID 一律按字符串处理。

五、数据库行为

无表变更、无 Flyway、无数据迁移——验团时间复用 group_batch_status_log，不加 settled_at 列。
两次状态推进都是 CAS（TRIP_FINISHED → REVIEWING、REVIEWING → SETTLED、SETTLED → REVIEWING），并发下只有一个请求成功，重复调用不重复写流水。
新增错误码 589555（团期段 589500-589599，此前占用到 589554）。

六、边界行为

场景	行为
团期在「出行完毕」，首次录共享成本	先推进到「核团中」+ 写 `BATCH_TRIP_END`，再录成本
团期已在「核团中」，再录成本	不重复推进、不重复写时间线，正常录入
团期在「已验团」，录成本	`589501`，不会被带回核团中
验团时团期不是「核团中」	`589501`
重复验团	`589555`
反确认时团期不是「已验团」	`589501`
反确认后	回到「核团中」，可继续录成本、可再次验团
已验团后流团 / 改容量	`589544` / `589538`（既有状态门，本次未补）
无权限调验团 / 反确认	`589507`
并发验团	CAS 保证只有一个成功，另一个拿 `589555` 或 `589501`

六.6、修改前后对比

项	改前	改后
`TRIP_FINISHED → REVIEWING`	没有任何代码能推进（全 order-v3 对 `GroupBatchStatus.REVIEWING` 的命中只有读判据）	首次录共享成本时 CAS 推进
`REVIEWING → SETTLED`	没有任何代码能推进	新增验团归档端点
`SETTLED → REVIEWING`	无	新增反确认端点
录共享成本端点	状态门写死 `REVIEWING`，而团期进不到该状态 → 实际调不通	可从「出行完毕」直接调，端点自己把状态带过去
看板「核团中」「已验团」桶	恒为 0	能真正出数
时间线 `BATCH_TRIP_END` / `BATCH_SETTLE`	枚举定义了但零引用	两跳各写一条

六.7、影响评估

新增的两个端点对现有调用方零影响——没有人在调它们。

录共享成本端点的副作用是增量的：改前团期不可能处于 TRIP_FINISHED 还能调通这个端点（状态门直接拒），所以不存在「改前能调通、改后行为变了」的调用方。改后只是多了一条此前走不到的成功路径。

权限：验团 / 反确认走超管 / 管理员 / 财务。这与原型状态生命周期表里验团责任人「团期管理员 / 财务」完全对上。没有选 group-batch:manage 是因为该码没有授予 FINANCE，选它会把财务挡在验团之外。

运营侧可见变化：团期看板的「核团中」「已验团」两个桶从此会有数据；此前这两个桶恒空，运营看不到任何在核或已归档的团。

七、不影响范围

不改订单侧核单（settlement 域）的任何端点与语义。
不改团期前半段（招募 / 成团 / 资源 / 物资 / 待出发 / 出行中）的任何推进逻辑。
不做核团四表、主 / 次报账人记账、成本平均分摊到各子订单（GB-ADM-050~052）——本单只做状态推进骨架。
无表变更、无 Flyway、无网关路由新增。
只滚 hl-order-service-v3 一个服务。

八、测试环境已验证

TEST（api.test.1814.love）真实网关，团期 2089713777065832450 走完整圈（2026-09-10）。造数：把该团期状态临时置为 TRIP_FINISHED（0 活跃户，不影响其它验收），验完已全部回滚 （状态复原 RESOURCE_PREPARING、造的成本行与 4 条时间线均已删除，复核残留为 0）。

步	实测
① 起始状态	`TRIP_FINISHED`
② 录共享成本	`200`，返回成本行 ID
③ 录后状态自动变成 `REVIEWING`	✅ 时间线 `BATCH_TRIP_END`「返团核团」`TRIP_FINISHED → REVIEWING`
④ 验团归档	`200`；状态 → `SETTLED`；时间线 `BATCH_SETTLE`「验团结算」`REVIEWING → SETTLED`
⑤ 重复验团	`589555`「该团期已验团归档，不可重复验团」
⑥ 终态约束：录成本	`589501`
⑦ 终态约束：流团	`589544`「团期已出行，不可发起或批复流团」
⑧ 终态约束：改容量	`589538`「物料准备开始后不可再调整满团名额」
⑨ 判权：`CUSTOMIZER` 调反确认	`589507`
⑩ 判权：`FINANCE` 调反确认	`200` —— 财务口径生效，与原型「团期管理员 / 财务」对上
⑪ 反确认后状态	`REVIEWING`；时间线 `BATCH_SETTLE` `SETTLED → REVIEWING`
⑫ 反确认后可再次验团	`200`，回到 `SETTLED`

完整链路 TRIP_FINISHED → REVIEWING → SETTLED → REVIEWING → SETTLED 全通。

本机全量：mvn -o -pl hl-order-service-v3 test → Tests run: 9654, Failures: 0, Errors: 0, Skipped: 7, BUILD SUCCESS。新增单测 GroupBatchSettleServiceTest 10 例 + GroupBatchSettlementServiceTest 补 5 例。

十、相关文档

工单：#7456（本单）
原型：团期详情 → 状态生命周期 Tab（阶段六「核团」「验团」两行）
范式来源：订单核单 settlement 域的 advanceSettlementReviewing / finalize / confirm / reopenFinalSnapshot
前序：#7190（出行段两跳 PENDING_DEPARTURE → TRAVELLING → TRIP_FINISHED，本单接着它往下做）、#7304（时间线读端点）
后续：GB-ADM-050~052 核团四表落地后，验团前置要补上「核团已提交」这一条（代码里已留 TODO 锚点）

关联 / 联系人

工单：https://git.1814.love:8443/wx/HL/issues/7456
PR：https://git.1814.love:8443/wx/HL/pulls/7485
后端：jw；前端：mmg

17 KiB 原始文件 Blame 文件历史 Unescape Escape

团期生命周期后半段：核团开工 + 验团归档 + 反确认

一、给前端的一句话

二、变更接口清单

三、接口详情

1. 团期验团归档 POST /v3/admin/order/group-batch/:groupBatchId/settle

使用场景

入参

出参

请求示例

响应示例

空数据 / 降级响应

错误响应

业务边界

2. 团期验团反确认 POST /v3/admin/order/group-batch/:groupBatchId/settle/reopen

使用场景

入参

出参

请求示例

响应示例

空数据 / 降级响应

错误响应

业务边界

3. 录入团期共享成本 POST /v3/admin/order/group-batch/:groupBatchId/settlement/cost

使用场景

入参

出参

请求示例

响应示例

空数据 / 降级响应

错误响应

业务边界

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

五、数据库行为

六、边界行为

六.6、修改前后对比

六.7、影响评估

七、不影响范围

八、测试环境已验证

十、相关文档

关联 / 联系人

17 KiB

原始文件 Blame 文件历史

1. 团期验团归档 `POST /v3/admin/order/group-batch/:groupBatchId/settle`

2. 团期验团反确认 `POST /v3/admin/order/group-batch/:groupBatchId/settle/reopen`

3. 录入团期共享成本 `POST /v3/admin/order/group-batch/:groupBatchId/settlement/cost`