diff --git a/changelogs-v2/2026-10/02_8687_团期抢单池旧列表接口下线-删除接口-管理后台.md b/changelogs-v2/2026-10/02_8687_团期抢单池旧列表接口下线-删除接口-管理后台.md new file mode 100644 index 00000000..40a97d00 --- /dev/null +++ b/changelogs-v2/2026-10/02_8687_团期抢单池旧列表接口下线-删除接口-管理后台.md @@ -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`(均已随本单删除) + +#### 使用场景 + +删除前:房务在团期抢单池页查看未被整团认领、需求已整体确认、阶段为「资源准备中」的团期(整团一行)。现改为调用 `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>` + +| 字段 | 类型 | 说明 | +|------|------|------| +| 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 | 团期创建时间 | + +#### 请求示例 + +```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