wx/hl-api-changelog
1
0
派生 0
代码 工单 合并请求 工作流 软件包 项目 发布 百科 活动
文件
main
hl-api-changelog/changelogs-v2/2026-09/18_7932_团期验团归档前置核团-修改接口-管理后台.md
T

15 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 7932 验团归档前置核团定稿并同事务推进核团为已验团，验团反确认同步退回核团 admin jw(GIT) 修改接口 deployed verified not_required 已上线的验团归档 POST .../settle 行为变更：核团须先提交核算（ALLOCATED）才能验团，验团同事务把核团推到已验团（CHECKED）；新增可选请求体 checkNote（验团意见）。验团反确认 POST .../settle/reopen 同事务把核团从已验团退回已核算。⚠️ 处于核单中（REVIEWING）但还没有核团记录的团，验团会返回 589567，须先在核团 Tab 完成定稿。后端 PR #7944 已合并 dev-v3 并部署 TEST。核团 7 个新接口见同日新增接口 changelog。前端实证（hl-ui v2.1，2026-09-20）：本件为验团写口新增前置校验（589567），属后端拦截口径，前端惯例由拦截器透后端 message、不建字典；验团功能本身尚未接入前端，将随同日核团新增接口件一并排期时覆盖该前置提示，本件不单独产生前端改动，翻 not_required。后续：验团按钮（REVIEWING+ALLOCATED 双条件置灰）、验团意见 checkNote≤512、589567/589568 透 message、验团/反确认成功刷新面板与详情，已随同日核团新增接口件一并交付（hl-ui v2.1 @ 5833f46f），本件维持 not_required 不填认领字段。 2026-09-18 dev-v3

order-v3: 🔧 验团归档须先完成核团定稿，验团 / 反确认与核团状态联动

存放目录: changelogs-v2/{YYYY-MM}/（管理后台，二期 order-v3）

服务: hl-order-service-v3（order-v3） PR: #7944（合并提交 db3abc6c7；后续 #7955 未改这两个接口） Issue: #7932 日期: 2026-09-18 影响范围: 团期详情「验团」「验团反确认」按钮

⚠️ 关键变化

  1. ⚠️ 线上已有接口的行为变更：POST .../settle（验团归档）以前只要团期在「核单中」（REVIEWING）就能点；现在还要求核团已提交核算。
    • 处于核单中但还没有核团记录的团，验团会返回 589567（「该团期尚未进入核团：尚无核团记录，请先在核团 Tab 完成核算定稿后再验团」）。
    • 核团还在录入中，验团返回 589568。
    • 运营须先到「核团验团」Tab：打开面板（自动生成草稿）→ 保存 → 提交核算，然后再验团。
  2. 验团成功时，核团与团期在同一个事务里一起变：核团 ALLOCATED → CHECKED、团期 REVIEWING → SETTLED，不会出现一个变了一个没变。
  3. 验团新增可选请求体 { "checkNote": "..." }（验团意见，≤512 字）；不传 body 与以前一样能调。
  4. POST .../settle/reopen（验团反确认）同时把核团从「已验团」退回「已核算」，并清空验团意见；要改分摊数须再点「重新核算」。
  5. 路径、响应结构、判权方式都不变。

一、背景

以前验团只看团期状态，「成本还没录完就能点验团」是已知缺口。#7932 上线核团后，验团改为以核团定稿为前提，并与核团「已验团」合并成一个动作（不另设 /audit/check 接口）。

二、变更接口清单

# 接口 方法 路径 变更类型 说明
1 验团归档（GB-ADM-053） POST /v3/admin/order/group-batch/{groupBatchId}/settle 行为变更 + 新增可选请求体 须核团已核算；同事务推进核团为已验团
2 验团反确认 POST /v3/admin/order/group-batch/{groupBatchId}/settle/reopen 行为变更 同事务把核团从已验团退回已核算

三、接口详情

1. 验团归档（GB-ADM-053） POST /v3/admin/order/group-batch/{groupBatchId}/settle

VO: GroupBatchSettleReqVO（可选）→ Result<Void>

使用场景

团期详情 / 核团 Tab「验团」按钮：核对完成后归档，团期进入已验团终态。按钮建议只在 batchStatus=REVIEWING 且核团面板 auditStatus=ALLOCATED 时可点（两个状态都能从核团面板 GB-ADM-050 一次拿到）。

权限（不变）：按角色——超级管理员 / 管理员 / 财务；不看 group-batch:audit:* 权限码。团期管理员能核算但不能验团。

入参

