---
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: "04b5cca6bfa46f93711bb6cc9019e3b6e284488e"
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 即可，无需改入参；但同入参返回的团期集合变大，核单页签会多看到待核单与已结算的团。前端已交付：核单页签带 productId 时列表请求显式传 scope=ALL（§8.2 缺省 ONGOING 会滤掉核单三态），其余桶维持不传 scope 口径，统计条不受影响。（此前 frontmatter 误标 implemented 无 ref，本次实证交付后补齐。）"
---

# 【修改接口·管理后台】团期看板「核单」页签筛选口径扩为核单三态 (#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}
（无请求体）
```

**响应**（返回核单中 + 已结算两类团期；当前库暂无「待核单」团，故为 2 条）：
```json
{
  "code": 200,
  "data": {
    "total": 2,
    "records": [
      { "groupBatchId": "2105223439872933889", "batchNo": "T26-2325", "batchStatus": "REVIEWING", "batchStatusName": "核单中", "stage": "REVIEW", "stageName": "核单", "reviewStatus": "COMPLETED", "reviewStatusName": "已核单", "settlementStatus": "PENDING", "settlementStatusName": "待结算" },
      { "groupBatchId": "2105223438312652802", "batchNo": "T26-5936", "batchStatus": "SETTLED", "batchStatusName": "已结算", "stage": "SETTLE", "stageName": "结算", "reviewStatus": "COMPLETED", "reviewStatusName": "已核单", "settlementStatus": "COMPLETED", "settlementStatusName": "已结算" }
    ]
  },
  "message": "成功",
  "success": true
}
```

> 说明：核单页签现在会同时返回「核单中」与「已结算」的团（改前只返回核单中）。若库里有「待核单 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