wx/hl-api-changelog
1
0
派生 0
代码 工单 合并请求 工作流 软件包 项目 发布 百科 活动
文件
main
hl-api-changelog/changelogs-v2/2026-09/30_8491_房务旧列表接口下线-删除接口-管理后台.md
T

26 KiB
原始文件 永久链接 Blame 文件历史

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 8491 房务旧列表接口下线：抢单池列表、我的接单、组长全部已抢订单、我的团 admin wx(GIT) 删除接口 deployed not_required not_required 2026-09-30 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 删除前：行列表
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 删除前：出行日期 / 夜数 / 城市
records[].totalAmount BigDecimal(String) 删除前：订单总额
records[].consultantName / consultantId / consultantRemark String / Long(String) / String 删除前：定制师信息
records[].requirementNote / dispatchRemark / special String / String / List 删除前：需求备注 / 派单备注 / 特殊要求
records[].requirementVersion Integer 删除前：需求版本
records[].urgencyLevel / urgencyLabel / daysToDepart / manualUrgent String / String / Integer / Boolean 删除前：紧急度
records[].createTime LocalDateTime 删除前：入池时间
records[].isRework / reworkPrevClaimerName Boolean / String 删除前：返工标识 / 上一任认领人

请求示例

GET /v3/admin/order/grab-pool/hotel-requirements?page=1&pageSize=20

响应示例

删除前（仅供清理对照）：

{
  "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 为空时处理。

错误响应

删除前（仅供清理对照）：

{
  "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 删除前：行列表
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 删除前：出行信息
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 删除前：作废信息

请求示例

GET /v3/admin/order/grab-pool/my-claims/hotel?status=unfinished&page=1&pageSize=20

响应示例

删除前（仅供清理对照）：

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

空数据 / 降级响应

接口已删除，无空数据或降级形态可约定；前端移除调用点。

错误响应

删除前（仅供清理对照）：

{
  "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 删除前：同接口 2，行内 claimerId / claimerName 标该单属哪个房务
total Long 删除前：总数
stats HouseMyOrderStatsVO 删除前：同接口 2

请求示例

GET /v3/admin/order/grab-pool/all-claims/hotel?page=1&pageSize=20

响应示例

删除前（仅供清理对照）：

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

空数据 / 降级响应

接口已删除，无空数据或降级形态可约定；前端移除调用点。

错误响应

删除前（仅供清理对照）：

{
  "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 删除前：行列表
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 删除前：需求整体确认标记

请求示例

GET /v3/admin/order/grab-pool/my-claims/group-batches?scope=mine&page=1&pageSize=20

响应示例

删除前（仅供清理对照）：

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

空数据 / 降级响应

接口已删除，无空数据或降级形态可约定；前端移除调用点。

错误响应

删除前（仅供清理对照）：

{
  "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
  • 契约文档: docs/order-v3/api/API-SPEC-HOUSE-V1.1.html §12 房务控制台
  • 同批变更: 同目录 30_8491_房务控制台接口-新增接口-管理后台.md、30_8491_房务配房接口字段与口径调整-修改接口-管理后台.md

关联 / 联系人

链接

联系人

  • 后端负责人: @wx
在新工单中引用 查看 Git Blame 复制永久链接