团期核单页签 opsStage=REVIEW 筛选口径扩为核单三态（#8671）

changelogs-v2/2026-10/01_8671_团期核单页签扩为核单三态-修改接口-管理后台.md
2026-10-01 09:18:32 +08:00
@@ -0,0 +1,192 @@
+---
+schema: "hl-changelog/v2"
+ticket: "8671"
+title: "团期看板「核单」页签 opsStage=REVIEW 筛选口径扩为核单三态"
+consumer: "admin"
+author: "yst(GIT)"
+change_type: "修改接口"
+backend_status: "merged"
+gateway_status: "verified"
+frontend_status: "implemented"
+frontend_owner: "hl-admin(claude-opus-4-8)"
+frontend_ref: ""
+target_release: "v2.1"
+verified_at: "2026-10-01"
+base: "dev-v3"
+updated_at: "2026-10-01"
+status_note: "团期看板「核单」页签（opsStage=REVIEW）筛选范围扩大：从只含「核单中 REVIEWING」扩为「待核单 PENDING_REVIEW + 核单中 REVIEWING + 已结算 SETTLED」三态。前端继续传 opsStage=REVIEW 即可，无需改入参；但同入参返回的团期集合变大，核单页签会多看到待核单与已结算的团。"
+---
+
+# 【修改接口·管理后台】团期看板「核单」页签筛选口径扩为核单三态 (#8671)
+
+> **PR**: #8672 | **服务**: hl-order-service-v3（8086） | **更新时间**: 2026-10-01
+
+## 1. 接口背景
+
+管理后台「团期」看板的「核单」页签，业务上应只列出与核单相关的团期（待核单 / 核单中 / 已结算），把招募中、资源准备中、待出发、出行中、已取消等非核单团过滤掉。
+
+此前「核单」页签（`opsStage=REVIEW`）只筛「核单中 REVIEWING」一个状态，导致：
+- **待核单**（已返团、尚未开始核单）的团看不到——它被归在「出行」页签下；
+- **已结算**的团看不到——它被归在「结算」页签下。
+
+财务 / 运营在核单页签想统览「整个核单阶段」的团时，要么漏团，要么得把范围切到「全部」把无关团全拉进来。
+
+## 2. 变更清单
+
+| # | 接口 | 方法 | 路径 | 变更类型 | 说明 |
+|---|------|------|------|----------|------|
+| 1 | 团期分页看板列表 | GET | `/v3/admin/order/group-batch` | 修改接口 | `opsStage=REVIEW` 筛选口径扩为核单三态 |
+
+> 说明：本接口同时被 `/v3/admin/order/group-batch/board`（看板视图）复用同一筛选口径，行为一致变化。
+
+## 3. 接口详情
+
+### 3.1 团期分页看板列表
+
+- **使用场景**：管理后台团期看板分页查询，前端点各页签（招募/配置/确认/出行/核单/结算/已流团）时传对应 `opsStage` 筛选。
+- **认证**：需 JWT（管理后台管理员）。
+- **幂等性**：查询接口，天然幂等。
+- **限流**：无。
+
+## 4. 接口入参
+
+### 4.1 Query 参数（仅列本次相关）
+
+| 字段 | 类型 | 必填 | 说明 |
+|------|------|------|------|
+| `opsStage` | String | ❌ | 看板桶筛选。本次仅 `REVIEW` 一档的展开口径变化，其余桶不变 |
+| `pageNo` | Integer | ❌ | 页码，默认 1 |
+| `pageSize` | Integer | ❌ | 每页条数 |
+| `scope` | String | ❌ | 班期范围（ONGOING/FINISHED/ALL）。⚠️ 见 §9 边界：核单三态返团日已过，默认 ONGOING 会滤掉，需传 ALL |
+
+## 5. 出参（响应）
+
+出参字段结构**完全不变**（仍是团期分页 `records[]`，含 `groupBatchId`/`batchNo`/`batchStatus`/`reviewStatus`/`settlementStatus`/`stage`/`stageName` 等）。本次只改「哪些团期被筛进结果集」，不改任何返回字段。
+
+> ⚠️ 核单页签内不同行的 `stage` / `stageName`（节点标签）**可能不统一**：待核单的团节点仍显示「出行」、已结算的团节点仍显示「结算」。这是刻意的——本次只扩筛选范围，不动看板六节点归属模型。前端如对节点标签有统一展示诉求，需另行提需求。
+
+## 6. 枚举 / 数据字典
+
+### 6.1 opsStage（看板桶筛选值）
+
+**所属字段**：`opsStage` | **类型**：`String` | **必填**：❌
+
+| 值 | 中文 | 展开为哪些团期状态 | 本次是否变化 |
+|----|------|--------------------|--------------|
+| `RECRUIT` | 招募 | RECRUITING | 否 |
+| `CONFIGURE` | 配置 | RESOURCE_PREPARING | 否 |
+| `CONFIRM` | 确认 | MATERIAL_PREPARING | 否 |
+| `TRIP` | 出行 | PENDING_DEPARTURE + TRAVELLING + PENDING_REVIEW | 否 |
+| `REVIEW` | 核单 | **PENDING_REVIEW + REVIEWING + SETTLED** | ✅ 变化 |
+| `SETTLE` | 结算 | SETTLED | 否 |
+| `DISBANDED` | 已流团 | CANCELLED | 否 |
+
+### 6.2 batchStatus（团期九态，出参）
+
+| 值 | 中文 | 说明 |
+|----|------|------|
+| `RECRUITING` | 招募中 | — |
+| `RESOURCE_PREPARING` | 资源准备中 | — |
+| `MATERIAL_PREPARING` | 物料准备中 | — |
+| `PENDING_DEPARTURE` | 待出发 | — |
+| `TRAVELLING` | 出行中 | — |
+| `PENDING_REVIEW` | 待核单 | 返团后尚未开始核单 |
+| `REVIEWING` | 核单中 | — |
+| `SETTLED` | 已结算 | — |
+| `CANCELLED` | 已取消 | 流团 |
+
+## 7. 错误码
+
+本接口无新增错误码；`opsStage` 传非法值时忽略该筛选并记 warn（不报错、不返 400）。
+
+## 8. 示例（典型 / 边界）
+
+### 8.1 典型：核单页签查询
+
+**请求**：
+```http
+GET /v3/admin/order/group-batch?pageNo=1&pageSize=20&opsStage=REVIEW&scope=ALL
+Authorization: Bearer {adminToken}
+（无请求体）
+```
+
+**响应**（返回待核单 + 核单中 + 已结算三类团期）：
+```json
+{
+  "code": 200,
+  "data": {
+    "total": 2,
+    "records": [
+      { "groupBatchId": "2105223439872933889", "batchNo": "T26-2325", "batchStatus": "PENDING_REVIEW", "batchStatusName": "待核单", "stage": "TRIP", "stageName": "出行", "reviewStatus": "PENDING", "settlementStatus": "NONE" },
+      { "groupBatchId": "2105223438312652802", "batchNo": "T26-5936", "batchStatus": "PENDING_REVIEW", "batchStatusName": "待核单", "stage": "TRIP", "stageName": "出行", "reviewStatus": "PENDING", "settlementStatus": "NONE" }
+    ]
+  },
+  "message": "成功",
+  "success": true
+}
+```
+
+> 注意示例中 `batchStatus=PENDING_REVIEW`（待核单）的团，其 `stageName` 仍是「出行」——筛选把它选进了核单页签，但节点标签维持出行。见 §5 说明。
+
+### 8.2 边界：默认 scope=ONGOING 会滤掉核单团
+
+**场景说明**：核单三态的团期返团日必然已过，若前端不传 `scope=ALL`，缺省规则会把它们按「未结束」滤掉。
+
+**请求**：
+```http
+GET /v3/admin/order/group-batch?pageNo=1&pageSize=20&opsStage=REVIEW
+Authorization: Bearer {adminToken}
+（无请求体，scope 缺省）
+```
+
+**响应**：productId 缺省时 scope 默认 ALL（不受影响）；productId 有值时 scope 默认 ONGOING，核单团被滤掉返回空。前端点核单页签**务必显式传 `scope=ALL`**。
+
+## 9. 业务边界
+
+- ✅ **适用**：核单页签统览核单阶段全部团期（待核单 / 核单中 / 已结算）。
+- ⚠️ **scope 联动**：核单三态返团日已过，前端点核单页签需把 `scope` 切到 `ALL`，否则默认范围会把它们过滤掉（此约束改前已存在，本次不变）。
+- ⚠️ **节点标签不统一**：核单页签内，待核单团节点显示「出行」、已结算团节点显示「结算」（见 §5）。
+- ❌ **不变**：`SETTLE` 结算页签仍只筛 `SETTLED`；`TRIP` 出行页签仍含 `PENDING_REVIEW`（待核单团会同时出现在出行页签与核单页签）。
+
+## 10. 修改前后对比
+
+### 10.1 行为级对比
+
+| 行为 | 改前 | 改后 |
+|------|------|------|
+| `opsStage=REVIEW` 筛出的团期状态 | 仅 REVIEWING（核单中） | PENDING_REVIEW + REVIEWING + SETTLED（核单三态） |
+| 核单页签能否看到「待核单」团 | ❌ 看不到（在出行页签） | ✅ 能看到 |
+| 核单页签能否看到「已结算」团 | ❌ 看不到（在结算页签） | ✅ 能看到 |
+| 入参字段 / 出参字段 | — | 完全不变 |
+
+## 11. 影响评估 / 回滚
+
+### 11.1 影响评估
+
+- **是否破坏向后兼容**：否。入参出参字段不变；仅 `opsStage=REVIEW` 返回的数据集扩大（多返回待核单 + 已结算团期）。
+- **前端是否必须同步上线**：否。前端继续传 `opsStage=REVIEW` 即可；但需留意核单页签行数会变多、节点标签不统一。
+- **影响已有数据**：无，纯查询筛选口径变化，无数据迁移。
+
+### 11.2 回滚方案
+
+- **回滚方式**：revert PR #8672 即可恢复 `opsStage=REVIEW` 单态口径。
+- **回滚后清理**：无（无脏数据 / 缓存）。
+- **回滚耗时**：重新打包部署 hl-order-service-v3，约 5 分钟。
+
+## 12. 注意事项
+
+- 上线需重启 / 重新部署 **hl-order-service-v3**（8086）。
+- 前端无需改入参；如核单页签需统一节点标签，属另一个展示层需求，单独提。
+
+## 13. 关联 / 联系人
+
+### 13.1 链接
+
+- **Issue**: [#8671](https://git.1814.love/wx/HL/issues/8671)
+- **PR**: [#8672](https://git.1814.love/wx/HL/pulls/8672)
+- **Merge commit**: [f01d7565b3](https://git.1814.love/wx/HL/commit/f01d7565b3b750841eb32af98a448f5b1a7b5b7f)
+
+### 13.2 联系人
+
+- **后端负责人**: @yst
+- **前端对接（管理后台）**: @hl-admin