hl-api-changelog/changelogs-v2/2026-10/02_8687_团期抢单池旧列表接口下线-删除接口-管理后台.md

schema, ticket, title, consumer, author, change_type, backend_status, gateway_status, frontend_status, frontend_owner, frontend_ref, target_release, verified_at, status_note, updated_at, base

schema	ticket	title	consumer	author	change_type	backend_status	gateway_status	frontend_status	frontend_owner	frontend_ref	target_release	verified_at	status_note	updated_at	base
hl-changelog/v2	8687	删除团期抢单池旧列表接口（GET /v3/admin/order/grab-pool/group-batches）	admin	wx(GIT)	删除接口	deployed	not_required	not_required						2026-10-02	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	行列表
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	团期创建时间

请求示例

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 为示例用值。

{
  "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）。

错误响应

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

联系人

• 后端负责人: @wx