From 6c62b1aa2b52b7c62fe56e4d4c5ca202c7be72ee Mon Sep 17 00:00:00 2001
From: jw <jinwei@1814.love>
Date: Thu, 10 Sep 2026 18:10:23 +0800
Subject: [PATCH] =?UTF-8?q?docs(changelog):=20#7456=20=E5=9B=A2=E6=9C=9F?=
 =?UTF-8?q?=E7=94=9F=E5=91=BD=E5=91=A8=E6=9C=9F=E5=90=8E=E5=8D=8A=E6=AE=B5?=
 =?UTF-8?q?=E2=80=94=E2=80=94=E6=A0=B8=E5=9B=A2=E5=BC=80=E5=B7=A5=E8=87=AA?=
 =?UTF-8?q?=E5=8A=A8=E6=8E=A8=E8=BF=9B=20+=20=E9=AA=8C=E5=9B=A2=E5=BD=92?=
 =?UTF-8?q?=E6=A1=A3=20+=20=E5=8F=8D=E7=A1=AE=E8=AE=A4?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 ...Ÿç”Ÿå‘½å‘¨æœŸå�Žå�Šæ®µæ ¸å›¢éªŒå›¢-修改接å�£-管ç�†å�Žå�°.md | 348 ++++++++++++++++++
 1 file changed, 348 insertions(+)
 create mode 100644 changelogs-v2/2026-09/10_7456_团期生命周期��段核团验团-修改接�-管���.md

