changelog(7188,7190): 团期看板 batchLabel 序号透出（PR #7209）+ 团期九态/八桶与出行完毕自动推进（PR #7212），均已部署 dev-v3 网关复测

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01N7Xpgcv9nncadAXQtWhg4P
2026-09-06 21:51:08 +08:00
@@ -0,0 +1,458 @@
+---
+schema: "hl-changelog/v2"
+ticket: "7188"
+title: "团期看板/列表/详情透出「第N期」班期序号 batchLabel"
+consumer: "admin"
+author: "wx(GIT)"
+change_type: "修改接口"
+backend_status: "deployed"
+gateway_status: "verified"
+frontend_status: "pending"
+frontend_owner: ""
+frontend_ref: ""
+target_release: ""
+verified_at: "2026-09-06"
+updated_at: "2026-09-06"
+base: "dev-v3"
+status_note: "后端已合并（PR #7209，合并提交 a5eacefd）并于 2026-09-06 21:19-21:22 部署测试服 dev-v3（product-v2 + order-v3），网关复测 6/6 通过；前端把看板行标题改成「第{batchLabel}期 {batchName}」，batchLabel 为空时退回只显 batchName。"
+---
+
+# 团期模块：看板 / 列表 / 详情透出「第N期」班期序号
+
+## ⚠️ 关键变化
+
+- 三个团期接口新增 / 修正字段 **`batchLabel`**（String，班期序号，如 `"7"`）：product 侧按同产品全部班期**出发日期升序位置 = 下标 + 1** 实时重算（不信存储列，删班期后自愈；同日期同排序值按 batchId 兜底），经内部接口透传到 order-v3。
+- **前端行标题改为「第{batchLabel}期 {batchName}」**（hl-ui `src/views/order-v2/batch/components/PeriodRow.vue:164-171` `title` computed 目前只显 `batchName`），`batchLabel` 为空时退回只显 `batchName`——存量团期在下一次该班期下单前分页/详情里是 null，必须兜底。
+- 班期名口径：product 保存与 order 快照两侧 **trim**；新增/编辑班期名为空白 → 回退班期编号 `batchNo`；编辑不传 `batchName` → 保留旧名。现场「 没，那你」（前导空格）这类脏名下单后自愈。
+- 分页项（GB-ADM-001）本单取快照值；#7189 合入后分页改以产品全班期为基底、`batchLabel` 取 product 实时值，**字段名不变**。
+
+---
+
+## 一、背景
+
+### 现象
+
+wx 2026-09-06 看测试服「团期订单」看板：行标题显示班期名「没，那你」，期望「第7期 没，那你」（该班期是产品「冻干粉发短信给」按出发日的第 7 期）。序号只存在于 product 管理端班期列表，Feign 契约与团期三个响应 VO 都没有，`order_group_batch.batch_label` 列从未被写入。
+
+### 调用链
+
+1. hl-ui `src/stores/orderV2Batch.js:93-97` `getGroupBatchPage()` → `GET /v3/admin/order/group-batch`（GB-ADM-001）→ `records[].batchLabel`（快照）
+2. 看板合并层 `GET /v3/admin/order/group-batch/board` → order-v3 Feign `GET /internal/product/group/{productId}/detail` → product `GroupTourBatchService.getBatchCalendarByProductId` 逐项 `batchLabel = 位置 + 1` → 命中/未建团行实时值、孤儿行快照
+3. 团期详情 `GET /v3/admin/order/group-batch/{groupBatchId}`（GB-ADM-002）→ `batchLabel` 快照
+4. 快照写入：GROUP 创单建团时 `GroupBatchService.buildGroupBatchDO` 从 `GET /internal/product/batch/{batchId}/info` 的 `batchLabel` 写 `batch_label`；此后每次该班期下单 `refreshSnapshot` 同步刷新序号 / 班期名 / 产品名 / 出发日 / 返团日 / 报名截止日六列
+
+### 地面真相（测试服 dev-v3 a5eacefd，2026-09-06 21:2x，产品 2044306857534636034，班期 2026-10-01 productBatchId=2052935476557328386，团期 2096412454643802114）
+
+| 接口 | 结果 |
+|---|---|
+| board | 7 行按出发日升序 `batchLabel` = "1"(06-04) "2"(07-03) "3"(07-10) "4"(07-17) "5"(07-24) "6"(07-31) "7"(10-01)；06-04 期存储列是 "6" 却回 "1"，10-01 期回 "7" ✓ 按位置实时重算 |
+| 分页 / 详情（刷新前） | `batchLabel` 字段存在、值 null（存量团期） |
+| 分页 / 详情（在该班期新下一单后，测完已取消） | 详情 `batchLabel="7"`、分页项 `batchLabel="7"`、`batchName="没，那你"`（前导空格已 trim） |
+
+---
+
+## 二、变更接口清单
+
+| # | 接口 | 方法 | 路径 | 变更类型 | 说明 |
+|---|------|------|------|----------|------|
+| 1 | 团期看板分页（GB-ADM-001） | GET | `/v3/admin/order/group-batch` | 响应新增字段 | `records[].batchLabel`（快照；存量团期下单前为 null） |
+| 2 | 团期看板合并层列表 | GET | `/v3/admin/order/group-batch/board` | 响应新增字段 | 每项 `batchLabel`：命中/未建团行取 product 实时值，孤儿行取快照 |
+| 3 | 团期详情（GB-ADM-002） | GET | `/v3/admin/order/group-batch/{groupBatchId}` | 响应字段语义修正 | 既有字段 `batchLabel` 由恒 null 改为班期序号快照 |
+
+---
+
+## 三、接口详情
+
+### 1. 团期看板分页 `GET /v3/admin/order/group-batch`
+
+**VO**: `GroupBatchListReqVO → Result<PageResult<GroupBatchPageItemRespVO>>`
+
+#### 使用场景
+
+团期看板列表；行标题用 `batchLabel` + `batchName` 拼「第N期 名称」。
+
+#### 入参
+
+| 字段 | 位置 | 类型 | 必填 | 约束 | 说明 |
+|------|------|------|------|------|------|
+| productId | query | Long(字符串) | 否 | 雪花 ID | 按产品筛选 |
+| opsStage | query | String | 否 | RECRUIT / FORMED / PENDING_TRIP / TRAVELLING / TRIP_FINISHED / AUDITING / CHECKED / DISBANDED | 桶筛选（不变） |
+| month | query | String | 否 | yyyy-MM | 出发月份 |
+| keyword | query | String | 否 | 已转义 | 班期编号 / 名称模糊 |
+| batchStatus | query | String | 否 | 团期状态码 | 可选 |
+| deadlineFrom / deadlineTo | query | String | 否 | yyyy-MM-dd | 报名截止日区间 |
+| pageNo | query | Integer | 否 | 默认 1 | 页码 |
+| pageSize | query | Integer | 否 | 默认 20，最大 100 | 每页条数 |
+
+#### 出参 `Result<PageResult<GroupBatchPageItemRespVO>>`
+
+| 字段 | 类型 | 说明 |
+|------|------|------|
+| data.records[] | Array | 团期行（分页容器 `records / total / page / pageSize`） |
+| data.records[].batchLabel | String | **新增**。班期序号快照（`order_group_batch.batch_label`）：建团写入、每次该班期下单刷新；存量团期在下一次下单前为 null；#7189 起改取 product 实时值 |
+| data.records[].batchName | String | 班期名（快照，下单刷新时已 trim） |
+| data.records[].batchNo | String | 班期编号 |
+| 其余字段 | — | 不变（groupBatchId / productBatchId / productId / productName / batchStatus / batchStatusName / minGroupPeople / maxRooms / maxParticipants / enrolledPeople / enrolledRooms / remainRooms / remainParticipants / orderCount / enrollDeadline / departDate / endDate / receivableAmount / receivedAmount / chips） |
+
+#### 请求示例
+
+```http
+GET /v3/admin/order/group-batch?productId=2044306857534636034&pageNo=1&pageSize=50 HTTP/1.1
+Host: api.test.1814.love:9443
+Authorization: Bearer <token>
+```
+
+#### 响应示例
+
+在该班期下单刷新快照后实测（2026-09-06 21:2x，非相关字段略）：
+
+```json
+{
+  "code": 200,
+  "message": "成功",
+  "data": {
+    "records": [
+      {
+        "groupBatchId": "2096412454643802114",
+        "productBatchId": "2052935476557328386",
+        "productId": "2044306857534636034",
+        "batchNo": "Q202610012052935476548939777",
+        "batchName": "没，那你",
+        "batchLabel": "7",
+        "batchStatus": "RESOURCE_PREPARING",
+        "batchStatusName": "资源准备中",
+        "departDate": "2026-10-01",
+        "endDate": "2026-10-03"
+      }
+    ],
+    "total": 1,
+    "page": 1,
+    "pageSize": 50
+  },
+  "success": true
+}
+```
+
+#### 空数据 / 降级响应
+
+存量团期在下一次该班期下单前 `batchLabel` 为 null（不是缺字段），前端退回只显 `batchName`；无命中团期时 `records` 为空数组。
+
+```json
+{
+  "code": 200,
+  "message": "成功",
+  "data": {
+    "records": [
+      { "groupBatchId": "2096412454643802114", "batchName": "没，那你", "batchLabel": null }
+    ],
+    "total": 1,
+    "page": 1,
+    "pageSize": 50
+  },
+  "success": true
+}
+```
+
+#### 错误响应
+
+```json
+{
+  "code": 589507,
+  "message": "无操作权限（非团期管理员 / 非本定制师名下）",
+  "data": null,
+  "success": false
+}
+```
+
+HTTP 始终 200，按 `code` 判断。
+
+#### 业务边界
+
+- 权限 `group-batch:view`
+- `batchLabel` 是数字字符串（`"7"`），后端不拼「第N期」文案，前端拼
+- 序号会随 product 侧增删班期漂移，快照只在下单时刷新；需要绝对实时以 board / #7189 后的分页为准
+
+### 2. 团期看板合并层列表 `GET /v3/admin/order/group-batch/board`
+
+**VO**: `Result<List<GroupBatchBoardItemRespVO>>`（查询参数 productId，无请求 VO）
+
+#### 使用场景
+
+以产品全部班期为基底的看板（命中 / 未建团 / 孤儿三类行）；hl-ui 当前未调用，#7189 后分页也走同一合并基底。
+
+#### 入参
+
+| 字段 | 位置 | 类型 | 必填 | 约束 | 说明 |
+|------|------|------|------|------|------|
+| productId | query | Long(字符串) | 是 | 雪花 ID | 产品 ID |
+
+#### 出参 `Result<List<GroupBatchBoardItemRespVO>>`
+
+| 字段 | 类型 | 说明 |
+|------|------|------|
+| data[].batchLabel | String | **新增**。命中行 / 未建团行 = product 实时序号；孤儿行（product 已删该班期）= 快照，可能 null |
+| data[].productBatchId / productId / batchNo / batchName | String | 不变 |
+| data[].departureDate / endDate / enrollmentDeadline | String(yyyy-MM-dd) | 不变（product 实时） |
+| data[].groupBatchId | String(Long) | 未建团行为 null（不变） |
+| 其余字段 | — | 不变（maxRooms / maxParticipants / enrolledRooms / enrolledPeople / remainRooms / remainParticipants / batchStatus / batchStatusLabel / hotelReady / vehicleReady / guideReady / photographerReady / needsGuide / needsPhotographer / orderCount / productBatchRemoved / contractSignedCount / insuranceInsuredCount） |
+
+#### 请求示例
+
+```http
+GET /v3/admin/order/group-batch/board?productId=2044306857534636034 HTTP/1.1
+Host: api.test.1814.love:9443
+Authorization: Bearer <token>
+```
+
+#### 响应示例
+
+实测（2026-09-06 21:2x，只列序号相关字段，共 7 行）：
+
+```json
+{
+  "code": 200,
+  "message": "成功",
+  "data": [
+    { "productBatchId": "2045498872326717442", "departureDate": "2026-06-04", "batchName": "fadege", "batchLabel": "1", "groupBatchId": null },
+    { "productBatchId": "2045401225930690562", "departureDate": "2026-07-03", "batchLabel": "2", "groupBatchId": null },
+    { "productBatchId": "2045401225960050689", "departureDate": "2026-07-10", "batchLabel": "3", "groupBatchId": null },
+    { "productBatchId": "2045401225964244993", "departureDate": "2026-07-17", "batchLabel": "4", "groupBatchId": null },
+    { "productBatchId": "2045401225972633601", "departureDate": "2026-07-24", "batchLabel": "5", "groupBatchId": null },
+    { "productBatchId": "2045401225976827906", "departureDate": "2026-07-31", "batchLabel": "6", "groupBatchId": null },
+    { "productBatchId": "2052935476557328386", "departureDate": "2026-10-01", "batchName": " 没，那你", "batchLabel": "7", "groupBatchId": "2096412454643802114" }
+  ],
+  "success": true
+}
+```
+
+#### 空数据 / 降级响应
+
+产品无班期时 `data` 为空数组；孤儿行 `batchLabel` 可能为 null。
+
+```json
+{
+  "code": 200,
+  "message": "成功",
+  "data": [],
+  "success": true
+}
+```
+
+#### 错误响应
+
+```json
+{
+  "code": 589515,
+  "message": "获取团期产品列表失败，请稍后重试",
+  "data": null,
+  "success": false
+}
+```
+
+另：`589507` 无操作权限。
+
+#### 业务边界
+
+- 序号按 product 当前全部未删班期的出发日升序位置计算（同日期按 sortOrder、再按 batchId）；软删的班期不占位
+- 未建团行的 `batchName` 取 product 侧当前值（可能未 trim，如示例第 7 行前导空格），命中行分页/详情取快照（已 trim）
+
+### 3. 团期详情 `GET /v3/admin/order/group-batch/{groupBatchId}`
+
+**VO**: `Result<GroupBatchDetailRespVO>`（路径参数，无请求 VO）
+
+#### 使用场景
+
+团期详情页头部；`batchLabel` 语义修正为班期序号快照。
+
+#### 入参
+
+| 字段 | 位置 | 类型 | 必填 | 约束 | 说明 |
+|------|------|------|------|------|------|
+| groupBatchId | path | Long(字符串) | 是 | 团期主订单 ID | 不是 productBatchId |
+
+#### 出参 `Result<GroupBatchDetailRespVO>`
+
+| 字段 | 类型 | 说明 |
+|------|------|------|
+| data.batchLabel | String | **语义修正**：改前恒 null（列从未写入，文案「班期标签快照 example=主推」）；改后 = 班期序号快照（建团写入、下单刷新），文案「班期序号（第N期）快照 example=7」 |
+| data.batchName | String | 班期名快照（下单刷新时已 trim） |
+| 其余字段 | — | 不变 |
+
+#### 请求示例
+
+```http
+GET /v3/admin/order/group-batch/2096412454643802114 HTTP/1.1
+Host: api.test.1814.love:9443
+Authorization: Bearer <token>
+```
+
+#### 响应示例
+
+刷新快照后实测（非相关字段略）：
+
+```json
+{
+  "code": 200,
+  "message": "成功",
+  "data": {
+    "groupBatchId": "2096412454643802114",
+    "productBatchId": "2052935476557328386",
+    "batchNo": "Q202610012052935476548939777",
+    "batchName": "没，那你",
+    "batchLabel": "7",
+    "batchStatus": "RESOURCE_PREPARING",
+    "departDate": "2026-10-01",
+    "endDate": "2026-10-03"
+  },
+  "success": true
+}
+```
+
+#### 空数据 / 降级响应
+
+存量团期下单刷新前 `batchLabel` 为 null；前端退回只显 `batchName`。
+
+```json
+{
+  "code": 200,
+  "message": "成功",
+  "data": { "groupBatchId": "2096412454643802114", "batchName": "没，那你", "batchLabel": null },
+  "success": true
+}
+```
+
+#### 错误响应
+
+```json
+{
+  "code": 589500,
+  "message": "团期不存在",
+  "data": null,
+  "success": false
+}
+```
+
+#### 业务边界
+
+- 同 GB-ADM-001：数字字符串、快照语义、null 兜底
+
+---
+
+## 四、契约约束与正确调用方式
+
+> 三个接口均为只读 GET；本节写的是**前端消费 `batchLabel` 的规则**。
+
+### ✅ 正确 / ❌ 错误 payload 对照
+
+| 场景 | payload / 处理 |
+|------|---------|
+| ✅ 行标题 | `row.batchLabel ? \`第${row.batchLabel}期 ${row.batchName}\` : row.batchName` |
+| ✅ 徽标 / 导出用序号 | 直接用 `batchLabel` 字符串，不要自己按行下标算 |
+| ❌ 把 `batchLabel` 当数字做算术或排序键 | 它是字符串，且随 product 增删班期漂移；排序用 `departDate` |
+| ❌ 不兜底 null | 存量团期分页/详情在下单刷新前为 null，会渲染成「第undefined期」 |
+
+### 切换状态时的必要动作
+
+无写接口。序号变化来自 product 侧班期增删/改期，看板刷新即可。
+
+---
+
+## 五、数据库行为
+
+无表变更、无 Flyway。`order_group_batch.batch_label VARCHAR(64)` 列早已存在，本单开始写入：
+
+| 时点 | 写入 |
+|------|------|
+| GROUP 首单建团 | `batch_label` = product `GET /internal/product/batch/{batchId}/info` 的 `batchLabel`；`batch_name` trim |
+| 该班期每次下单 | `refreshSnapshot` 非 null 且变化才更新：`product_name / batch_name / batch_label / depart_date / end_date / enroll_deadline` |
+
+product 侧 `group_tour_batch.batch_label` 存储列不再作为读源（脏值如 06-04 期存 "6" 不影响输出）；`batch_name` 保存时 trim，空白回退 `batch_no`。
+
+---
+
+## 六、边界行为
+
+- 未登录 → 网关 401；无权限 → `589507`
+- 团期不存在 → `589500`；board 拉产品失败 → `589515`
+- product 定位不到该班期（理论不会）→ `batchLabel` null 并记 WARN，不报错
+- 产品下只有一期 → `batchLabel="1"`
+- 下单时 product 回传日期串非法 → 刷新跳过该列并记 WARN，不影响下单
+
+## 六.5、枚举 / 数据字典
+
+无新增枚举；`batchLabel` 为自由数字字符串。
+
+## 六.6、修改前后对比
+
+### 字段级对比
+
+| 字段 | 修改前 | 修改后 |
+|------|--------|--------|
+| GB-ADM-001 `records[].batchLabel` | 无 | 新增（快照） |
+| board `data[].batchLabel` | 无 | 新增（实时 / 孤儿行快照） |
+| GB-ADM-002 `data.batchLabel` | 存在但恒 null | 班期序号快照 |
+| product `GET /internal/product/batch/{batchId}/info` `batchLabel` | 无 | 新增（内部接口，前端不直接调） |
+
+### 行为级对比
+
+| 场景 | 修改前 | 修改后 |
+|------|--------|--------|
+| 看板行标题 | 只有班期名 | 「第7期 没，那你」（前端拼） |
+| 班期名带前后空格 | 原样落库、原样显示 | 保存 / 快照两侧 trim |
+| 新增或编辑班期名为空白 | 新增回退 batchNo，编辑可能落 null | 两条路径都回退 `batchNo` |
+| 编辑不传 batchName | 保留旧名 | 保留旧名（不变） |
+
+## 六.7、影响评估
+
+- 向后兼容：只加字段 / 修正语义，老前端不改不报错
+- 前端是否必须同步上线：否；但不改则标题仍无序号
+- 数据：无表变更；存量 `batch_label` 不回填，随下单自愈
+
+---
+
+## 七、不影响范围
+
+- **仅影响**: 团期看板行标题、团期详情头部、board 合并层
+- **零影响**:
+  - 创单 / 报价接口契约（`POST /v3/admin/order` 入参出参不变）
+  - product 管理端班期列表（已是同一序号口径）
+  - 芯片、桶、状态机
+  - 小程序
+
+---
+
+## 八、测试环境已验证
+
+真实接口输出（测试服 api.test.1814.love，2026-09-06 21:2x，登录后切 ADMIN 角色）：
+
+```
+GET /v3/admin/order/group-batch/board?productId=2044306857534636034            → 200, 7 行 batchLabel 1..7 按出发日升序，10-01 期 "7" ✓
+GET /v3/admin/order/group-batch?productId=2044306857534636034&pageSize=50      → 200, 存量行 batchLabel 字段存在=null ✓
+GET /v3/admin/order/group-batch/2096412454643802114                            → 200, batchLabel 字段存在=null ✓
+POST /v3/admin/order（该班期新下一单，测完取消）                                 → 200, 触发 refreshSnapshot ✓
+GET /v3/admin/order/group-batch/2096412454643802114                            → batchLabel="7", batchName="没，那你" ✓
+GET /v3/admin/order/group-batch?productId=2044306857534636034&pageSize=50      → 该行 batchLabel="7" ✓
+```
+
+验证产品: `productId=2044306857534636034`（冻干粉发短信给），班期 `productBatchId=2052935476557328386`（2026-10-01），团期 `groupBatchId=2096412454643802114`。单测：product `GroupTourBatchServiceTest` 3/0、`GroupTourBatchMapperTest` 2/0（ORDER BY 三键，变异验证）、`GroupBatchLabelResolverTest` 6/0、`InternalProductServiceTest` 7/0、`ProductPricingServiceTest` 97/0；order `GroupBatchServiceTest` 73/0、`GroupBatchConverterTest` 37/0、`BatchInfoVODeserializationTest` 4/0、ArchTest 41/0；合入后 dev-v3 HEAD 全量 product-v2 1550/0、order-v3 8726/0。部署：Deploy Panel 21:19-21:22 product-v2 与 order-v3 双实例滚动完成，分支 dev-v3。
+
+---
+
+## 十、相关文档
+
+- 关联 Issue: [wx/HL#7188](https://git.1814.love:8443/wx/HL/issues/7188)
+- 关联 PR: [wx/HL#7209](https://git.1814.love:8443/wx/HL/pulls/7209)
+- 同现场: #7189（看板以产品全班期为基底 + 班期范围筛选，分页 batchLabel 改实时值）、#7190（「出行完毕」状态与八桶）、#7204（导/摄芯片零指派口径）
+- 前端缺陷 changelog: `06_frontend_团期看板展开行子订单列表恒空-前端缺陷-管理后台.md`
+
+## 关联 / 联系人
+
+### 链接
+
+- **Issue**: [#7188](https://git.1814.love:8443/wx/HL/issues/7188)
+- **PR**: [#7209](https://git.1814.love:8443/wx/HL/pulls/7209)
+- **Merge commit**: [a5eacefd](https://git.1814.love:8443/wx/HL/commit/a5eacefdb270b2f783db95afc790c9d0eb65a8da)
+
+### 联系人
+
+- **后端负责人**: @wx
@@ -0,0 +1,458 @@
+---
+schema: "hl-changelog/v2"
+ticket: "7190"
+title: "团期状态新增「出行完毕」TRIP_FINISHED，看板七桶扩八桶"
+consumer: "admin"
+author: "wx(GIT)"
+change_type: "修改接口"
+backend_status: "deployed"
+gateway_status: "verified"
+frontend_status: "pending"
+frontend_owner: ""
+frontend_ref: ""
+target_release: ""
+verified_at: "2026-09-06"
+updated_at: "2026-09-06"
+base: "dev-v3"
+status_note: "后端已合并（PR #7212，合并提交 ccb4d8fd）并于 2026-09-06 21:20-21:22 部署测试服 dev-v3（order-v3 + user-service），网关复测通过（八桶键序、opsStage=TRIP_FINISHED 筛选、job 推进）；前端 batchLifecycle.js 桶表/页签/状态映射加 TRIP_FINISHED；两个自动推进 sys_job 保持 PAUSED。"
+---
+
+# 团期模块：状态九态（新增「出行完毕」）与看板八桶
+
+## ⚠️ 关键变化
+
+- **团期状态 8 → 9 态**：新增 `TRIP_FINISHED`「出行完毕」，位于 `TRAVELLING`「出行中」之后、`REVIEWING`「核单中」之前。九态与中文名：`RECRUITING` 招募中 / `RESOURCE_PREPARING` 资源准备中 / `MATERIAL_PREPARING` 物料准备中 / `PENDING_DEPARTURE` 待出发 / `TRAVELLING` 出行中 / **`TRIP_FINISHED` 出行完毕** / `REVIEWING` 核单中 / `SETTLED` 已结算 / `CANCELLED` 已取消。
+- **看板运营阶段 7 桶 → 8 桶**：新增桶 `TRIP_FINISHED`「出行完毕」，位于 `TRAVELLING` 之后、`AUDITING` 之前。八桶顺序：`RECRUIT, FORMED, PENDING_TRIP, TRAVELLING, TRIP_FINISHED, AUDITING, CHECKED, DISBANDED`。GB-ADM-009 统计条 `buckets` 固定键由 7 个变 8 个；GB-ADM-001 / GB-ADM-008 的 `opsStage` 多一个可选值。
+- **推进由两个定时任务按日自动完成**（出发日 ≤ 今天：待出发 → 出行中；返团日 < 今天：出行中 → 出行完毕；日期取 product 侧实时班期日期，不取团期快照）。**上线时两个 sys_job 为 PAUSED，「出行完毕 → 核单中」发起核单入口落地前不会 resume**，所以近期页面上不会自然出现该态，但契约已变，前端要先把桶/页签/映射补齐，否则出现时页签少一个、桶键被忽略。
+- 联动：出行完毕团期的房/车/导/摄芯片恒 `DONE`（与已返团同硬规则）；对其子订单退团被拒 `589501`；预支入口在该态仍开放；转期/调容量/需求提报按既有规则在该态均拒。
+
+---
+
+## 一、背景
+
+### 现象
+
+wx 2026-09-06 要求看板状态页签在「出行中」后增加「出行完毕」。排查发现团期八态的后半段（待出发 → 出行中 → 核单中 → 已结算）此前没有任何代码推进（订单级有按日期推进的 job，团期级没有），测试库全部团期都停在已成团。本单新增正式状态并补齐团期级按日推进。
+
+### 调用链
+
+1. hl-user-service sys_job（Quartz）`groupBatchLifecycleJob.processDepartures() / processTripFinishes()` → 桥接 bean 经 Feign → order-v3 `POST /v3/internal/jobs/group-batch-departure/run`、`/group-batch-trip-finish/run`（内部端点，网关不开放）
+2. order-v3 `GroupBatchLifecycleJobService`：取候选（`PENDING_DEPARTURE` / `TRAVELLING`）→ 按产品经 Feign 取 product 实时班期日期 → `GroupBatchLifecycleTxService.advanceOne` 同一事务 CAS 改状态 + 写时间线（`BATCH_DEPART`「系统自动发团」/ 新事件 `BATCH_TRIP_FINISH`「系统自动出行完毕」）
+3. 看板读侧：`GroupBatchStageBuckets` 九态折叠八桶 → GB-ADM-001 `records[].batchStatus / batchStatusName`、GB-ADM-009 `buckets`、GB-ADM-008 导出 `opsStage`
+
+### 地面真相（测试服 dev-v3，2026-09-06 21:38-21:42，团期房务会话临时造数）
+
+| 团期 | 造数 | 触发 job 后 | 说明 |
+|---|---|---|---|
+| A `2096495107078328322`（#7158验收班期） | 状态 → PENDING_DEPARTURE；product 侧出发日 12-20 → 09-05；order 快照出发日仍 12-20 | 第一轮（出发日 12-20，未来）不动；第二轮（09-05）→ **TRAVELLING** | 读 product 实时日期，快照未动 |
+| B `2096510069465088002`（#7178验收班期） | 状态 → TRAVELLING；product 侧返团日 12-28 → 09-05；order 快照返团日仍 12-27 | 第一轮不动；第二轮 → **TRIP_FINISHED**「出行完毕」 | 同上 |
+
+两轮 sys_job 1041 / 1042 执行日志均 SUCCESS（毫秒级）。造数已由团期房务会话复原。
+
+---
+
+## 二、变更接口清单
+
+| # | 接口 | 方法 | 路径 | 变更类型 | 说明 |
+|---|------|------|------|----------|------|
+| 1 | 团期看板分页（GB-ADM-001） | GET | `/v3/admin/order/group-batch` | 入参枚举扩展 + 响应取值扩展 | `opsStage` / `batchStatus` 新增 `TRIP_FINISHED`；`records[].batchStatus` 可为 `TRIP_FINISHED`、`batchStatusName="出行完毕"` |
+| 2 | 团期看板统计条（GB-ADM-009） | GET | `/v3/admin/order/group-batch/summary` | 响应结构扩展 | `buckets` 固定键 7 → 8，新增 `TRIP_FINISHED`，`total` = 八桶之和 |
+| 3 | 团期看板导出（GB-ADM-008） | GET | `/v3/admin/order/group-batch/export` | 入参枚举扩展 | `opsStage` 新增 `TRIP_FINISHED` |
+
+---
+
+## 三、接口详情
+
+### 1. 团期看板分页 `GET /v3/admin/order/group-batch`
+
+**VO**: `GroupBatchListReqVO → Result<PageResult<GroupBatchPageItemRespVO>>`
+
+#### 使用场景
+
+团期看板列表（hl-ui `src/stores/orderV2Batch.js:93-97` `getGroupBatchPage()`）；点「出行完毕」页签时传 `opsStage=TRIP_FINISHED`。
+
+#### 入参
+
+| 字段 | 位置 | 类型 | 必填 | 约束 | 说明 |
+|------|------|------|------|------|------|
+| productId | query | Long(字符串) | 否 | 雪花 ID | 按产品筛选 |
+| opsStage | query | String | 否 | `RECRUIT / FORMED / PENDING_TRIP / TRAVELLING / TRIP_FINISHED / AUDITING / CHECKED / DISBANDED` | **新增 `TRIP_FINISHED`**；非法值忽略不报错 |
+| batchStatus | query | String | 否 | 九态之一 | **可传 `TRIP_FINISHED`** |
+| month | query | String | 否 | yyyy-MM | 出发月份 |
+| keyword | query | String | 否 | 已转义 | 班期编号 / 名称模糊 |
+| deadlineFrom / deadlineTo | query | String | 否 | yyyy-MM-dd | 报名截止日区间 |
+| pageNo | query | Integer | 否 | 默认 1 | 页码 |
+| pageSize | query | Integer | 否 | 默认 20，最大 100 | 每页条数 |
+
+#### 出参 `Result<PageResult<GroupBatchPageItemRespVO>>`
+
+| 字段 | 类型 | 说明 |
+|------|------|------|
+| data.records[] | Array | 团期行（分页容器 `records / total / page / pageSize`） |
+| data.records[].groupBatchId | String(Long) | 团期主订单 ID |
+| data.records[].batchStatus | String | 九态之一，**可为 `TRIP_FINISHED`** |
+| data.records[].batchStatusName | String | 中文名，`TRIP_FINISHED` 对应「出行完毕」 |
+| data.records[].chips | Object | 六芯片；`TRIP_FINISHED` 团期房/车/导/摄恒 `DONE`（硬规则，与已返团同） |
+| 其余字段 | — | 不变（productBatchId / productId / productName / batchNo / batchName / batchLabel / maxRooms / maxParticipants / enrolledPeople / enrolledRooms / remainRooms / remainParticipants / orderCount / enrollDeadline / departDate / endDate / receivableAmount / receivedAmount） |
+
+#### 请求示例
+
+```http
+GET /v3/admin/order/group-batch?productId=2056947670512971778&opsStage=TRIP_FINISHED&pageSize=10 HTTP/1.1
+Host: api.test.1814.love:9443
+Authorization: Bearer <token>
+```
+
+#### 响应示例
+
+第二轮造数后实测（2026-09-06 21:42）：
+
+```json
+{
+  "code": 200,
+  "message": "成功",
+  "data": {
+    "records": [
+      {
+        "groupBatchId": "2096510069465088002",
+        "productId": "2056947670512971778",
+        "productName": "测试小蒙马-多档-固定金额",
+        "batchName": "#7178验收班期",
+        "batchStatus": "TRIP_FINISHED",
+        "batchStatusName": "出行完毕",
+        "orderCount": 1,
+        "departDate": "2026-12-27",
+        "endDate": "2026-12-28"
+      }
+    ],
+    "total": 1,
+    "page": 1,
+    "pageSize": 10
+  },
+  "success": true
+}
+```
+
+#### 空数据 / 降级响应
+
+`opsStage=TRIP_FINISHED` 在 sys_job 未 resume 期间通常无命中：`records` 为空数组、`total=0`，不是错误。
+
+```json
+{
+  "code": 200,
+  "message": "成功",
+  "data": { "records": [], "total": 0, "page": 1, "pageSize": 20 },
+  "success": true
+}
+```
+
+#### 错误响应
+
+```json
+{
+  "code": 589507,
+  "message": "无操作权限（非团期管理员 / 非本定制师名下）",
+  "data": null,
+  "success": false
+}
+```
+
+#### 业务边界
+
+- `opsStage` 与 `batchStatus` 的映射：`TRIP_FINISHED` 桶 = `TRIP_FINISHED` 态（单射，不是复合桶；`FORMED` 仍是 RESOURCE_PREPARING + MATERIAL_PREPARING 复合桶）
+- #7189 合入后有「班期范围」筛选，默认「未结束」按返团日过滤；出行完毕/待审核/已审核的团期返团日必然已过，前端点这三个页签时应自动把范围切到「全部」
+
+### 2. 团期看板统计条 `GET /v3/admin/order/group-batch/summary`
+
+**VO**: `Result<GroupBatchSummaryVO>`（查询参数 productId / month / keyword，无请求 VO）
+
+#### 使用场景
+
+看板页签计数（hl-ui `orderV2Batch.js:74` `getGroupBatchSummary()`），与 GB-ADM-001 同筛选、不含 opsStage。
+
+#### 入参
+
+| 字段 | 位置 | 类型 | 必填 | 约束 | 说明 |
+|------|------|------|------|------|------|
+| productId | query | Long(字符串) | 否 | 雪花 ID | 按产品 |
+| month | query | String | 否 | yyyy-MM | 出发月份 |
+| keyword | query | String | 否 | 已转义 | 班期编号 / 名称模糊 |
+
+#### 出参 `Result<GroupBatchSummaryVO>`
+
+| 字段 | 类型 | 说明 |
+|------|------|------|
+| data.total | Integer | 命中团期总数 = 八桶之和 |
+| data.buckets | Object | **固定 8 键**，顺序 `RECRUIT, FORMED, PENDING_TRIP, TRAVELLING, TRIP_FINISHED, AUDITING, CHECKED, DISBANDED`，无命中为 0（改前 7 键，无 `TRIP_FINISHED`） |
+| data.subOrderCount | Integer | 命中团期活跃子订单合计（不变） |
+
+#### 请求示例
+
+```http
+GET /v3/admin/order/group-batch/summary?productId=2056947670512971778 HTTP/1.1
+Host: api.test.1814.love:9443
+Authorization: Bearer <token>
+```
+
+#### 响应示例
+
+第二轮造数后实测（21:42）：
+
+```json
+{
+  "code": 200,
+  "message": "成功",
+  "data": {
+    "total": 6,
+    "buckets": {
+      "RECRUIT": 0,
+      "FORMED": 2,
+      "PENDING_TRIP": 0,
+      "TRAVELLING": 1,
+      "TRIP_FINISHED": 1,
+      "AUDITING": 0,
+      "CHECKED": 0,
+      "DISBANDED": 2
+    },
+    "subOrderCount": 4
+  },
+  "success": true
+}
+```
+
+#### 空数据 / 降级响应
+
+无命中团期时 `total=0`、`subOrderCount=0`，`buckets` 仍固定返回 8 键全 0。
+
+```json
+{
+  "code": 200,
+  "message": "成功",
+  "data": { "total": 0, "buckets": { "RECRUIT": 0, "FORMED": 0, "PENDING_TRIP": 0, "TRAVELLING": 0, "TRIP_FINISHED": 0, "AUDITING": 0, "CHECKED": 0, "DISBANDED": 0 }, "subOrderCount": 0 },
+  "success": true
+}
+```
+
+#### 错误响应
+
+```json
+{
+  "code": 589507,
+  "message": "无操作权限（非团期管理员 / 非本定制师名下）",
+  "data": null,
+  "success": false
+}
+```
+
+#### 业务边界
+
+- 桶键由后端枚举顺序生成，前端按对象键顺序或按自己的页签表读取都可以，但**不要按索引位置取第 5 个当「待审核」**（改前第 5 个是 AUDITING，改后是 TRIP_FINISHED）
+- 老前端未加新键时：多出的 `TRIP_FINISHED` 键被忽略，`total` 与页签计数之和会差出该桶的数量
+
+### 3. 团期看板导出 `GET /v3/admin/order/group-batch/export`
+
+**VO**: `无请求 VO（查询参数） → CSV 文件流 text/csv`
+
+#### 使用场景
+
+看板「导出」按钮（hl-ui `exportGroupBatch()`），筛选参数与 GB-ADM-001 同义、不含分页。
+
+#### 入参
+
+| 字段 | 位置 | 类型 | 必填 | 约束 | 说明 |
+|------|------|------|------|------|------|
+| productId | query | Long(字符串) | 否 | 雪花 ID | 按产品 |
+| month | query | String | 否 | yyyy-MM | 出发月份 |
+| keyword | query | String | 否 | 已转义 | 班期编号 / 名称模糊 |
+| opsStage | query | String | 否 | 八桶之一 | **新增 `TRIP_FINISHED`** |
+
+#### 出参 `CSV 文件流`
+
+| 字段 | 类型 | 说明 |
+|------|------|------|
+| （响应体） | text/csv | 列与改前一致；状态列可出现「出行完毕」 |
+
+#### 请求示例
+
+```http
+GET /v3/admin/order/group-batch/export?productId=2056947670512971778&opsStage=TRIP_FINISHED HTTP/1.1
+Host: api.test.1814.love:9443
+Authorization: Bearer <token>
+```
+
+#### 响应示例
+
+```json
+{
+  "code": 200,
+  "message": "文件流（Content-Type: text/csv; Content-Disposition: attachment），此处仅示意，实际响应体为 CSV"
+}
+```
+
+#### 空数据 / 降级响应
+
+无命中时返回只有表头的 CSV；命中 > 2000 行返回 `589517`。
+
+```json
+{
+  "code": 589517,
+  "message": "导出行数超过上限，请缩小筛选范围",
+  "data": null,
+  "success": false
+}
+```
+
+#### 错误响应
+
+```json
+{
+  "code": 589507,
+  "message": "无操作权限（非团期管理员 / 非本定制师名下）",
+  "data": null,
+  "success": false
+}
+```
+
+#### 业务边界
+
+- 权限 `group-batch:export`
+- `opsStage` 非法值忽略（与 GB-ADM-001 一致）
+
+---
+
+## 四、契约约束与正确调用方式
+
+> 三个接口均为只读 GET，无请求体；本节写的是**前端消费九态/八桶的规则**。
+
+### ✅ 正确 / ❌ 错误 payload 对照
+
+| 场景 | payload / 处理 |
+|------|---------|
+| ✅ 页签 → 筛选 | 点「出行完毕」页签传 `opsStage=TRIP_FINISHED`（与其它页签同一套 `opsStage`） |
+| ✅ 状态 → 桶 | 八态映射表加 `TRIP_FINISHED: 'TRIP_FINISHED'`；未知状态值按灰/默认样式，不抛错 |
+| ✅ 统计条 | 按键名读 `buckets.TRIP_FINISHED`，不按索引 |
+| ❌ 硬编码七桶数组 | 少一个页签、`total` 对不上 |
+| ❌ 把 `TRIP_FINISHED` 当「已完成」终态 | 它之后还有核单中 / 已结算；核单入口在后续单 |
+
+### 切换状态时的必要动作
+
+无写接口。团期进入 `TRIP_FINISHED` 只由 sys_job 1042 完成（当前 PAUSED）；前端不需要也不能手动推进。
+
+---
+
+## 五、数据库行为
+
+`order_group_batch.batch_status` 为 VARCHAR(32)，直接存新值 `TRIP_FINISHED`，无表变更、无 Flyway（order-v3）。hl-user-service Flyway `V20260906_005__register_group_batch_lifecycle_jobs.sql` 种子两行 `sys_job`（1041 团期出发推进 `0 10 0 * * ?`、1042 团期出行完毕推进 `0 20 0 * * ?`，`job_group=ORDER`，`status=PAUSED`）。
+
+| job | 扫描条件 | 推进 | 时间线事件 |
+|------|-----------------|------|------|
+| 1041 | `PENDING_DEPARTURE` 且 product 侧出发日 ≤ 今天 | → `TRAVELLING` | `BATCH_DEPART` 系统自动发团 |
+| 1042 | `TRAVELLING` 且 product 侧返团日 < 今天 | → `TRIP_FINISHED` | `BATCH_TRIP_FINISH` 系统自动出行完毕 |
+
+状态 CAS 与时间线在同一事务内原子提交；日期取不到 product 实时值时回退团期快照并记 WARN。
+
+---
+
+## 六、边界行为
+
+- 未登录 → 网关 401；无权限 → `589507`
+- `opsStage` / `batchStatus` 传未知值 → 忽略该筛选，不报错
+- 返团日当天仍算出行中（`< 今天` 才推进）；出发日当天即算出行中（`≤ 今天`）
+- 出行完毕团期：退团 → `589501`；转期 / 调满团名额 / 需求提报按既有阶段门拒绝；预支仍可发起
+- HTTP 始终 200，按 `code` 判断
+
+## 六.5、枚举 / 数据字典
+
+### batchStatus（`com.hulalv.order.groupbatch.enums.GroupBatchStatus`）
+
+| 值 | 中文名 | 桶（`GroupBatchStageBuckets.Bucket`） |
+|---|---|---|
+| `RECRUITING` | 招募中 | `RECRUIT` |
+| `RESOURCE_PREPARING` | 资源准备中 | `FORMED` |
+| `MATERIAL_PREPARING` | 物料准备中 | `FORMED` |
+| `PENDING_DEPARTURE` | 待出发 | `PENDING_TRIP` |
+| `TRAVELLING` | 出行中 | `TRAVELLING` |
+| **`TRIP_FINISHED`** | **出行完毕（新增）** | **`TRIP_FINISHED`（新增）** |
+| `REVIEWING` | 核单中 | `AUDITING` |
+| `SETTLED` | 已结算 | `CHECKED` |
+| `CANCELLED` | 已取消 | `DISBANDED` |
+
+### opsStage / buckets 键（`GroupBatchStageBuckets.Bucket`）
+
+`RECRUIT` 招募中 / `FORMED` 已成团 / `PENDING_TRIP` 待出行 / `TRAVELLING` 出行中 / **`TRIP_FINISHED` 出行完毕** / `AUDITING` 待审核 / `CHECKED` 已审核 / `DISBANDED` 流团（前端页签文案沿用现有）。
+
+## 六.6、修改前后对比
+
+### 字段级对比
+
+| 字段 | 修改前 | 修改后 |
+|------|--------|--------|
+| GB-ADM-001 / 008 `opsStage` 取值 | 7 值 | 8 值（+ `TRIP_FINISHED`） |
+| GB-ADM-001 `records[].batchStatus` 取值 | 8 值 | 9 值（+ `TRIP_FINISHED`，中文名「出行完毕」） |
+| GB-ADM-009 `buckets` 键 | 7 键 | 8 键，`TRIP_FINISHED` 插在 `TRAVELLING` 与 `AUDITING` 之间 |
+
+### 行为级对比
+
+| 场景 | 修改前 | 修改后 |
+|------|--------|--------|
+| 待出发团期到出发日 | 无人推进，永远待出发 | sys_job 1041（resume 后）每日 00:10 → 出行中 |
+| 出行中团期过返团日 | 无人推进，永远出行中 | sys_job 1042（resume 后）每日 00:20 → 出行完毕 |
+| 出行完毕团期芯片 | 不存在该态 | 房/车/导/摄恒 `DONE`（与已返团同） |
+| 出行完毕团期退团 | 不存在该态 | `589501` |
+| 原七桶各自口径 | — | 不变 |
+
+## 六.7、影响评估
+
+- 向后兼容：只增枚举值/键，不改字段名；老前端不改代码不报错，但页签少「出行完毕」、统计条多出的键被忽略
+- 前端是否必须同步上线：否（job PAUSED 期间不会出现该态数据）；但应在 job resume 前补齐
+- 数据：order-v3 无表变更；user-service 只有 sys_job 种子
+
+---
+
+## 七、不影响范围
+
+- **仅影响**: 团期看板页签/统计条/导出的桶集合，团期状态取值
+- **零影响**:
+  - #7204 导/摄芯片零指派口径、房/车/约/保芯片
+  - 订单（子订单）状态机与订单接口
+  - 团期成团 / 取消成团 / 流团 / 物资确认 / 结算守卫（仍要求核单中）
+  - 小程序
+
+---
+
+## 八、测试环境已验证
+
+真实接口输出（测试服 api.test.1814.love，2026-09-06 21:38-21:42，登录后切 ADMIN / 触发 job 切 SUPER_ADMIN）：
+
+```
+GET /v3/admin/order/group-batch/summary?productId=2044306857534636034                       → 200, buckets 键序 RECRUIT,FORMED,PENDING_TRIP,TRAVELLING,TRIP_FINISHED,AUDITING,CHECKED,DISBANDED ✓
+POST /admin/job/1041/trigger、/admin/job/1042/trigger（第一轮，造数期均为未来日期）           → sys_job_log SUCCESS，A/B 状态不动 ✓
+POST /admin/job/1041/trigger、/admin/job/1042/trigger（第二轮，product 侧日期改到 09-05）    → SUCCESS，A→TRAVELLING、B→TRIP_FINISHED，order 快照日期未动 ✓
+GET /v3/admin/order/group-batch?productId=2056947670512971778&opsStage=TRIP_FINISHED        → 200, 1 行 B「出行完毕」 ✓
+GET /v3/admin/order/group-batch/summary?productId=2056947670512971778                       → TRAVELLING=1, TRIP_FINISHED=1 ✓
+GET /v3/admin/order/group-batch/2096510069465088002/chips/hotel                             → aggregateStatus=DONE（硬规则） ✓
+POST /v3/admin/order/group-batch/2096510069465088002/sub-order/2096510069234401282/withdraw → 589501 ✓
+```
+
+验证团期: A `2096495107078328322`、B `2096510069465088002`（产品 2056947670512971778「测试小蒙马-多档-固定金额」），造数已复原。单测：`GroupBatchStageBucketsTest` 12/0、`GroupBatchSummaryVOTest` 2/0、`GroupBatchStatusTest` 6/0、`GroupBatchLifecycleJobServiceTest` 11/0、`GroupBatchLifecycleTxServiceTest` 4/0、`GroupBatchLifecycleJobTest` 3/0、`GroupBatchMapperIT` 13/0；合入后 dev-v3 HEAD 全量 order-v3 8726/0、hl-user-service `QuartzJobExecutorTest` 16/0。部署：Deploy Panel 21:20-21:22 双实例滚动完成（order-v3 + user-service），分支 dev-v3。
+
+---
+
+## 十、相关文档
+
+- 关联 Issue: [wx/HL#7190](https://git.1814.love:8443/wx/HL/issues/7190)
+- 关联 PR: [wx/HL#7212](https://git.1814.love:8443/wx/HL/pulls/7212)
+- 同现场: #7188（「第N期」序号）、#7189（看板以产品全班期为基底 + 班期范围筛选）、#7204（导/摄芯片零指派口径）
+- 后续单: 「出行完毕 → 核单中」发起核单入口（落地前两个 sys_job 保持 PAUSED）
+
+## 关联 / 联系人
+
+### 链接
+
+- **Issue**: [#7190](https://git.1814.love:8443/wx/HL/issues/7190)
+- **PR**: [#7212](https://git.1814.love:8443/wx/HL/pulls/7212)
+- **Merge commit**: [ccb4d8fd](https://git.1814.love:8443/wx/HL/commit/ccb4d8fd5177ef816e71fadd33335f8f1dce3966)
+
+### 联系人
+
+- **后端负责人**: @wx