From c5b40bb83e2cc36fad29c5a1f8036a439f402e1e Mon Sep 17 00:00:00 2001 From: API Changelog Bot Date: Fri, 11 Sep 2026 10:37:49 +0800 Subject: [PATCH] =?UTF-8?q?docs:=20=E7=AD=94=E5=A4=8D=E5=89=8D=E7=AB=AF=20?= =?UTF-8?q?#7324=20=E5=90=8E=E7=AB=AF=E9=9C=80=E6=B1=82=EF=BC=88=E5=90=8E?= =?UTF-8?q?=E7=AB=AF=E9=9B=B6=E6=94=B9=E5=8A=A8=EF=BC=89+=20=E8=A1=A5=20#7?= =?UTF-8?q?322=20=E6=88=91=E7=9A=84=E5=9B=A2=E4=B8=8D=E8=BF=87=E6=BB=A4=20?= =?UTF-8?q?batch=5Fstatus?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 前端据 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 --- ...看板batchStatus过滤CANCELLED-整团释放可达.md | 78 ++++++++++++++++++- ...期整团抢单与抢单池分流-新增接口-管理后台.md | 30 ++++++- 2 files changed, 104 insertions(+), 4 deletions(-) diff --git a/backend-requests/2026-09/11_7324_放开H1看板batchStatus过滤CANCELLED-整团释放可达.md b/backend-requests/2026-09/11_7324_放开H1看板batchStatus过滤CANCELLED-整团释放可达.md index 703d6e7d..c03f7576 100644 --- a/backend-requests/2026-09/11_7324_放开H1看板batchStatus过滤CANCELLED-整团释放可达.md +++ b/backend-requests/2026-09/11_7324_放开H1看板batchStatus过滤CANCELLED-整团释放可达.md @@ -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」一条。** diff --git a/changelogs-v2/2026-09/10_7322_团期整团抢单与抢单池分流-新增接口-管理后台.md b/changelogs-v2/2026-09/10_7322_团期整团抢单与抢单池分流-新增接口-管理后台.md index 145fb737..69f26b53 100644 --- a/changelogs-v2/2026-09/10_7322_团期整团抢单与抢单池分流-新增接口-管理后台.md +++ b/changelogs-v2/2026-09/10_7322_团期整团抢单与抢单池分流-新增接口-管理后台.md @@ -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