docs(backend-request): #7324 放开 H1 看板 batchStatus 对 CANCELLED 的过滤

前端 #7324 已交付整团释放写口(commit 6710ad4a),但 H1 列表忽略 CANCELLED
过滤导致已流团团期进不了看板、释放按钮无可达路径。写明需求/现状/期望/
安全性供后端评估排期:放开 H1 对 CANCELLED 过滤(推荐方案 A),前端零改动等待。

backend-requests/2026-09/11_7324_放开H1看板batchStatus过滤CANCELLED-整团释放可达.md

@@ -0,0 +1,77 @@
+---
+schema: "hl-backend-request/v1"
+title: "放开 H1 看板列表 batchStatus 对 CANCELLED 的过滤（让整团释放入口可达）"
+consumer: "backend"
+requester: "mmg（前端）"
+author: "mmg"
+target_service: "hl-order-service-v3"
+status: "proposed"
+related_issue: "7324"
+related_frontend_commit: "6710ad4a"
+created_at: "2026-09-11"
+---
+
+# 需求：放开 H1 看板列表 `batchStatus` 对 `CANCELLED` 的过滤
+
+> **来源工单**: #7324 房务团期看板与整团按日订房计划 CRUD
+> **服务**: `hl-order-service-v3`
+> **提出方**: 前端（mmg），2026-09-11
+> **状态**: 待后端评估 / 排期
+
+---
+
+## 一、一句话需求
+
+房务团期看板列表 `GET /v3/admin/house/group-batches`（H1）当前把 `batchStatus=CANCELLED` 从过滤里**忽略**（传了被静默丢弃，回退默认四态），导致已流团团期永远进不了看板列表；而「整团释放」写口仅对 CANCELLED 团期放行，前端「整团释放」按钮因此**没有任何用户可达路径**。请放开 H1 对 CANCELLED 的过滤，让已认领的已流团团期能进入看板列表。
+
+---
+
+## 二、现状行为（契约原文，#7324 changelog）
+
+`#7324` changelog 两处明确了当前过滤行为：
+
+1. H1 `batchStatus` 入参表：「传 `CANCELLED` **被忽略**」——默认四态 = `RESOURCE_PREPARING, MATERIAL_PREPARING, PENDING_DEPARTURE, TRAVELLING`（`HouseGroupBatchBoardManager.java:60-64`）。
+2. 边界行为：「`batchStatus` 若传入非法状态码或全部被过滤掉（如只传 `CANCELLED`），**静默回退为默认四态**，不报错」（`HouseGroupBatchBoardManager.java:224-236`）。
+
+链路后果：
+
+- 看板列表 H1 **结构性不返回** CANCELLED 团期。
+- 详情弹层（H2）只能从 H1 行点开，所以永远拿不到一个 `batchStatus==='CANCELLED'` 的 detail。
+- 前端「整团释放」按钮的显隐条件是 `detail.batchStatus === 'CANCELLED'`（`canReleaseAll`），恒为 false，按钮永不渲染。
+- release-all 端点 `POST .../room-plans/release-all` 本身仅对 CANCELLED 放行（其它态 808618，`HouseGroupBatchPlanGate.PLAN_RELEASE_ONLY_STATUSES` 只含 CANCELLED），端点行为自洽、无 bug——**只是前端够不到一个 CANCELLED 团期去调它**。
+
+---
+
+## 三、期望行为
+
+让 H1 在「按认领维度」下能返回已流团（CANCELLED）团期，二选一均可：
+
+- **方案 A（推荐）**：`batchStatus` 入参放开 `CANCELLED`——前端显式传 `batchStatus=CANCELLED` 时后端按此过滤，不再忽略/回退。改动最小，不影响不传参时的默认四态。
+- **方案 B**：新增一个独立查询参数（如 `includeCancelled=true` 或 `scope` 扩展），在认领维度下附带返回 CANCELLED 团期。
+
+无论哪个方案，都请保持「未认领团不进本页」的既有边界（H1 业务边界第 1 条），CANCELLED 放开只作用于「已被房务认领」的团。
+
+---
+
+## 四、为什么安全 / 不破坏既有
+
+- **阶段闸门已天然兜住写口**：`HouseGroupBatchPlanGate.PLAN_WRITABLE_STATUSES`（可写六态）不含 CANCELLED，H4/H5 对 CANCELLED 团期本就走 808600；H6/release-all 走更宽的 `releaseOnly` 分支（CANCELLED 放行）。放开 H1 过滤**不改变任何写口的阶段闸门判定**——只是让 CANCELLED 团期「能被看见」，写口权限仍由各端点自己的闸门控制。
+- **release-all 端点无需改**：它已正确地对 CANCELLED 放行、对其它态 808618，本次只动 H1 读侧。
+- **向后兼容**：不传 `batchStatus` 的既有调用方仍走默认四态，行为零变化；只有显式传 `CANCELLED` 的调用方才看到新返回。
+
+---
+
+## 五、前端配套（已就绪，零改动等待）
+
+前端「整团释放」按钮与 release-all 调用**已实现并保留**（`#7324` 前端 commit `6710ad4a`），显隐条件 `canReleaseAll` 已按「`batchStatus==='CANCELLED'` 且非组长只读」写好。后端一旦放开 H1 的 CANCELLED 过滤，CANCELLED 团期进入看板 → 详情弹层 `detail.batchStatus` 即为 CANCELLED → 按钮自动出现并可点，**前端无需任何改动**。
+
+后端部署后通知前端即可，前端会回归验证「整团释放」入口可达。
+
+---
+
+## 关联
+
+- Issue: [#7324](https://git.1814.love:8443/wx/HL/issues/7324)
+- 后端 PR: [#7465](https://git.1814.love:8443/wx/HL/pulls/7465)
+- 前端交付 commit: `6710ad4a`（hl-admin `v2.1`）
+- 相关源码: `HouseGroupBatchBoardManager.java`（H1 编排，`:60-64` 默认四态、`:224-236` batchStatus 过滤）、`HouseGroupBatchPlanGate.java`（阶段闸门，无需改）