diff --git a/backend-requests/2026-09/11_7324_放开H1看板batchStatus过滤CANCELLED-整团释放可达.md b/backend-requests/2026-09/11_7324_放开H1看板batchStatus过滤CANCELLED-整团释放可达.md new file mode 100644 index 00000000..703d6e7d --- /dev/null +++ b/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`(阶段闸门,无需改)