---
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