字段 位置 类型 必填 约束 说明
groupBatchId Path Long（传字符串） ✅ 团期 ID 不变
checkNote Body String 否 ≤ 512 字 新增：验团意见；整个请求体都可以不传

出参

不变。

字段 类型 说明
data null 成功无数据；验团意见 / 验团时间在核团面板 GB-ADM-050 的 checkNote / checkedAt 里看

请求示例

POST /v3/admin/order/group-batch/2100857935637663745/settle
Authorization: Bearer <token>
Content-Type: application/json

{ "checkNote": "成本已逐项核对" }

不带意见时可以不传请求体（老前端写法照常可用）。

响应示例

（TEST 真实响应，2026-09-18，核团已核算的团期；之后核团 CHECKED、团期 SETTLED）

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

空数据 / 降级响应

写接口，无空数据形态。被拒时整笔回滚：团期状态、核团状态、验团意见都不变（TEST 已核对）。

{ "code": 589568, "message": "核团当前状态不允许该操作：当前「录入中」，需要「已核算」；请先在核团 Tab 完成核算定稿后再验团", "data": null, "success": false }

错误响应

（TEST 真实响应：核单中、但还没有核团记录的团 —— 本次行为变更的主要影响面）

{ "code": 589567, "message": "该团期尚未进入核团：尚无核团记录，请先在核团 Tab 完成核算定稿后再验团", "data": null, "success": false }
code 触发条件
589507 非超级管理员 / 管理员 / 财务（不变）
589500 团期不存在（不变）
589555 团期已验团（不变；并发时后到的一次也报这个）
589501 团期不在核单中（不变）
589567 新增：团期在核单中，但还没有核团记录
589568 新增：核团不在「已核算」（如还在录入中）
589573 新增：推进核团状态时与他人操作冲突，刷新后重试
400 checkNote 超过 512 字

业务边界

  • 判断顺序：先判权限 → 团期存在 → 团期状态（不是核单中就按原来的 589555 / 589501 报）→ 再判核团。
  • 核团已是「已验团」（极少数并发场景）时不改验团意见，交给团期状态判断。
  • 验团后核团四张表只读：保存 / 提交核算 / 重新核算都会被拒（589568），开票仍可。

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

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

使用场景

已验团的团发现有误时点「验团反确认」：团期 SETTLED → REVIEWING，同时核团 CHECKED → ALLOCATED，清空验团人、验团时间与意见（旧值写进团期时间线）。要改分摊数，再到核团 Tab 点「重新核算」（已开票的团会被拦）。

权限（不变）：超级管理员 / 管理员 / 财务。

入参

本次入参不变。

字段 位置 类型 必填 约束 说明
groupBatchId Path Long（传字符串） ✅ 团期 ID 无请求体

出参

本次出参不变。

字段 类型 说明
data null 成功无数据

请求示例

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

无请求体。

响应示例

（TEST 真实响应，2026-09-18；之后团期 REVIEWING、核团 ALLOCATED，checkNote / checkedAt 变为 null，逐户定稿保留）

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

空数据 / 降级响应

本单上线前就已验团、没有核团记录的存量团：反确认照常成功，只退团期状态，不动核团（反确认是纠错退路，不因核团数据缺失而堵死）。

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

错误响应

{ "code": 589501, "message": "团期状态不允许当前操作", "data": null, "success": false }
code 触发条件
589507 非超级管理员 / 管理员 / 财务（不变）
589500 团期不存在（不变）
589501 团期不是已验团（不变）
589573 新增：退回核团状态时与他人操作冲突

业务边界

  • 反确认后核团停在「已核算」，逐户定稿不清空；需要改数时再「重新核算」。
  • 旧的验团人、时间、意见写在团期时间线（验团事件的附加信息）里，可追溯。

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

前端需要做的

  1. 验团按钮可点条件：batchStatus === 'REVIEWING' && auditStatus === 'ALLOCATED'（取自核团面板 GB-ADM-050）。核团未定稿时置灰并提示「请先在核团 Tab 完成核算定稿」。
  2. 验团弹窗加可选「验团意见」输入框（≤512 字），作为 checkNote 提交；不填可不传 body。
  3. 589567 / 589568 直接展示后端 message（已带引导语），并引导跳到核团 Tab。
  4. 验团 / 反确认成功后刷新核团面板（核团状态会一起变）。

✅ 正确 / ❌ 错误 用法

场景 做法
✅ 验团带意见 { "checkNote": "成本已逐项核对" }
✅ 验团不带意见 不传 body，或传 {}
❌ 核团还在录入中就点验团 589568
❌ 核单中但从没打开过核团 Tab 就点验团 589567（本次新增的拒绝）
❌ 调 /audit/check 做验团 没有这个接口，验团就是 /settle