diff --git a/changelogs-v2/2026-09/10_7456_团期生命周期��段核团验团-修改接�-管���.md b/changelogs-v2/2026-09/10_7456_团期生命周期��段核团验团-修改接�-管���.md
new file mode 100644
index 00000000..51ad3771
--- /dev/null
+++ b/changelogs-v2/2026-09/10_7456_团期生命周期��段核团验团-修改接�-管���.md
@@ -0,0 +1,348 @@
+---
+schema: "hl-changelog/v2"
+ticket: "7456"
+title: "团期生命周期��段打通：核团开工自动推进 + 验团归档 + 验团�确认"
+consumer: "admin"
+author: "jw(GIT)"
+change_type: "修改接�"
+backend_status: "deployed"
+gateway_status: "verified"
+frontend_status: "pending"
+frontend_owner: "mmg"
+frontend_ref: ""
+target_release: ""
+verified_at: "2026-09-10"
+status_note: "团期生命周期此�在「出行完毕�之�就断了——核团（REVIEWING）与验团（SETTLED）两个状�是死枚举，全 order-v3 没有任何代�能推进到它们，看�的「核团中�「已验团�两个桶�为 0，团期共享�本录入端点因状�门写死 REVIEWING 而根本调�通。本次照订�核�范�补上两跳：① 首次录团期共享�本时把团期从「出行完毕�自动推进到「核团中�（��定时任务���日期，与订�侧 advanceSettlementReviewing �构）；② 新增验团归档端点把「核团中�推到「已验团�终�；③ 新增验团�确认端点，验错了能退回核团中。�端三�必看：① 录共享�本这个既有端点现在有了状�副作用，调用�请��团期详情刷新状�；② 验团与�确认走财务�径（超管/管�员/财务），与订�核�的 finalize/confirm �一套角色判�；③ 已验团是终�，�团�改容��录�本都会被既有状�门挡�。⚠� 已知缺�：验团�置目��校验到「状�是 REVIEWING�，原型�求的「核团�交��赖尚未建的核团四表（GB-ADM-050~052），在那之�验团�能在�本没录完时被点掉，�确认端点兜�一部分。无表�更�无 Flyway，新增错误� 589555。"
+updated_at: "2026-09-10"
+base: "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 | 无返回体；状��化请��团期详情 |
+
+#### 请求示例
+
+```http
+POST /v3/admin/order/group-batch/2089713777065832450/settle
+Authorization: Bearer <admin token>
+```
+
+#### �应示例
+
+```json
+{ "code": 200, "message": "�功", "data": null, "success": true }
+```
+
+#### 空数� / �级�应
+
+写�，无空数�形�。团期�存在报 `589500`。
+**验团时间��新列**——`order_group_batch` 没有 `settled_at`（那是 `order_main` 的列），
+验团时间从 `GET .../status-logs` 里 `BATCH_SETTLE`「验团结算�那�的 `changedAt` 读，`#7304` 已开了这个读端点。
+
+#### 错误�应
+
+团期已验团归档，��调用：
+
+```json
+{ "code": 589555, "message": "该团期已验团归档，����验团", "data": null, "success": false }
+```
+
+团期状��是「核团中�：
+
+```json
+{ "code": 589501, "message": "团期状���许当��作", "data": null, "success": false }
+```
+
+无��（�超管 / 管�员 / 财务）：
+
+```json
+{ "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 | 无返回体；状��化请��团期详情 |
+
+#### 请求示例
+
+```http
+POST /v3/admin/order/group-batch/2089713777065832450/settle/reopen
+Authorization: Bearer <admin token>
+```
+
+#### �应示例
+
+```json
+{ "code": 200, "message": "�功", "data": null, "success": true }
+```
+
+#### 空数� / �级�应
+
+写�，无空数�形�。团期�存在报 `589500`。
+
+#### 错误�应
+
+团期�是「已验团�状�（比如已�被别人退回过）：
+
+```json
+{ "code": 589501, "message": "团期状���许当��作", "data": null, "success": false }
+```
+
+无��：
+
+```json
+{ "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（雪花，按字符串下�） |
+
+#### 请求示例
+
+```http
+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":"大巴费用"}
+```
+
+#### �应示例
+
+```json
+{ "code": 200, "message": "�功", "data": "2097990074078580737", "success": true }
+```
+
+#### 空数� / �级�应
+
+写�，无空数�形�。**入��出��既有错误�本次一律未�**，�的�是状�副作用。
+
+#### 错误�应
+
+团期既�是「出行完毕�也�是「核团中�：
+
+```json
+{ "code": 589501, "message": "团期状���许当��作", "data": null, "success": false }
+```
+
+无��（该端点走 `group-batch:finance:advance`，#7411 已接）：
+
+```json
+{ "code": 589507, "message": "无�作��（�团期管�员 / �本定制师�下）", "data": null, "success": false }
+```
+
+#### 业务边界
+
+- **新增副作用**：团期处于 `TRIP_FINISHED`（出行完毕）时，本端点会**先把它 CAS 推进到 `REVIEWING`**（核团中），
+  �执行原有的�本录入。�事务写 `BATCH_TRIP_END`「返团核团�时间线。
+- 团期已在 `REVIEWING` 时���推进����写时间线（幂等）。
+- **推进��定时任务���日期**——与订�侧「第一次录核�明细自动把订�从待核�转�核�中��字�构。
+- ⚠� **�端请注�**：调用�功�团期状��能已��了，**请��团期详情刷新状�与按钮�用性**。
+- 已验团（`SETTLED`）的团期调本端点报 `589501`，�会被带回核团中（有�测钉�）。
+
+## 四�契约约�与正确调用方�
+
+1. **录共享�本之����团期详情**。它现在有状�副作用，页�上的阶段��按钮�用性都会�。
+2. **验团 / �确认走财务�径**：超管 / 管�员 / 财务，与订�核�的 `finalize` / `confirm` �一套角色判�。
+   定制师�房务�车务等角色会拿到 `589507`。
+3. **验团时间��找 `settled_at` 字段**——团期表没有这一列。从 `GET .../status-logs` 里
+   `BATCH_SETTLE` 那�的 `changedAt` 读。
+4. **已验团是终�**：�团 `589544`�改容� `589538`�录�本 `589501`。界�上这些按钮应当置�。
+5. **`589555` 是「已验团归档，����验团�**，与 `589501`「状���许�分开——�者告诉用户「已��过了�，
+   �者告诉用户「现在这个阶段��了�，�示文案建议区分。
+6. **雪花 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