docs: 答复前端 #7324 后端需求（后端零改动）+ 补 #7322 我的团不过滤 batch_status
changelog-filename-gate / validate (push) Successful in 2s
changelog-filename-gate / validate (push) Successful in 2s
前端据 H1 看板过滤 CANCELLED 的行为，推断「整团释放」按钮无可达路径。 该推断的关键环节不成立：我的团（GET /v3/admin/order/grab-pool/my-claims/ group-batches）刻意不按 batch_status 过滤，H2 详情也没有阶段闸门， CANCELLED 团期经「我的团 → H2 详情」完全可达。 根因在我方：#7322 的 changelog 从未写过这条行为，前端看不到 javadoc。 本次一并补记，并在需求单上答复 status=answered-no-backend-change。 Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
这个提交包含在：
API Changelog Bot
@@ -5,10 +5,13 @@ consumer: "backend"
|
||||
requester: "mmg（前端）"
|
||||
author: "mmg"
|
||||
target_service: "hl-order-service-v3"
|
||||
status: "proposed"
|
||||
status: "answered-no-backend-change"
|
||||
related_issue: "7324"
|
||||
related_frontend_commit: "6710ad4a"
|
||||
created_at: "2026-09-11"
|
||||
answered_at: "2026-09-11"
|
||||
answered_by: "Claude（后端管理者）"
|
||||
backend_verdict: "可达路径已存在，后端零改动；我方 #7322 changelog 漏写「我的团」不过滤 batch_status，前端的判断在当时信息下是合理的"
|
||||
---
|
||||
|
||||
# 需求：放开 H1 看板列表 `batchStatus` 对 `CANCELLED` 的过滤
|
||||
@@ -75,3 +78,76 @@ created_at: "2026-09-11"
|
||||
- 后端 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`（阶段闸门，无需改）
|
||||
|
||||
|
||||
---
|
||||
|
||||
## 🔧 后端答复（2026-09-11）
|
||||
|
||||
> **结论：本单不需要后端改动——可达路径已经存在。而你们不知道它存在，是因为我们的 #7322 changelog 漏写了一条关键行为。这个缺口在我方。**
|
||||
|
||||
### 一、结论先行
|
||||
|
||||
「整团释放按钮没有任何用户可达路径」这一判断**不成立**。已经存在的路径是：
|
||||
|
||||
```
|
||||
GET /v3/admin/order/grab-pool/my-claims/group-batches ← 我的团（#7322 已交付且已验收）
|
||||
↓ 该列表不过滤 batch_status，已流团（CANCELLED）团期就在里面
|
||||
↓ 行上直接带 groupBatchId / batchStatus / batchStatusLabel
|
||||
GET /v3/admin/house/group-batches/{groupBatchId} ← H2 详情（无阶段闸门）
|
||||
↓ detail.batchStatus === 'CANCELLED' → canReleaseAll 成立
|
||||
POST /v3/admin/house/group-batches/{groupBatchId}/room-plans/release-all
|
||||
```
|
||||
|
||||
### 二、逐环节证据（五条，全部对源码复核过，不是从文档转述）
|
||||
|
||||
| # | 环节 | 证据 |
|
||||
|---|---|---|
|
||||
| 1 | **我的团不过滤 `batch_status`** | `HouseGroupGrabService.listMyGroups` javadoc 原话：「**不限制 batch_status**：已认领的团可能已流团 / 已结束，本单不自动释放指针，**房务仍要看得见并手动释放**」。代码 `q.setBatchStatus(req.getBatchStatus())` 原样下推，**不传就是不加这个条件**，没有 H1 那种「过滤空了回退默认四态」的逻辑 |
|
||||
| 2 | **服务层也不注入状态** | `GroupBatchService.pageHouseClaimed` 直接把 query 下推 mapper，零注入 |
|
||||
| 3 | **同一文件里的对照（最强证据）** | 紧挨着的 `GroupBatchService.pageHouseGrabPool` 却**强制**写死 `q.setBatchStatuses(REQUIREMENT_CONFIRMABLE_STATUSES)`。一个注入、一个不注入，**是刻意区分不是遗漏** |
|
||||
| 4 | **我的团的行携带判定所需字段** | `HouseMyGroupItemRespVO extends HouseGroupGrabPoolItemRespVO`，父类有 `groupBatchId`、`batchStatus`、`batchStatusLabel` |
|
||||
| 5 | **H2 详情没有阶段闸门** | `HouseGroupBatchBoardController.detail` 的门**只有归属**（未认领 808612 / 他人认领 808613），**不判 `batchStatus`**——CANCELLED 团只要是本人认领的就能打开 |
|
||||
|
||||
你对 release-all 端点本身的判断是对的：它只对 CANCELLED 放行、其它态 808618，端点自洽无 bug。
|
||||
|
||||
### 三、H1 过滤掉 CANCELLED 是刻意设计，且原注释就指明了入口在详情页
|
||||
|
||||
`HouseGroupBatchBoardManager.resolveBatchStatuses` 上方注释原话：
|
||||
|
||||
> 「为什么已流团的团不许出现在看板：本页是『要干活的团』，流团团的唯一动作是整团释放，**那个入口在详情页而不是列表页**；混在一起会让房务每天都在列表里看到一堆做不了任何事的团。」
|
||||
|
||||
注释写明了「详情页」，**但没写明从哪个列表进详情页**——这就是这次误判的接缝所在。
|
||||
|
||||
### 四、这次的根因在我方，不在你们
|
||||
|
||||
你们的推理链条本身是严密的：读 #7324 changelog → H1 明确写了「传 CANCELLED 被忽略」→ 详情从 H1 点开 → 因此 CANCELLED 详情不可达。**在你们掌握的信息里，这个结论是对的。**
|
||||
|
||||
问题出在 **#7322 的 changelog 从头到尾没有提过「我的团」不过滤 `batch_status`**（我逐行搜过那篇，零命中）。这条行为是后端刻意设计并写进 javadoc 的，却**没有进入交接件**——而 javadoc 你们看不到。
|
||||
|
||||
**所以这是我方的文档缺口，不是你们的疏忽。** #7322 的 changelog 我会补这一条。
|
||||
|
||||
### 五、前端需要做什么（如果需要）
|
||||
|
||||
把「我的团」列表行接到 H2 详情弹层——同一个弹层，入参就是行上已有的 `groupBatchId`。两端 API 都已交付并验收过（#7322 changelog `frontend_status: verified`），这是**接线**不是新功能。
|
||||
|
||||
如果「我的团」页当前打开的不是 H2 那个弹层，这一步是前端改动；**后端仍然零改动**。
|
||||
|
||||
补一条使用上的细节：我的团的 `batchStatus` 入参是**透传**的，所以
|
||||
|
||||
- 不传 → 全部已认领团（含 CANCELLED）；
|
||||
- 传 `CANCELLED` → **只看已流团的团**，做一个「待释放」筛选很自然。
|
||||
|
||||
这和 H1 的行为正好相反（H1 传 `CANCELLED` 会被丢弃并回退默认四态），**两个列表的 `batchStatus` 语义不同，别套用同一套前端逻辑**。
|
||||
|
||||
### 六、留给 wx 的产品判断（这一条不是 bug，是口径）
|
||||
|
||||
方案 A（H1 放开 CANCELLED）实现成本确实很低，你对「不破坏既有」的分析也站得住：写口闸门 `PLAN_WRITABLE_STATUSES` 不含 CANCELLED，放开读侧不影响任何写口判定——这点我复核过，属实。
|
||||
|
||||
**但我不建议改**，理由是它与「看板 = 要干活的团」这条既有定案直接冲突，而该定案是有成文理由的（见第三节注释）。已流团团期在看板里是纯噪声：房务对它只能做一个动作，而那个动作有专门的入口。
|
||||
|
||||
如果 wx 判断「房务更习惯在看板里找」，那我照做——**但那时它是一次产品口径调整，不是修 bug**，会另开工单并同步改注释里的定案说明。这个判断我交给 wx，不自行拍板。
|
||||
|
||||
---
|
||||
|
||||
**后端本单零改动。#7322 的 changelog 会补「我的团不过滤 batch_status」一条。**
|
||||
|
||||
@@ -10,10 +10,10 @@ gateway_status: "not_required"
|
||||
frontend_status: "verified"
|
||||
frontend_owner: "mmg"
|
||||
frontend_ref: "745cd9b8"
|
||||
target_release: ""
|
||||
target_release: "hl-ui@745cd9b8"
|
||||
verified_at: "2026-09-10"
|
||||
status_note: "本篇覆盖 PR #7436（合并提交 ab4118a01）。2026-09-10 已部署测试服（HEAD 6d41d6148，已验 ab4118a01 为其祖先），Flyway V20260910_301 执行成功，order_group_batch 三列 house_claimer_id/house_claimer_name/house_claimed_at 已落库。32 条验收项中 28 条已取证，含用 5 个真实登录账号过网关实测的归属与接管链路。后台菜单（sys_menu）的两行抢单池入口已由 PR #7467（squash 7f791a250，hl-user-service 的 V20260910_001）补上。⚠️ 部署两条：① #7322 的部署清单原本不含 hl-user-service，本次起必须带上；② 菜单树按 roleId 缓在 Redis（cache:menu:tree:role:{roleId}，TTL 3600s），Flyway 直连 DB 不触发失效，部署后需 DEL cache:menu:tree:role:* 否则最长要等一小时。前端已交付(commit 745cd9b8):新增团期抢单池页(抢单池·团期+我的团两 Tab,含超管团级接管)与普通抢单池独立页,orders 页摘除 pool scope,BatchHero 接负责房务三字段;checkpoint 全绿。"
|
||||
updated_at: "2026-09-10"
|
||||
updated_at: "2026-09-11"
|
||||
base: "dev-v3"
|
||||
---
|
||||
|
||||
@@ -392,7 +392,7 @@ Authorization: Bearer <持 SUPER_ADMIN 的管理端 token>
|
||||
|---|---|---|---|---|---|
|
||||
| scope | Query | String | 否 | `mine`（默认）/ `all` | 普通房务传 `all` → 808092 |
|
||||
| keyword | Query | String | 否 | ≤32 字 | `batchNo`/`productName` 模糊 |
|
||||
| batchStatus | Query | String | 否 | 团期九态任一，非法值 400 | — |
|
||||
| batchStatus | Query | String | 否 | 团期九态任一，非法值 400 | **透传，不做任何过滤**——含 `CANCELLED`。不传 = 全部已认领团（含已流团）。⚠️ 与 H1 看板语义相反，详见下方补记 |
|
||||
| needsReconfirm | Query | Boolean | 否 | `true`=只看 `requirement_confirmed=0` 的团 | 待管理员重新确认 |
|
||||
| departDateFrom / departDateTo | Query | LocalDate | 否 | — | 出发日区间 |
|
||||
| claimedAtFrom / claimedAtTo | Query | LocalDateTime | 否 | `yyyy-MM-dd'T'HH:mm:ss` | 认领时间区间 |
|
||||
@@ -415,6 +415,30 @@ Authorization: Bearer <持 SUPER_ADMIN 的管理端 token>
|
||||
|
||||
（字段取自 `HouseMyGroupPageRespVO.java`、`HouseMyGroupItemRespVO.java`、`HouseMyGroupStatsVO.java`。）
|
||||
|
||||
#### 🔴 补记（2026-09-11）：本列表**不按 `batch_status` 过滤**，已流团（CANCELLED）团期就在里面
|
||||
|
||||
这条行为原本就是后端的刻意设计，但**本篇首发时漏写了**，在此补上。
|
||||
|
||||
- `HouseGroupGrabService.listMyGroups` 的 javadoc 原话：「**不限制 batch_status**：已认领的团可能已流团 / 已结束，本单不自动释放指针，**房务仍要看得见并手动释放**」；
|
||||
- 服务层 `GroupBatchService.pageHouseClaimed` 把查询条件**原样下推**，零注入；
|
||||
对照：同一个类里的 `pageHouseGrabPool`（团期抢单池）却**强制**写死 `REQUIREMENT_CONFIRMABLE_STATUSES`。
|
||||
一个注入、一个不注入，是刻意区分，不是遗漏。
|
||||
|
||||
**与 H1 房务团期看板（#7324）的语义正好相反，两个列表不能套用同一套前端逻辑：**
|
||||
|
||||
| | 本接口（我的团） | H1 看板 `GET /v3/admin/house/group-batches` |
|
||||
|---|---|---|
|
||||
| 不传 `batchStatus` | 全部已认领团，**含 CANCELLED** | 默认四态，**不含 CANCELLED** |
|
||||
| 传 `batchStatus=CANCELLED` | **只看已流团的团**（可当「待释放」筛选用） | 被**静默丢弃**并回退默认四态 |
|
||||
|
||||
**这条为什么要紧**：「整团释放」写口 `POST .../room-plans/release-all` 仅对 `CANCELLED` 团期放行，
|
||||
而 H2 详情 `GET /v3/admin/house/group-batches/{groupBatchId}` **没有阶段闸门**（只判归属：未认领 808612 / 他人认领 808613）。
|
||||
所以拿一个 CANCELLED 团的 `groupBatchId` 去打 H2，是能打开的——**本接口就是拿到那个 id 的地方**。
|
||||
|
||||
前端 2026-09-11 曾据 H1 的过滤行为推断「整团释放按钮无任何可达路径」并提了后端需求
|
||||
（`backend-requests/2026-09/11_7324_放开H1看板batchStatus过滤CANCELLED-整团释放可达.md`）。
|
||||
那个推断在当时掌握的信息下是合理的——**缺的正是本篇漏写的这一条**，不是前端疏忽。
|
||||
|
||||
#### 请求示例
|
||||
|
||||
```json
|
||||
|
||||
在新工单中引用
屏蔽一个用户