五、数据库行为

  • 无表结构变更、无 Flyway。
  • 验团成功：团期状态改为已验团；核团状态改为已验团，写验团人、验团时间、验团意见，版本 +1；团期时间线的验团事件附加记录核团迁移与验团意见。
  • 反确认成功：团期状态退回核单中；核团状态退回已核算，清空验团人、时间、意见，版本 +1；旧值写进时间线。
  • 任何一步被拒，团期与核团整笔回滚，零写入（TEST 已核对 589567 / 589568 两种拒绝后团期仍为核单中、核团行数不变）。

六、边界行为

  • 核单中 + 无核团记录 → 验团 589567（改前可以直接验团）。
  • 核单中 + 核团录入中 → 验团 589568（改前可以直接验团）。
  • 核单中 + 核团已核算 → 验团成功，核团同步变已验团。
  • 已验团 → 再点验团 589555（不变）；反确认成功，核团退回已核算。
  • 本单上线前已验团的存量团（无核团记录）→ 反确认照常成功。

六.6、修改前后对比

字段级对比

字段 改前 改后
settle 请求体 无 可选 { checkNote: String ≤512 }
settle / reopen 路径、响应 — 不变
settle 错误码 589507 / 589500 / 589555 / 589501 另加 589567 / 589568 / 589573
reopen 错误码 589507 / 589500 / 589501 另加 589573

行为级对比

行为 改前 改后
验团前置 团期在核单中即可 团期在核单中 且 核团已核算
核单中但没有核团记录的团点验团 成功归档 589567 拒绝
验团对核团的影响 无（当时还没有核团） 核团 ALLOCATED → CHECKED，同一事务
验团意见 无处填写 checkNote，在核团面板回显
反确认对核团的影响 无 核团 CHECKED → ALLOCATED，清空验团意见

六.7、影响评估

  • 是否破坏向后兼容: 结构兼容（老前端不传 body 照常可调）；行为上收紧——原来能直接验团的「核单中」团期，现在必须先完成核团定稿。
  • 存量在途团影响: TEST / 线上所有处于核单中、还没做核团的团期，验团都会被 589567 拒绝，需要运营先到核团 Tab 完成「打开面板 → 保存 → 提交核算」。上线前建议通知运营与财务。
  • 前端是否必须同步上线: 否，不改也不会出错（后端会拦并给出引导语）；但建议同步上线第四节的按钮条件与验团意见输入框，避免运营「点了才知道不行」。
  • 前端 workaround 清理点: 无。

七、不影响范围

  • 仅影响: 验团归档、验团反确认两个接口的前置与联动。
  • 零影响:
    • 发起核单 POST .../review/start（出行完毕 → 核单中）
    • 团期共享成本录入 / 列表 / 汇总
    • 订单侧第 1 层核单与财务复核
    • 验团 / 反确认的判权口径（仍是超级管理员 / 管理员 / 财务）

八、测试环境已验证

被测版本：hl-order-service-v3 = dev-v3（#7944 合并提交 db3abc6c7，其后 #7955 合并 aed07cc3c 未改这两个接口），经网关实测。

E（核单中，无核团记录）  settle        → 589567「尚无核团记录，请先在核团 Tab 完成核算定稿后再验团」；团期仍 REVIEWING、核团 0 行 ✓
B（核团录入中，无 body）  settle        → 589568「当前「录入中」，需要「已核算」…」；团期仍 REVIEWING                 ✓
A（核团录入中）           settle        → 589568；零写入                                                               ✓
A（核团已核算）           settle + checkNote → 200；核团 CHECKED、版本 7→8、checkNote 已写；团期 SETTLED；
                          时间线 BATCH_SETTLE 附核团 ALLOCATED→CHECKED                                                ✓
A（已验团）               保存 / 提交核算 / 重新核算 → 均 589568；录共享成本 → 589501                                 ✓
A（已验团）               reopen        → 200；团期 REVIEWING；核团 ALLOCATED、版本 8→9、验团人时与意见清空；
                          逐户定稿 3 户保留；时间线附旧验团人时与意见                                                  ✓

十、相关文档

  • 关联 Issue: wx/HL#7932
  • 关联 PR: wx/HL#7944
  • 同日新增接口：changelogs-v2/2026-09/18_7932_团期核团核算开票导出与节点下钻-新增接口-管理后台.md（核团 7 个接口、权限码、错误码全表）

关联 / 联系人

链接

联系人

  • 后端负责人: @jw
  • 前端负责人: @mmg
在新工单中引用 查看 Git Blame 复制永久链接