docs(changelog): #8687 删除团期抢单池旧列表接口 GET grab-pool/group-batches

替代接口 GET /v3/admin/order/house-allocation/group-batches（status=pendingClaim 复刻旧口径）。 Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
2026-10-02 14:22:02 +08:00
@@ -0,0 +1,317 @@
+---
+schema: "hl-changelog/v2"
+ticket: "8687"
+title: "删除团期抢单池旧列表接口（GET /v3/admin/order/grab-pool/group-batches）"
+consumer: "admin"
+author: "wx(GIT)"
+change_type: "删除接口"
+backend_status: "deployed"
+gateway_status: "not_required"
+frontend_status: "not_required"
+frontend_owner: ""
+frontend_ref: ""
+target_release: ""
+verified_at: ""
+status_note: ""
+updated_at: "2026-10-02"
+base: "dev-v3"
+---
+
+# 删除团期抢单池旧列表接口
+
+> **存放目录**: 二期 → `changelogs-v2/2026-10/`
+>
+> **服务**: hl-order-service-v3
+> **Issue**: #8687
+> **日期**: 2026-10-02
+> **影响范围**: 管理后台团期抢单池旧列表页的数据来源
+
+---
+
+## ⚠️ 关键变化
+
+- 路由 `GET /v3/admin/order/grab-pool/group-batches`（`HouseGroupGrabAdminController.listGrabPool`）已删除，服务端不再有该路由映射。调用时 HTTP 状态仍为 200（HL 业务失败统一走 200），响应体业务码 `code=404`：`{"code":404,"message":"接口不存在: GET /v3/admin/order/grab-pool/group-batches","data":null,"success":false}`。
+- **替代接口**：`GET /v3/admin/order/house-allocation/group-batches`（`HouseAllocationListAdminController.listGroupBatches`，#8375/#8491 已上线）；复刻旧列表口径传 `status=pendingClaim`（不需要再额外传 `batchStatus=RESOURCE_PREPARING`，两者同源于 `GroupBatchService.requirementConfirmableStatuses()`）。
+- 同一控制器下 4 个团级写口（整团认领 `claim` / 释放 `release` / 接管 `takeover` / 转交 `transfer`）路径与行为均不变。
+- hl-ui（`origin/v2.1`）的 `grab-pool-group.js` 对旧 GET 路径零调用（该文件自身注释已记载两个读口随 #8375 改版下线），无需前端联动改动。
+
+---
+
+## 一、背景
+
+旧接口 `listGrabPool` 在 #8375 房务配房列表改版后已标 `@Deprecated`，继任者 `GET /v3/admin/order/house-allocation/group-batches` 自 #8375/#8491 起已承载同一批团期列表展示（待整团认领 + 已整团认领合表）。本次（#8687）删除旧路由与其专属 VO（`HouseGroupGrabPoolPageReqVO`、`HouseGroupGrabPoolItemRespVO`），以及服务层 `HouseGroupGrabService.listGrabPool` 与配套查询 DTO `HouseGrabPoolQuery`。
+
+---
+
+## 二、变更接口清单
+
+| # | 接口 | 方法 | 路径 | 变更类型 | 说明 |
+|---|------|------|------|----------|------|
+| 1 | 团期抢单池列表（旧） | GET | `/v3/admin/order/grab-pool/group-batches` | 删除 | 改用 house-allocation/group-batches |
+
+---
+
+## 三、接口详情
+
+本接口已删除。下表记录的是**删除前**的契约，供前端清理调用点、核对与替代接口的字段映射。字段名、类型、校验文案均取自删除前源码；服务端已无该路由映射，调用返回 HTTP 200 + 业务码 `code=404`（`接口不存在: GET /v3/admin/order/grab-pool/group-batches`）。
+
+### 1. 团期抢单池列表（旧） `GET /v3/admin/order/grab-pool/group-batches`
+
+**VO**: `HouseGroupGrabPoolPageReqVO → PageResult<HouseGroupGrabPoolItemRespVO>`（均已随本单删除）
+
+#### 使用场景
+
+删除前：房务在团期抢单池页查看未被整团认领、需求已整体确认、阶段为「资源准备中」的团期（整团一行）。现改为调用 `GET /v3/admin/order/house-allocation/group-batches?status=pendingClaim`。
+
+#### 入参
+
+| 字段 | 位置 | 类型 | 必填 | 约束 | 说明 |
+|------|------|------|------|------|------|
+| keyword | Query | String | ❌ | ≤32 字 | 团期号 / 产品名模糊搜索 |
+| productId | Query | Long | ❌ | - | 产品 ID 精确过滤 |
+| batchStatus | Query | String | ❌ | 只接受 `RESOURCE_PREPARING` | 传其它值 400 |
+| departDateFrom | Query | LocalDate | ❌ | - | 出发日下界（含） |
+| departDateTo | Query | LocalDate | ❌ | - | 出发日上界（含） |
+| page | Query | Integer | ❌ | ≥1，默认 1 | 页码 |
+| pageSize | Query | Integer | ❌ | 1~100，默认 20 | 每页条数 |
+| sortBy | Query | String | ❌ | 默认 `departDate,asc`，可切 `createTime,desc` | 排序 |
+
+#### 出参
+
+`Result<PageResult<HouseGroupGrabPoolItemRespVO>>`
+
+| 字段 | 类型 | 说明 |
+|------|------|------|
+| records | List<HouseGroupGrabPoolItemRespVO> | 行列表 |
+| total | int | 总条数 |
+| page | int | 回显页码 |
+| pageSize | int | 回显每页条数 |
+| records[].groupBatchId | String（Long 转字符串） | 团期主订单 ID |
+| records[].batchNo | String | 运营团期号 |
+| records[].productId | String（Long 转字符串） | 产品 ID |
+| records[].productName | String | 产品名快照 |
+| records[].batchName | String | 班期名快照 |
+| records[].batchLabel | String | 第 N 期快照 |
+| records[].batchStatus | String | 团期阶段 code（本接口恒为 `RESOURCE_PREPARING`） |
+| records[].batchStatusLabel | String | 团期阶段中文（恒为「资源准备中」） |
+| records[].departDate | LocalDate | 出发日期 |
+| records[].endDate | LocalDate | 结束日期 |
+| records[].enrollDeadline | LocalDate | 报名截止日 |
+| records[].enrolledRooms | Integer | 已报名房数 |
+| records[].enrolledPeople | Integer | 已报名人数 |
+| records[].activeOrderCount | Integer | 活跃子订单数（排除 CANCELLED） |
+| records[].hotelOrderCount | Integer | 已放行到房务的需房户数 |
+| records[].hotelReady | Boolean | 团期酒店资源是否已就绪 |
+| records[].daysToDepart | Integer | 今天到出发日天数 |
+| records[].urgencyLevel | String | 紧急度 code（NORMAL/URGENT/CRITICAL） |
+| records[].urgencyLabel | String | 紧急度中文 |
+| records[].createTime | LocalDateTime | 团期创建时间 |
+
+#### 请求示例
+
+```http
+GET /v3/admin/order/grab-pool/group-batches?page=1&pageSize=20
+```
+
+#### 响应示例
+
+字段值取自 2026-10-02 11:13 测试服 `house-allocation/group-batches` 实测返回中的一行（该团当时阶段为 `RESOURCE_PREPARING`），按旧接口的 20 个字段裁剪展示；容器层 `total`/`page`/`pageSize` 为示例用值。
+
+```json
+{
+  "code": 200,
+  "message": "成功",
+  "data": {
+    "records": [
+      {
+        "groupBatchId": "2104838272570245121",
+        "batchNo": "T26-7574",
+        "productId": "2101499109901778946",
+        "productName": "jw测试产品",
+        "batchName": "11月10日阿尔山温泉雪国5日游",
+        "batchLabel": "4",
+        "batchStatus": "RESOURCE_PREPARING",
+        "batchStatusLabel": "资源准备中",
+        "departDate": "2026-11-10",
+        "endDate": "2026-11-16",
+        "enrollDeadline": "2026-11-09",
+        "enrolledRooms": 0,
+        "enrolledPeople": 0,
+        "activeOrderCount": 0,
+        "hotelOrderCount": 0,
+        "hotelReady": false,
+        "daysToDepart": 39,
+        "urgencyLevel": "NORMAL",
+        "urgencyLabel": "正常",
+        "createTime": "2026-09-29 15:38:45"
+      }
+    ],
+    "total": 1,
+    "page": 1,
+    "pageSize": 20
+  },
+  "success": true
+}
+```
+
+#### 空数据 / 降级响应
+
+接口已删除，无空数据或降级形态可约定。删除后任何入参都返回 HTTP 200 + `{"code":404,"message":"接口不存在: GET /v3/admin/order/grab-pool/group-batches","data":null,"success":false}`（2026-10-02 部署 `ca1b590d7` 后实测）。删除前，无命中记录时实测返回 `{"records":[],"total":0,"page":1,"pageSize":5}`（2026-10-02 11:12，提交 `a65c53ebbc`）。
+
+#### 错误响应
+
+```json
+{
+  "code": 400,
+  "message": "batchStatus 只接受 RESOURCE_PREPARING",
+  "data": null,
+  "success": false
+}
+```
+
+| code | message | 触发 |
+|------|---------|------|
+| 400 | keyword 长度不能超过 32 字 / batchStatus 只接受 RESOURCE_PREPARING / page 必须大于等于 1 / pageSize 最大 100 | 删除前的入参校验 |
+| 808090 | 未登录或非房务角色，无权操作 | 删除前：非 ROOM_MANAGER / SUPER_ADMIN 访问（零角色 token 放行） |
+
+#### 业务边界
+
+- 服务端已无该路由映射，调用返回 HTTP 200 + 业务码 `code=404`；调用点一律移除。
+- 替代接口 `GET /v3/admin/order/house-allocation/group-batches` 的 `status=pendingClaim` 分支复刻本接口口径（未被整团认领 + 需求已整体确认 + 阶段在可确认集合内，当前该集合只有 `RESOURCE_PREPARING`，单源 `GroupBatchService.requirementConfirmableStatuses()`），不需要额外传 `batchStatus`。
+- 替代接口的 `batchStatus` 若显式传值，接受团期九态任一（不再锁定 `RESOURCE_PREPARING`），旧接口「传其它值 400」的收紧校验不再复现。
+
+---
+
+## 四、契约约束与正确调用方式
+
+### ✅ 正确 / ❌ 错误 payload 对照
+
+| 场景 | payload |
+|------|---------|
+| ❌ 团期抢单池列表 | `GET /v3/admin/order/grab-pool/group-batches` → 路由已删除，业务码 `code=404`（接口不存在） |
+| ✅ 团期抢单池列表 | `GET /v3/admin/order/house-allocation/group-batches?status=pendingClaim` |
+
+### 字段迁移
+
+- 响应容器从 `PageResult`（`records`/`total`/`page`/`pageSize`）换成 `HouseAllocationGroupPageRespVO`（`list`/`total`/`stats`），字段名不同，且新容器不回显 `page`/`pageSize`。
+- 旧 20 个行字段在新响应行 `HouseAllocationGroupRespVO` 中逐一同名存在（见六.6），可按原字段名直接取值。
+- 新增的 `requirementConfirmed`/`houseClaimerId`/`houseClaimerName`/`houseClaimedAt`/`isMine`/`canStartAllocation`/`taskKind`/`taskKindLabel`/`unreadCount`/`readOnly`/`readOnlyReason` 是旧接口没有的扩展字段（旧池列表语义上只展示未认领团，没有认领人信息）。
+
+---
+
+## 五、数据库行为
+
+本次清单仅涉及只读 GET 的删除，不涉及任何写入路径。
+
+| 前端提交 | 写入位置 | 行为 |
+|----------|----------|------|
+| 无 | 无 | 本接口为只读，不涉及写入 |
+
+---
+
+## 六、边界行为
+
+- 路由已从服务端删除，调用返回 HTTP 200 + 业务码 `code=404`（`接口不存在`）；调用点一律移除，不要按这个返回体做分支判断。
+- 同控制器 4 个写口（claim/release/takeover/transfer）未受影响，路径、错误码（808090 等）、角色门全部不变。
+- 替代接口的角色门与旧接口等价：`ROOM_MANAGER` / `SUPER_ADMIN` 放行，零角色 token（网关未透传 `X-Admin-Role`）放行，其余角色 808090。
+
+---
+
+## 六.5 枚举
+
+### 团期阶段 batchStatus（`GroupBatchStatus`）
+
+**所属字段**: 旧接口 `HouseGroupGrabPoolPageReqVO.batchStatus`（入参，仅接受 `RESOURCE_PREPARING` 一值）/ 替代接口 `HouseAllocationGroupPageReqVO.batchStatus`（入参，接受全部九态）与两者行内 `batchStatus`/`batchStatusLabel`
+**类型**: `String`
+
+| 值 | 中文 | 说明 |
+|----|------|------|
+| `RECRUITING` | 招募中 | 旧接口传此值 400，替代接口可传 |
+| `RESOURCE_PREPARING` | 资源准备中 | 两接口唯一共同的「可认领」阶段 |
+| `MATERIAL_PREPARING` | 物料准备中 | 旧接口传此值 400，替代接口可传 |
+| `PENDING_DEPARTURE` | 待出发 | 同上 |
+| `TRAVELLING` | 出行中 | 同上 |
+| `PENDING_REVIEW` | 待核单 | 同上（#8516 由 `TRIP_FINISHED` 改名，旧值仍兼容） |
+| `REVIEWING` | 核单中 | 同上 |
+| `SETTLED` | 已结算 | 同上 |
+| `CANCELLED` | 已取消 | 同上 |
+
+---
+
+## 六.6、修改前后对比
+
+### 字段级对比
+
+| 字段 | 改前（旧接口） | 改后（替代接口） |
+|------|------|------|
+| 响应容器 | `PageResult`：`records`/`total`/`page`/`pageSize` | `HouseAllocationGroupPageRespVO`：`list`/`total`/`stats`，不回显 page/pageSize |
+| `groupBatchId`/`batchNo`/`productId`/`productName`/`batchName`/`batchLabel`/`batchStatus`/`batchStatusLabel`/`departDate`/`endDate`/`enrollDeadline`/`enrolledRooms`/`enrolledPeople`/`activeOrderCount`/`hotelOrderCount`/`hotelReady`/`daysToDepart`/`urgencyLevel`/`urgencyLabel`/`createTime` | 有（20 字段） | 同名字段原样保留 |
+| `requirementConfirmed`/`houseClaimerId`/`houseClaimerName`/`houseClaimedAt`/`isMine`/`canStartAllocation`/`taskKind`/`taskKindLabel`/`unreadCount`/`readOnly`/`readOnlyReason` | 无 | 新增 11 个字段 |
+| 入参 `batchStatus` 取值范围 | 仅 `RESOURCE_PREPARING`，其余 400 | 团期九态任一 |
+| 入参 `scope`/`status` | 无（隐含只看未认领 + RESOURCE_PREPARING） | 新增，`status=pendingClaim` 复刻旧默认口径 |
+
+### 行为级对比
+
+| 行为 | 改前 | 改后 |
+|------|------|------|
+| 调用旧路由 | 返回分页列表 | 路由已删除，HTTP 200 + 业务码 `code=404`（接口不存在） |
+| 查看待整团认领的团期 | 固定只看 `RESOURCE_PREPARING` 一个阶段 | 固定看 `requirementConfirmableStatuses()`（当前等价，单源可变） |
+
+---
+
+## 六.7、影响评估
+
+- **是否破坏向后兼容**: 是。路由删除，仍调用旧路径的代码会收到业务码 `code=404`（接口不存在）。
+- **前端是否必须同步上线**: 否——经 hl-ui `origin/v2.1` 核查，`grab-pool-group.js` 对本路径零调用（该文件自身注释记载两个读口已随 #8375 改版下线），现网没有调用点需要跟随本单改动。
+- **残留调用点清理**: 若历史分支仍保留对旧路径的调用、或按 `records`/`page`/`pageSize` 解析响应的代码，需改为按 `list`/`stats` 解析替代接口。
+
+---
+
+## 七、不影响范围
+
+- **仅影响**: 调用 `GET /v3/admin/order/grab-pool/group-batches` 的代码（现网 hl-ui 已零调用）。
+- **零影响**:
+  - 同控制器 4 个写口：`POST .../group-batches/{groupBatchId}/claim`、`.../release`、`.../takeover`、`.../transfer`
+  - 替代接口 `GET /v3/admin/order/house-allocation/group-batches` 与 `GET /v3/admin/order/house-allocation/households`
+  - 小程序与 H5
+
+---
+
+## 八、测试环境已验证
+
+测试服环境，2026-10-02，经网关调用。
+
+```
+删除前（hl-order-service-v3 提交 a65c53ebbc）
+GET /v3/admin/order/grab-pool/group-batches?page=1&pageSize=5
+  → HTTP 200，code 200，records 为空（当时测试数据里没有满足旧池条件的团），11:12 实测
+GET /v3/admin/order/house-allocation/group-batches?scope=all&page=1&pageSize=5（替代接口）
+  → HTTP 200，code 200，total=8，11:13 实测；三节响应示例的字段值取自这次返回的其中一行
+
+删除后（hl-order-service-v3 提交 ca1b590d7，13:25 部署，两个实例均已重启）
+GET /v3/admin/order/grab-pool/group-batches?page=1&pageSize=5
+  → HTTP 200，{"code":404,"message":"接口不存在: GET /v3/admin/order/grab-pool/group-batches","data":null,"success":false}
+GET /v3/admin/order/house-allocation/group-batches?scope=all&page=1&pageSize=5（同一 token）
+  → HTTP 200，code 200，total=8，第 1 页 5 个 groupBatchId 及顺序与删除前相同；
+    只有 isMine / readOnly / readOnlyReason 不同，这三个字段随查看者账号变化，两次请求用的账号不同
+POST /v3/admin/order/grab-pool/group-batches/{groupBatchId}/release、/claim、/release
+  → 均 HTTP 200，code 200，库里团级认领人按 原认领人 → 空 → admin → 空 变化；
+    最后用 /takeover 把认领人还原为原认领人
+```
+
+验证身份：超管测试账号。
+
+---
+
+## 十、相关文档
+
+- 继任端点源码：`HouseAllocationListAdminController.listGroupBatches` / `HouseAllocationListService.pageGroupBatches`
+- 前置变更：#8375（房务去掉抢单池，配房并入房务管家订单列表，继任端点上线）、#8491（房务控制台；其 I-24 删除了另外 4 个旧抢单池读口，本单删除的是剩下的这一个）
+
+## 关联 / 联系人
+
+### 链接
+- **Issue**: [#8687](https://git.1814.love:8443/wx/HL/issues/8687)
+
+### 联系人
+- **后端负责人**: @wx