docs(changelog): #7932 团期核团 7 个新增接口与验团前置核团行为变更

Refs wx/HL#7932 Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
2026-09-18 18:12:53 +08:00
@@ -0,0 +1,328 @@
+---
+schema: "hl-changelog/v2"
+ticket: "7932"
+title: "验团归档前置核团定稿并同事务推进核团为已验团，验团反确认同步退回核团"
+consumer: "admin"
+author: "jw(GIT)"
+change_type: "修改接口"
+backend_status: "deployed"
+gateway_status: "verified"
+frontend_status: "pending"
+frontend_owner: ""
+frontend_ref: ""
+target_release: ""
+verified_at: ""
+status_note: "已上线的验团归档 POST .../settle 行为变更：核团须先提交核算（ALLOCATED）才能验团，验团同事务把核团推到已验团（CHECKED）；新增可选请求体 checkNote（验团意见）。验团反确认 POST .../settle/reopen 同事务把核团从已验团退回已核算。⚠️ 处于核单中（REVIEWING）但还没有核团记录的团，验团会返回 589567，须先在核团 Tab 完成定稿。后端 PR #7944 已合并 dev-v3 并部署 TEST。核团 7 个新接口见同日新增接口 changelog。"
+updated_at: "2026-09-18"
+base: "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` 里看 |
+
+#### 请求示例
+
+```http
+POST /v3/admin/order/group-batch/2100857935637663745/settle
+Authorization: Bearer <token>
+Content-Type: application/json
+
+{ "checkNote": "成本已逐项核对" }
+```
+
+不带意见时可以不传请求体（老前端写法照常可用）。
+
+#### 响应示例
+
+（TEST 真实响应，2026-09-18，核团已核算的团期；之后核团 `CHECKED`、团期 `SETTLED`）
+
+```json
+{ "code": 200, "message": "成功", "data": null, "success": true }
+```
+
+#### 空数据 / 降级响应
+
+写接口，无空数据形态。被拒时整笔回滚：团期状态、核团状态、验团意见都不变（TEST 已核对）。
+
+```json
+{ "code": 589568, "message": "核团当前状态不允许该操作：当前「录入中」，需要「已核算」；请先在核团 Tab 完成核算定稿后再验团", "data": null, "success": false }
+```
+
+#### 错误响应
+
+（TEST 真实响应：核单中、但还没有核团记录的团 —— **本次行为变更的主要影响面**）
+
+```json
+{ "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 | 成功无数据 |
+
+#### 请求示例
+
+```http
+POST /v3/admin/order/group-batch/2100857935637663745/settle/reopen
+Authorization: Bearer <token>
+```
+
+无请求体。
+
+#### 响应示例
+
+（TEST 真实响应，2026-09-18；之后团期 `REVIEWING`、核团 `ALLOCATED`，`checkNote` / `checkedAt` 变为 null，逐户定稿保留）
+
+```json
+{ "code": 200, "message": "成功", "data": null, "success": true }
+```
+
+#### 空数据 / 降级响应
+
+本单上线前就已验团、没有核团记录的存量团：反确认照常成功，只退团期状态，不动核团（反确认是纠错退路，不因核团数据缺失而堵死）。
+
+```json
+{ "code": 200, "message": "成功", "data": null, "success": true }
+```
+
+#### 错误响应
+
+```json
+{ "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](https://git.1814.love:8443/wx/HL/issues/7932)
+- 关联 PR: [wx/HL#7944](https://git.1814.love:8443/wx/HL/pulls/7944)
+- 同日新增接口：`changelogs-v2/2026-09/18_7932_团期核团核算开票导出与节点下钻-新增接口-管理后台.md`（核团 7 个接口、权限码、错误码全表）
+
+## 关联 / 联系人
+
+### 链接
+
+- **Issue**: [#7932](https://git.1814.love:8443/wx/HL/issues/7932)
+- **PR**: [#7944](https://git.1814.love:8443/wx/HL/pulls/7944)
+- **Merge commit**: [db3abc6c7](https://git.1814.love:8443/wx/HL/commit/db3abc6c7)
+
+### 联系人
+
+- **后端负责人**: @jw
+- **前端负责人**: @mmg