615 行
26 KiB
Markdown
615 行
26 KiB
Markdown
---
|
||
schema: "hl-changelog/v2"
|
||
ticket: "8491"
|
||
title: "房务旧列表接口下线：抢单池列表、我的接单、组长全部已抢订单、我的团"
|
||
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-09-30"
|
||
base: "dev-v3"
|
||
---
|
||
|
||
# 房务旧列表: 下线 4 个已废弃的管理端列表接口（抢单池列表 / 我的接单 / 组长全部已抢订单 / 我的团）
|
||
|
||
> **存放目录**: 二期 → `changelogs-v2/2026-09/`
|
||
>
|
||
> **服务**: hl-order-service-v3
|
||
> **Issue**: #8491
|
||
> **日期**: 2026-09-29
|
||
> **影响范围**: 管理后台房务旧列表页（抢单池、我的接单、组长监督视图、我的团）的数据来源
|
||
|
||
---
|
||
|
||
## ⚠️ 关键变化（非必须,本版与上版行为不同 / 纠错 / 撤销时必写）
|
||
|
||
- 以下 4 个 GET 接口从服务端删除，服务端已无这些路由映射，删除后返回形态本文不作约定，调用点一律移除：
|
||
- `GET /v3/admin/order/grab-pool/hotel-requirements`
|
||
- `GET /v3/admin/order/grab-pool/my-claims/hotel`
|
||
- `GET /v3/admin/order/grab-pool/all-claims/hotel`
|
||
- `GET /v3/admin/order/grab-pool/my-claims/group-batches`
|
||
- 替代接口：常规单统一走 `GET /v3/admin/order/house-allocation/households`，团期统一走 `GET /v3/admin/order/house-allocation/group-batches`（两者本次的字段调整见同目录修改接口文件）。
|
||
- 「房务组长」角色同步取消：原「全部已抢订单」监督视图与「我的团 scope=all」不再存在，全体房务改用替代接口的 `scope=all` 查看全部。
|
||
|
||
---
|
||
|
||
## 一、背景（选填）
|
||
|
||
这 4 个接口在 #8491 之前已标注「已废弃，改用 house-allocation 列表」，房务控制台上线两条统一列表后删除。它们的请求 / 响应 VO（`HouseMyOrderPageReqVO`、`HouseMyOrderPageRespVO`、`HouseMyOrderItemRespVO`、`HouseMyOrderStatsVO`、`HouseMyGroupPageReqVO`、`HouseMyGroupPageRespVO`、`HouseMyGroupItemRespVO`、`HouseMyGroupStatsVO`）随之删除。
|
||
|
||
---
|
||
|
||
## 二、变更接口清单
|
||
|
||
| # | 接口 | 方法 | 路径 | 变更类型 | 说明 |
|
||
|---|------|------|------|----------|------|
|
||
| 1 | 抢单池列表（常规单） | GET | `/v3/admin/order/grab-pool/hotel-requirements` | 删除 | 改用 households 列表 status=pendingClaim |
|
||
| 2 | 我的接单（常规单） | GET | `/v3/admin/order/grab-pool/my-claims/hotel` | 删除 | 改用 households 列表 scope=mine |
|
||
| 3 | 组长全部已抢订单（常规单） | GET | `/v3/admin/order/grab-pool/all-claims/hotel` | 删除 | 改用 households 列表 scope=all |
|
||
| 4 | 我的团（团期） | GET | `/v3/admin/order/grab-pool/my-claims/group-batches` | 删除 | 改用 group-batches 列表 status=claimed |
|
||
|
||
---
|
||
|
||
## 三、接口详情
|
||
|
||
本节 4 个接口均已删除。入参 / 出参表与示例记录的是**删除前**的契约，仅供前端定位与清理调用点；字段名、类型、校验文案逐一取自删除前源码，ID、日期、姓名等取值为说明用的构造值。服务端已无这些路由映射，删除后返回形态本文不作约定。
|
||
|
||
### 1. 抢单池列表（常规单） `GET /v3/admin/order/grab-pool/hotel-requirements`
|
||
|
||
**VO**: `HouseGrabPageReqVO → PageResult<HouseGrabPageItemRespVO>`（已删除接口，VO 类仍在代码中但无接口引用）
|
||
|
||
#### 使用场景
|
||
|
||
删除前：房务在抢单池页查看待认领的常规单需求。现在改为 `GET /v3/admin/order/house-allocation/households?status=pendingClaim`。
|
||
|
||
#### 入参
|
||
|
||
| 字段 | 位置 | 类型 | 必填 | 约束 | 说明 |
|
||
|------|------|------|------|------|------|
|
||
| keyword | Query | String | ❌ | ≤32 字 | 删除前：关键词 |
|
||
| productType | Query | String | ❌ | - | 删除前：产品类型 |
|
||
| productName | Query | String | ❌ | - | 删除前：产品名 |
|
||
| consultantId | Query | Long | ❌ | - | 删除前：定制师 |
|
||
| guestName | Query | String | ❌ | - | 删除前：客人姓名 |
|
||
| departDateFrom / departDateTo | Query | LocalDate | ❌ | - | 删除前：出行日期区间 |
|
||
| page | Query | Integer | ❌ | ≥1，默认 1 | 删除前：页码 |
|
||
| pageSize | Query | Integer | ❌ | 1~100，默认 20 | 删除前：每页条数 |
|
||
| sortBy | Query | String | ❌ | 默认 createTime,desc | 删除前：排序 |
|
||
|
||
#### 出参 `Result<PageResult<HouseGrabPageItemRespVO>>`
|
||
|
||
| 字段 | 类型 | 说明 |
|
||
|------|------|------|
|
||
| records | List<HouseGrabPageItemRespVO> | 删除前：行列表 |
|
||
| total | int | 删除前：总数 |
|
||
| records[].id / orderId | Long(String) | 删除前：需求 ID / 订单 ID |
|
||
| records[].orderNo / teamNo / guestName / personsDesc | String | 删除前：订单号 / 团号 / 客人 / 人数描述 |
|
||
| records[].productType / productName / productNo / route | String | 删除前：产品信息 |
|
||
| records[].departDate / nights / cities | LocalDate / Integer / List<String> | 删除前：出行日期 / 夜数 / 城市 |
|
||
| records[].totalAmount | BigDecimal(String) | 删除前：订单总额 |
|
||
| records[].consultantName / consultantId / consultantRemark | String / Long(String) / String | 删除前：定制师信息 |
|
||
| records[].requirementNote / dispatchRemark / special | String / String / List<String> | 删除前：需求备注 / 派单备注 / 特殊要求 |
|
||
| records[].requirementVersion | Integer | 删除前：需求版本 |
|
||
| records[].urgencyLevel / urgencyLabel / daysToDepart / manualUrgent | String / String / Integer / Boolean | 删除前：紧急度 |
|
||
| records[].createTime | LocalDateTime | 删除前：入池时间 |
|
||
| records[].isRework / reworkPrevClaimerName | Boolean / String | 删除前：返工标识 / 上一任认领人 |
|
||
|
||
#### 请求示例
|
||
|
||
```http
|
||
GET /v3/admin/order/grab-pool/hotel-requirements?page=1&pageSize=20
|
||
```
|
||
|
||
#### 响应示例
|
||
|
||
删除前（仅供清理对照）：
|
||
|
||
```json
|
||
{
|
||
"code": 200,
|
||
"message": "成功",
|
||
"data": {
|
||
"records": [
|
||
{
|
||
"id": "1940000000000000011",
|
||
"orderId": "1930000000000000021",
|
||
"orderNo": "26-0915",
|
||
"teamNo": "26-0920",
|
||
"guestName": "李女士一家",
|
||
"productName": "呼伦贝尔秋色 6 日",
|
||
"departDate": "2026-10-05",
|
||
"isRework": false
|
||
}
|
||
],
|
||
"total": 1,
|
||
"page": 1,
|
||
"pageSize": 20
|
||
},
|
||
"success": true
|
||
}
|
||
```
|
||
|
||
#### 空数据 / 降级响应
|
||
|
||
接口已删除，无空数据或降级形态可约定；前端移除调用点，空列表展示改由替代接口 `records` 为空时处理。
|
||
|
||
#### 错误响应
|
||
|
||
删除前（仅供清理对照）：
|
||
|
||
```json
|
||
{
|
||
"code": 400,
|
||
"message": "keyword 长度不能超过 32 字",
|
||
"data": null,
|
||
"success": false
|
||
}
|
||
```
|
||
|
||
| code | message | 触发 |
|
||
|------|---------|------|
|
||
| 400 | keyword 长度不能超过 32 字 / page 必须 ≥ 1 / pageSize 最大 100 | 删除前的入参校验 |
|
||
|
||
#### 业务边界
|
||
|
||
- 服务端已无该路由映射，删除后返回形态本文不作约定，调用点一律移除。
|
||
- 替代：`GET /v3/admin/order/house-allocation/households?status=pendingClaim`，排序可传 `sortBy=createTime,desc` 保持原默认顺序；替代接口的 `list` 字段名与本接口的 `records` 不同。
|
||
|
||
### 2. 我的接单（常规单） `GET /v3/admin/order/grab-pool/my-claims/hotel`
|
||
|
||
**VO**: `HouseMyOrderPageReqVO → HouseMyOrderPageRespVO`（均已删除）
|
||
|
||
#### 使用场景
|
||
|
||
删除前：房务查看本人已认领的常规单及状态统计。现在改为 `GET /v3/admin/order/house-allocation/households?scope=mine`。
|
||
|
||
#### 入参
|
||
|
||
| 字段 | 位置 | 类型 | 必填 | 约束 | 说明 |
|
||
|------|------|------|------|------|------|
|
||
| keyword | Query | String | ❌ | ≤32 字 | 删除前：关键词 |
|
||
| status | Query | String | ❌ | `unfinished` / `allUnfinished` / `todo` / `inProgress` / `claiming` / `pendingConfirm` / `confirmed` / `exception` / `voided` / `inInquiry` | 删除前：跟单状态（前三个都表示全部未完成） |
|
||
| productType | Query | String | ❌ | CORE / ROUTE / CUSTOM / GROUP | 删除前：产品类型 |
|
||
| productName / guestName | Query | String | ❌ | - | 删除前：模糊搜 |
|
||
| consultantId | Query | Long | ❌ | - | 删除前：定制师 |
|
||
| departDateFrom / departDateTo | Query | LocalDate | ❌ | - | 删除前：出行日期区间 |
|
||
| stayDate | Query | LocalDate | ❌ | - | 删除前：入住晚下钻 |
|
||
| claimedAtFrom / claimedAtTo | Query | LocalDateTime | ❌ | - | 删除前：认领时间区间 |
|
||
| city / hasException / hasTodo / hasUnreadMessage | Query | String / Boolean | ❌ | - | 删除前：预留字段，未实现 |
|
||
| page | Query | Integer | ❌ | ≥1，默认 1 | 删除前：页码 |
|
||
| pageSize | Query | Integer | ❌ | 1~100，默认 20 | 删除前：每页条数 |
|
||
| sortBy | Query | String | ❌ | 默认 claimedAt,desc | 删除前：排序 |
|
||
|
||
#### 出参 `Result<HouseMyOrderPageRespVO>`
|
||
|
||
| 字段 | 类型 | 说明 |
|
||
|------|------|------|
|
||
| list | List<HouseMyOrderItemRespVO> | 删除前：行列表 |
|
||
| total | Long | 删除前：总数 |
|
||
| stats | HouseMyOrderStatsVO | 删除前：inProgress / claiming / inInquiry（恒 0）/ pendingConfirm / confirmed / exception / voided |
|
||
| list[].id / orderId / consultantId / claimerId | Long(String) | 删除前：需求 / 订单 / 定制师 / 持有人 ID |
|
||
| list[].orderNo / teamNo / guestName / personsDesc / productType / productName / route | String | 删除前：订单与产品信息 |
|
||
| list[].departDate / nights / cities | LocalDate / Integer / List<String> | 删除前：出行信息 |
|
||
| list[].totalAmount | BigDecimal(String) | 删除前：订单总额 |
|
||
| list[].consultantName / claimerName / claimedAt | String / String / LocalDateTime | 删除前：定制师 / 持有人 / 认领时间 |
|
||
| list[].houseStatus | String | 删除前：**中文状态**（与 houseStatusLabel 同值） |
|
||
| list[].houseStatusLabel | String | 删除前：中文状态 |
|
||
| list[].progressDesc / hotelSummary / lastAction | String | 删除前：进度文字 / 已配酒店摘要 / 最近动作 |
|
||
| list[].exceptionCount / todoCount / unreadMessageCount | Integer | 删除前：异常数 / 待办数 / 未读留言数 |
|
||
| list[].primaryAction | HousePrimaryActionVO | 删除前：code / label / url |
|
||
| list[].voided / requirementVersion / voidReason / voidedAt | Boolean / Integer / String / LocalDateTime | 删除前：作废信息 |
|
||
|
||
#### 请求示例
|
||
|
||
```http
|
||
GET /v3/admin/order/grab-pool/my-claims/hotel?status=unfinished&page=1&pageSize=20
|
||
```
|
||
|
||
#### 响应示例
|
||
|
||
删除前（仅供清理对照）：
|
||
|
||
```json
|
||
{
|
||
"code": 200,
|
||
"message": "成功",
|
||
"data": {
|
||
"list": [
|
||
{
|
||
"id": "1940000000000000011",
|
||
"orderId": "1930000000000000021",
|
||
"orderNo": "26-0915",
|
||
"guestName": "李女士一家",
|
||
"claimerName": "张敏",
|
||
"houseStatus": "配房中",
|
||
"houseStatusLabel": "配房中",
|
||
"progressDesc": "5晚已配3晚",
|
||
"unreadMessageCount": 2,
|
||
"voided": false
|
||
}
|
||
],
|
||
"total": 1,
|
||
"stats": {
|
||
"inProgress": 1,
|
||
"claiming": 1,
|
||
"inInquiry": 0,
|
||
"pendingConfirm": 0,
|
||
"confirmed": 0,
|
||
"exception": 0,
|
||
"voided": 0
|
||
}
|
||
},
|
||
"success": true
|
||
}
|
||
```
|
||
|
||
#### 空数据 / 降级响应
|
||
|
||
接口已删除，无空数据或降级形态可约定；前端移除调用点。
|
||
|
||
#### 错误响应
|
||
|
||
删除前（仅供清理对照）：
|
||
|
||
```json
|
||
{
|
||
"code": 400,
|
||
"message": "pageSize 最大 100",
|
||
"data": null,
|
||
"success": false
|
||
}
|
||
```
|
||
|
||
| code | message | 触发 |
|
||
|------|---------|------|
|
||
| 400 | keyword 长度不能超过 32 字 / page 必须 ≥ 1 / pageSize 最大 100 | 删除前的入参校验 |
|
||
|
||
#### 业务边界
|
||
|
||
- 服务端已无该路由映射，删除后返回形态本文不作约定，调用点一律移除。
|
||
- 替代接口的 `houseStatus` 是枚举码（PENDING_CLAIM / CLAIMING / PENDING_FINALIZE / CONFIRMED / EXCEPTION），中文取 `houseStatusLabel`；按本接口 `houseStatus` 中文做判断的代码要改。
|
||
- 替代接口 `scope` 默认 `all`，查本人认领的单必须显式传 `scope=mine`。
|
||
- 本接口的 `voided` / `voidReason` / `voidedAt` / `progressDesc` / `hotelSummary` / `lastAction` 在替代列表中没有对应字段。
|
||
|
||
### 3. 组长全部已抢订单（常规单） `GET /v3/admin/order/grab-pool/all-claims/hotel`
|
||
|
||
**VO**: `HouseMyOrderPageReqVO → HouseMyOrderPageRespVO`（均已删除）
|
||
|
||
#### 使用场景
|
||
|
||
删除前：房务组长 / 超管的只读监督视图，查看全部已认领常规单。「房务组长」角色已取消，全体房务改用 `GET /v3/admin/order/house-allocation/households?scope=all`。
|
||
|
||
#### 入参
|
||
|
||
| 字段 | 位置 | 类型 | 必填 | 约束 | 说明 |
|
||
|------|------|------|------|------|------|
|
||
| keyword | Query | String | ❌ | ≤32 字 | 删除前：同接口 2 |
|
||
| status | Query | String | ❌ | 同接口 2 | 删除前：跟单状态 |
|
||
| page | Query | Integer | ❌ | ≥1，默认 1 | 删除前：页码 |
|
||
| pageSize | Query | Integer | ❌ | 1~100，默认 20 | 删除前：每页条数 |
|
||
| 其余筛选 | Query | - | ❌ | 同接口 2 | 删除前：与接口 2 共用同一请求 VO |
|
||
|
||
#### 出参 `Result<HouseMyOrderPageRespVO>`
|
||
|
||
| 字段 | 类型 | 说明 |
|
||
|------|------|------|
|
||
| list | List<HouseMyOrderItemRespVO> | 删除前：同接口 2，行内 claimerId / claimerName 标该单属哪个房务 |
|
||
| total | Long | 删除前：总数 |
|
||
| stats | HouseMyOrderStatsVO | 删除前：同接口 2 |
|
||
|
||
#### 请求示例
|
||
|
||
```http
|
||
GET /v3/admin/order/grab-pool/all-claims/hotel?page=1&pageSize=20
|
||
```
|
||
|
||
#### 响应示例
|
||
|
||
删除前（仅供清理对照）：
|
||
|
||
```json
|
||
{
|
||
"code": 200,
|
||
"message": "成功",
|
||
"data": {
|
||
"list": [
|
||
{
|
||
"id": "1940000000000000012",
|
||
"orderId": "1930000000000000022",
|
||
"orderNo": "26-0916",
|
||
"claimerId": "30002",
|
||
"claimerName": "王芳",
|
||
"houseStatus": "待最终确认",
|
||
"houseStatusLabel": "待最终确认"
|
||
}
|
||
],
|
||
"total": 1,
|
||
"stats": {
|
||
"inProgress": 0,
|
||
"claiming": 0,
|
||
"inInquiry": 0,
|
||
"pendingConfirm": 1,
|
||
"confirmed": 0,
|
||
"exception": 0,
|
||
"voided": 0
|
||
}
|
||
},
|
||
"success": true
|
||
}
|
||
```
|
||
|
||
#### 空数据 / 降级响应
|
||
|
||
接口已删除，无空数据或降级形态可约定；前端移除调用点。
|
||
|
||
#### 错误响应
|
||
|
||
删除前（仅供清理对照）：
|
||
|
||
```json
|
||
{
|
||
"code": 808092,
|
||
"message": "无权查看全部房务订单（仅房务组长或超管可查看）",
|
||
"data": null,
|
||
"success": false
|
||
}
|
||
```
|
||
|
||
| code | message | 触发 |
|
||
|------|---------|------|
|
||
| 808092 | 无权查看全部房务订单（仅房务组长或超管可查看） | 删除前：非组长 / 超管访问；该码已删除，不复用 |
|
||
| 400 | keyword 长度不能超过 32 字 / page 必须 ≥ 1 / pageSize 最大 100 | 删除前的入参校验 |
|
||
|
||
#### 业务边界
|
||
|
||
- 服务端已无该路由映射，删除后返回形态本文不作约定，调用点一律移除。
|
||
- 替代接口 `scope=all` 对全体房务开放；行内 `claimerName` 与 `readOnly` / `readOnlyReason` 标出该单由谁处理。
|
||
|
||
### 4. 我的团（团期） `GET /v3/admin/order/grab-pool/my-claims/group-batches`
|
||
|
||
**VO**: `HouseMyGroupPageReqVO → HouseMyGroupPageRespVO`（均已删除）
|
||
|
||
#### 使用场景
|
||
|
||
删除前：房务查看本人整团认领的团期（scope=mine），组长 / 超管可看全部已认领团（scope=all）。现在改为 `GET /v3/admin/order/house-allocation/group-batches?status=claimed`，配合 `scope=mine` 或 `scope=all`。
|
||
|
||
#### 入参
|
||
|
||
| 字段 | 位置 | 类型 | 必填 | 约束 | 说明 |
|
||
|------|------|------|------|------|------|
|
||
| scope | Query | String | ❌ | mine / all，默认 mine | 删除前：all 仅组长 / 超管 |
|
||
| keyword | Query | String | ❌ | ≤32 字 | 删除前：团期号 / 产品名 |
|
||
| batchStatus | Query | String | ❌ | 团期九态之一 | 删除前：团期状态 |
|
||
| needsReconfirm | Query | Boolean | ❌ | - | 删除前：只看需求待重新确认的团 |
|
||
| departDateFrom / departDateTo | Query | LocalDate | ❌ | - | 删除前：出发日区间 |
|
||
| claimedAtFrom / claimedAtTo | Query | LocalDateTime | ❌ | - | 删除前：认领时间区间 |
|
||
| page | Query | Integer | ❌ | ≥1，默认 1 | 删除前：页码 |
|
||
| pageSize | Query | Integer | ❌ | 1~100，默认 20 | 删除前：每页条数 |
|
||
| sortBy | Query | String | ❌ | 默认 claimedAt,desc，可切 departDate,asc | 删除前：排序 |
|
||
|
||
#### 出参 `Result<HouseMyGroupPageRespVO>`
|
||
|
||
| 字段 | 类型 | 说明 |
|
||
|------|------|------|
|
||
| total | Long | 删除前：总数 |
|
||
| stats | HouseMyGroupStatsVO | 删除前：total / needsReconfirm / cancelled（后两项在 total 超过 500 时为 null） |
|
||
| list | List<HouseMyGroupItemRespVO> | 删除前：行列表 |
|
||
| list[].groupBatchId / productId | Long(String) | 删除前：团期 / 产品 ID |
|
||
| list[].batchNo / productName / batchName / batchLabel / batchStatus / batchStatusLabel | String | 删除前：团期信息 |
|
||
| list[].departDate / endDate / enrollDeadline | LocalDate | 删除前：日期 |
|
||
| list[].enrolledRooms / enrolledPeople / activeOrderCount / hotelOrderCount / daysToDepart | Integer | 删除前：计数 |
|
||
| list[].hotelReady | Boolean | 删除前：酒店是否就绪 |
|
||
| list[].urgencyLevel / urgencyLabel | String | 删除前：紧急度 |
|
||
| list[].createTime | LocalDateTime | 删除前：创建时间 |
|
||
| list[].houseClaimerId / houseClaimerName / houseClaimedAt | Long(String) / String / LocalDateTime | 删除前：整团认领人与时间 |
|
||
| list[].requirementConfirmed | Boolean | 删除前：需求整体确认标记 |
|
||
|
||
#### 请求示例
|
||
|
||
```http
|
||
GET /v3/admin/order/grab-pool/my-claims/group-batches?scope=mine&page=1&pageSize=20
|
||
```
|
||
|
||
#### 响应示例
|
||
|
||
删除前（仅供清理对照）：
|
||
|
||
```json
|
||
{
|
||
"code": 200,
|
||
"message": "成功",
|
||
"data": {
|
||
"total": 1,
|
||
"stats": {
|
||
"total": 1,
|
||
"needsReconfirm": 0,
|
||
"cancelled": 0
|
||
},
|
||
"list": [
|
||
{
|
||
"groupBatchId": "1950000000000000031",
|
||
"batchNo": "GB261005",
|
||
"batchName": "呼伦贝尔秋色 6 日",
|
||
"batchStatus": "PENDING_DEPARTURE",
|
||
"departDate": "2026-10-05",
|
||
"houseClaimerId": "30001",
|
||
"houseClaimerName": "张敏",
|
||
"houseClaimedAt": "2026-09-20 10:00:00",
|
||
"requirementConfirmed": true
|
||
}
|
||
]
|
||
},
|
||
"success": true
|
||
}
|
||
```
|
||
|
||
#### 空数据 / 降级响应
|
||
|
||
接口已删除，无空数据或降级形态可约定；前端移除调用点。
|
||
|
||
#### 错误响应
|
||
|
||
删除前（仅供清理对照）：
|
||
|
||
```json
|
||
{
|
||
"code": 808092,
|
||
"message": "无权查看全部房务订单（仅房务组长或超管可查看）",
|
||
"data": null,
|
||
"success": false
|
||
}
|
||
```
|
||
|
||
| code | message | 触发 |
|
||
|------|---------|------|
|
||
| 808092 | 无权查看全部房务订单（仅房务组长或超管可查看） | 删除前：普通房务传 scope=all；该码已删除，不复用 |
|
||
| 400 | keyword 长度不能超过 32 字 / page 必须大于等于 1 / pageSize 最大 100 | 删除前的入参校验 |
|
||
|
||
#### 业务边界
|
||
|
||
- 服务端已无该路由映射，删除后返回形态本文不作约定，调用点一律移除。
|
||
- 替代接口没有 `needsReconfirm` 筛选；行字段 `requirementConfirmed` 仍在，可在前端按它标记。
|
||
- 替代接口的统计为 `pendingClaim` / `claimed` / `all`，没有 needsReconfirm / cancelled 计数。
|
||
- 替代接口 `scope` 默认 `all`，查本人整团认领的团必须显式传 `scope=mine`。
|
||
|
||
---
|
||
|
||
## 四、契约约束与正确调用方式（接口类必写）
|
||
|
||
> 本节只写**后端接受/拒绝 payload 的规则**,不写 UI 渲染建议。
|
||
|
||
### ✅ 正确 / ❌ 错误 payload 对照
|
||
|
||
| 场景 | payload |
|
||
|------|---------|
|
||
| ❌ 抢单池列表 | `GET /v3/admin/order/grab-pool/hotel-requirements` → 路由已删除 |
|
||
| ✅ 抢单池列表 | `GET /v3/admin/order/house-allocation/households?status=pendingClaim&sortBy=createTime,desc` |
|
||
| ❌ 我的接单 | `GET /v3/admin/order/grab-pool/my-claims/hotel` → 路由已删除 |
|
||
| ✅ 我的接单 | `GET /v3/admin/order/house-allocation/households?scope=mine&status=unfinished` |
|
||
| ❌ 全部已抢订单 | `GET /v3/admin/order/grab-pool/all-claims/hotel` → 路由已删除 |
|
||
| ✅ 全部已抢订单 | `GET /v3/admin/order/house-allocation/households?scope=all&status=unfinished` |
|
||
| ❌ 我的团 | `GET /v3/admin/order/grab-pool/my-claims/group-batches` → 路由已删除 |
|
||
| ✅ 我的团 | `GET /v3/admin/order/house-allocation/group-batches?scope=mine&status=claimed` |
|
||
|
||
### 切换状态时的必要动作
|
||
|
||
- 替代接口的状态筛选取值与旧接口不同：常规单 `status` 为 pendingClaim / unfinished（默认）/ claiming / pendingConfirm / confirmed / exception，空串=全部；团期 `status` 为 pendingClaim / claimed，不传=两者都要。旧值（`allUnfinished` / `todo` / `inProgress` / `voided` / `inInquiry`）传给替代接口会被入参校验拒绝（400）。
|
||
- 两个替代接口的 `scope` 默认都是 `all`；原「我的接单」「我的团」对应的调用必须显式带 `scope=mine`。
|
||
- 常规单替代接口 `sortBy` 只接受 departDate,asc（默认）/ createTime,desc / claimedAt,desc；团期替代接口只接受 departDate,asc（默认）/ claimedAt,desc / createTime,desc。
|
||
|
||
---
|
||
|
||
## 五、数据库行为（涉及写操作时必写）
|
||
|
||
| 前端提交 | 写入位置 | 行为 |
|
||
|----------|----------|------|
|
||
| 4 个已删除接口均为只读 GET | 无 | 不涉及写入 |
|
||
|
||
**显式 SET NULL 说明**: 不涉及。
|
||
|
||
---
|
||
|
||
## 六、边界行为
|
||
|
||
- 4 条路由已从服务端删除，删除后返回形态本文不作约定，前端不得依赖任何返回来判断，调用点一律移除。
|
||
- 替代接口的读权限：全体房务（ROOM_MANAGER / SUPER_ADMIN）可用 `scope=all`；非房务角色返回 808090「未登录或非房务角色，无权操作」。
|
||
- 808091、808092 随组长角色一并删除，不复用。
|
||
|
||
---
|
||
|
||
## 六.5、枚举 / 数据字典（接口出现枚举时必写）
|
||
|
||
### 替代接口 houseStatus（HouseStateEnum）
|
||
|
||
**所属字段**: `HouseAllocationHouseholdRespVO.houseStatus`（替代旧接口 `HouseMyOrderItemRespVO.houseStatus` 的中文值） / **类型**: `String`
|
||
|
||
| 值 | 中文 | 说明 |
|
||
|----|------|------|
|
||
| `PENDING_CLAIM` | 待配房 | 尚未认领 |
|
||
| `CLAIMING` | 配房中 | 已认领、配房进行中 |
|
||
| `PENDING_FINALIZE` | 待最终确认 | 配房待最终确认 |
|
||
| `CONFIRMED` | 已完成 | 配房完成 |
|
||
| `EXCEPTION` | 异常 | 异常 |
|
||
|
||
---
|
||
|
||
## 六.6、修改前后对比（修改/删除接口必写）
|
||
|
||
### 字段级对比
|
||
|
||
| 字段 | 改前 | 改后 |
|
||
|------|------|------|
|
||
| 我的接单 `list[].houseStatus` | 中文状态 | 替代接口为枚举码，中文取 `houseStatusLabel` |
|
||
| 我的接单 `list[].unreadMessageCount` | 未读留言数 | 替代接口 `unreadCount`（房务会话未读数） |
|
||
| 我的接单 `stats` | inProgress / claiming / inInquiry / pendingConfirm / confirmed / exception / voided | 替代接口 pendingClaim / claiming / pendingConfirm / confirmed / exception / unfinished / all |
|
||
| 我的接单 `progressDesc` / `hotelSummary` / `lastAction` / `voided` / `voidReason` / `voidedAt` | 有 | 替代列表无对应字段 |
|
||
| 抢单池列表 `records` | 行列表字段名 | 替代接口为 `list` |
|
||
| 我的团 `stats` | total / needsReconfirm / cancelled | 替代接口 pendingClaim / claimed / all |
|
||
| 我的团入参 `needsReconfirm` | 有 | 替代接口无；行字段 `requirementConfirmed` 保留 |
|
||
|
||
### 行为级对比
|
||
|
||
| 行为 | 改前 | 改后 |
|
||
|------|------|------|
|
||
| 调用 4 个旧列表接口 | 返回列表 | 路由已删除，返回形态本文不作约定 |
|
||
| 普通房务查看全部已认领常规单 | 808091 | 替代接口 scope=all 放行 |
|
||
| 普通房务查看全部已认领团期 | 808092 | 替代接口 scope=all 放行 |
|
||
|
||
---
|
||
|
||
## 六.7、影响评估
|
||
|
||
- **是否破坏向后兼容**: 是。4 条路由删除，仍调用的页面拿不到数据。
|
||
- **前端是否必须同步上线**: 是。服务端已无这 4 条路由，仍在调用的页面需改为替代接口。
|
||
- **前端 workaround 清理点**: 旧抢单池页、我的接单页、组长监督视图、我的团页对这 4 个路径的调用；按 `houseStatus` 中文值、`unreadMessageCount`、`inInquiry` / `voided` 统计、808091 / 808092 做的分支。
|
||
|
||
---
|
||
|
||
## 七、不影响范围（显式声明, 帮前端/QA 缩小排查面）
|
||
|
||
- **仅影响**: 管理后台调用上述 4 个路径的页面。
|
||
- **零影响**:
|
||
- 团期抢单池列表 `GET /v3/admin/order/grab-pool/group-batches` 保留（仍为废弃标注）
|
||
- 同一控制器的转单 `POST /v3/admin/order/hotel-requirements/{requirementId}/transfer` 保留（本次行为变化见同目录修改接口文件）
|
||
- 小程序与 H5
|
||
|
||
---
|
||
|
||
## 八、测试环境已验证
|
||
|
||
四个旧端点都用房务 A 身份经测试服网关调用，共三轮（00:30、00:31、01:18）。HTTP 状态恒为 200，下面的 `code` 指响应 body 里的 `code`，带 ✓ 标记。行尾 `@` 后面是当时测试服 order-v3 的部署提交，两个提交都包含本单合并提交 `7c21cf0e40`。
|
||
|
||
```
|
||
GET /v3/admin/order/grab-pool/hotel-requirements 抢单池列表（常规单） → code=404 ✓ @bdde64a3a，复测 ✓ @9c7ac9382
|
||
GET /v3/admin/order/grab-pool/my-claims/hotel 我的接单（常规单） → code=404 ✓ @bdde64a3a，复测 ✓ @9c7ac9382
|
||
GET /v3/admin/order/grab-pool/all-claims/hotel 组长全部已抢订单（常规单） → code=404 ✓ @bdde64a3a，复测 ✓ @9c7ac9382
|
||
GET /v3/admin/order/grab-pool/my-claims/group-batches 我的团（团期） → code=404 ✓ @bdde64a3a，复测 ✓ @9c7ac9382
|
||
```
|
||
|
||
验证身份：房务 A，测试专用账号。
|
||
|
||
---
|
||
|
||
## 十、相关文档
|
||
|
||
- 关联 Issue: [wx/HL#8491](https://git.1814.love:8443/wx/HL/issues/8491)
|
||
- 契约文档: `docs/order-v3/api/API-SPEC-HOUSE-V1.1.html` §12 房务控制台
|
||
- 同批变更: 同目录 `30_8491_房务控制台接口-新增接口-管理后台.md`、`30_8491_房务配房接口字段与口径调整-修改接口-管理后台.md`
|
||
|
||
## 关联 / 联系人
|
||
|
||
### 链接
|
||
|
||
- **Issue**: [#8491](https://git.1814.love:8443/wx/HL/issues/8491)
|
||
|
||
### 联系人
|
||
|
||
- **后端负责人**: @wx
|