hl-api-changelog/changelogs-v2/2026-10/01_8671_团期核单页签扩为核单三态-修改接口-管理后台.md

schema, ticket, title, consumer, author, change_type, backend_status, gateway_status, frontend_status, frontend_owner, frontend_ref, target_release, verified_at, base, updated_at, status_note

schema	ticket	title	consumer	author	change_type	backend_status	gateway_status	frontend_status	frontend_owner	frontend_ref	target_release	verified_at	base	updated_at	status_note
hl-changelog/v2	8671	团期看板「核单」页签 opsStage=REVIEW 筛选口径扩为核单三态	admin	yst(GIT)	修改接口	merged	verified	implemented	hl-admin(claude-opus-4-8)	04b5cca6bfa46f93711bb6cc9019e3b6e284488e	v2.1	2026-10-01	dev-v3	2026-10-01	团期看板「核单」页签（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 典型：核单页签查询

请求：

GET /v3/admin/order/group-batch?pageNo=1&pageSize=20&opsStage=REVIEW&scope=ALL
Authorization: Bearer {adminToken}
（无请求体）

响应（返回核单中 + 已结算两类团期；当前库暂无「待核单」团，故为 2 条）：

{
  "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，缺省规则会把它们按「未结束」滤掉。

请求：

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
• PR: #8672
• Merge commit: f01d7565b3

13.2 联系人

• 后端负责人: @yst
• 前端对接（管理后台）: @hl-admin