hl-api-changelog/changelogs-v2/2026-07/57_房务全量API复测与前端最终接入核对-管理后台.md

【前端总览·管理后台】房务全量 API 复测与最终接入核对

服务：hl-order-service-v3

生效分支：dev-v3

后端基线：merge commit 772338d4f

测试环境部署：Deploy Panel 任务 43fd5a66，8086/8186 双实例健康

最终复测：2026-07-14 使用 31 笔全新订单，通过测试网关完成 178 项接口/流程断言；模块全量测试 5560 项，0 失败、0 错误、15 跳过

1. 使用边界

1. 除 /v3/internal/** 外，管理后台所有接口必须走测试/正式网关，前端不得直连订单服务实例。
2. 页面动作以详情返回的 actions.*.enabled、待办返回的 todoTypes[] 为准，禁止根据 houseStatus 自行推导按钮或补标签。
3. 每次抢单、释放、转单、配房、清空、驳回、最终确认、订单调整成功后，重新请求详情、待办和工作台；不要用进入页面前的缓存继续渲染。
4. 本文件是当前源码最终契约总览；详细字段仍以关联 changelog 和 Knife4j 为准。

2. 抢单、权限与待办

主要接口：

GET  /v3/admin/order/grab-pool/hotel-requirements
POST /v3/admin/order/hotel-requirements/{requirementId}/claim
POST /v3/admin/order/hotel-requirements/{requirementId}/release
POST /v3/admin/order/hotel-requirements/{requirementId}/transfer
GET  /v3/admin/order/grab-pool/my-claims/hotel
GET  /v3/admin/order/grab-pool/all-claims/hotel
GET  /v3/admin/order/todos
GET  /admin/profile/dashboard

• 房务管理员只看自己的未完成任务；房务组长、超级管理员才可使用全部接单视图。
• 非房务角色抢单、横向操作他人需求均由后端拒绝，前端仍需按角色隐藏无权入口。
• 返工需求存在 OPEN REQUIREMENT_ADJUSTED 时，主标签只能是“需求变更重配”，不得再根据 houseStatus=CLAIMING 补“刚抢单待配房”。
• HOTEL_REPLY_TIMEOUT、UNREAD_CHAT 等独立提醒允许与返工标签共存。
• 最终确认、房务驳回、订单取消后，返工待办会关闭；页面必须刷新后再显示计数。

3. 订单调整后的住宿需求与既有配房

定制师提交订单调整：

POST /v3/admin/order/{orderId}/adjustment/submit

前端展示规则：

调整内容	后端结果	房务页面要求
增加行程晚数	原晚次配房保留，新增夜为空待配	新增夜单独显示“配房”
减少行程晚数	需求晚数减少，超范围旧配房不自动删除	继续展示旧配房，要求房务人工清空/调整
修改出发日期	范围内配房按 dayNumber 平移入住日期，酒店/房型/房间数/价格/库存口径保留并退回询房中	展示新日期并允许重新确认
修改出行人数	原配房保留，流程回到配房中或待最终确认	不得清空已有配房
同时改日期和晚数	新范围内平移，新增夜为空，超范围旧配房保留	同时展示当前需求和待人工处理的旧配房

• 新增夜允许空候选占位，roomCount 未填或为 0 可以保存需求；前端不要伪造间数。
• 历史需求必须继续展示；只有当前 active 需求可以修改。
• 订单调整出行人校验当前返回：删除最后一名成人为 581107；普通成人超声明配额为 581149。收到错误后保留表单，不得显示为已保存。

4. 配房、替换与单条原子调整

POST /v3/admin/order/hotel-requirements/{requirementId}/assignments
PUT  /v3/admin/order/assignments/{assignmentId}
PUT  /v3/admin/order/hotel-requirements/{requirementId}/assignments/{assignmentId}/placement
POST /v3/admin/order/hotel-requirements/{requirementId}/assignments/days/{dayNumber}/confirm

前端每条配房至少需要支持：

• 目标晚次 dayNumber
• 酒店 hotelId
• 房型 roomTypeId / roomCategory
• 房间数 roomCount
• 协议价 protoPrice
• 结算价 settlementPrice
• 是否扣库存 deductInventory
• 价格/结算方式同步开关
• 备注

跨晚次移动、改酒店、改房型、改房间数必须调用 placement 原子接口，不能在前端组合“新增目标晚 + 删除原晚”。目标日期不是自由文本，选项来自当前有效行程晚次，提交 dayNumber，stayDate 由后端推导。

示例：订单从 6 月 1 日改到 6 月 5 日，当前第 1 晚是 6 月 5 日时，提交 dayNumber=1；不要提交 stayDate=2026-06-05，也不要把 dayNumber 传成 5。

5. 价格快照与库存

• 配房保存当时的 protoPrice、settlementPrice，历史订单不得重新按当前价格日历推断。
• sellPrice 已废弃，前端不要再提交或展示为配房价格。
• 只有协议价或结算价相对资源日历实际发生变化时，才询问是否同步；未变化不弹窗。
• 同步必须由用户显式选择，默认不同步。
• deductInventory 每条配房必传：true 扣系统库存，false 只保存订单快照。
• 可用房就是当前可售库存，不要在前端再次减去已占用数；后端返回多少就展示多少。
• 扣库存配房改期时后端原子迁移库存；目标日期任一晚库存不足返回 808901，整次调整回滚，原订单、原配房和原库存保持不变。

6. 清空、驳回、重开与最终确认

DELETE /v3/admin/order/assignments/{assignmentId}
DELETE /v3/admin/order/hotel-requirements/{requirementId}/assignments/days/{dayNumber}
DELETE /v3/admin/order/hotel-requirements/{requirementId}/assignments
POST   /v3/admin/order/{orderId}/hotel-requirement/supplier-reject
POST   /v3/admin/order/hotel-requirements/{requirementId}/reopen
POST   /admin/house/assignments/requirements/{requirementId}/finalize

• 每个行程晚次都要有独立“清空”按钮；底部可保留“清空全部”。
• 清空全部必须二次确认；按天清空也要明确“只清空第 N 晚”。
• 有任意 active 配房/询房数据时不能驳回。按钮唯一依据是 actions.canRejectRequirement.enabled，不要只看流程状态。
• 无任何配房时允许直接最终确认，用于客人自行解决住宿。
• 一旦存在配房，最终确认要求所有 active 配房已确认，并与当前住宿晚次精确一致；否则返回 808181，页面保留数据供人工处理。
• 核心订单不能调用团期管理员驳回接口；错误由后端守卫返回，前端不要把团期驳回按钮用于核心订单。
• 房务驳回住宿需求后，原定制师会收到 ASSIGN_ROOM 待办；房务端应刷新并移除已关闭返工标签。

7. 详情、历史与操作日志

GET /v3/admin/house/orders/{orderId}/operation-log
GET /v3/admin/order/{orderId}/status-log
GET /v3/admin/order/orders/{orderId}/rooms
GET /admin/house/assignments/requirements/{requirementId}/receipts

最终复测已确认以下事件完整产生：

HOTEL_REQUIREMENT_SUBMIT、HOUSE_CLAIM、HOUSE_ASSIGNMENT_SUBMIT、HOUSE_ASSIGNMENT_UPDATE、HOUSE_ASSIGNMENT_CLEAR、REQUIREMENT_REJECTED、HOUSE_RELEASE、HOUSE_TRANSFER、HOTEL_DONE。

前端按事件类型显示简要业务文案，不需要展开内部表字段或库存补偿细节。

8. 月度对账

GET /v3/admin/house/reconciliation/monthly?month=YYYY-MM
GET /v3/admin/house/reconciliation/monthly/hotel-orders?month=YYYY-MM&hotelId={hotelId}&hotelName={hotelName}
GET /v3/admin/house/reconciliation/monthly/export?month=YYYY-MM&format=xlsx
GET /v3/admin/house/reconciliation/monthly/export?month=YYYY-MM&format=pdf

• 页面只展示配房完成订单的酒店汇总，酒店行可点击查看订单明细。
• “实际花销”读取核单住宿 actual_cost；未录入显示 —，不显示 0。
• Excel/PDF 直接下载后端返回文件，不在前端重新拼导出内容。

9. 页面一致性核对清单

前端处理完成后按同一订单核对：

1. 房务首页、待办列表、订单详情的主标签和数量一致。
2. 返工订单只显示“需求变更重配”，不显示“刚抢单待配房”。
3. 历史需求、当前需求、旧配房都可见；只有当前需求可编辑。
4. 每条既有配房有“调整”和“清空”入口；调整可同时改晚次、酒店、房型和房间数。
5. 有任何配房时驳回不可用；全部清空并刷新后才可驳回。
6. 增晚、减晚、改日期、改人数后不静默删除既有配房。
7. 零配房可最终确认；有配房时必须日期覆盖完整且全部确认。
8. 价格未变化不弹同步确认；发生变化时由用户选择是否同步。
9. 所有业务动作成功后重新请求详情/待办/工作台，不使用本地旧状态补标签。

10. 后端最终证据

• 模块全量测试：5560 项，0 失败、0 错误、15 跳过。
• 测试环境新订单：最终有效批次共 31 笔。
• 接口面：68/68。
• 缺口流程：23/23，3 个场景。
• 订单调整/返工/库存/取消：73/73，4 个场景。
• 操作日志：14/14，3 个场景。
• 运行时合计：178/178。
• #4992 仅修正出行人校验优先级、Settlement JSON 入参校验和测试基线，不新增前端字段或接口。

11. 关联详细 changelog

• 29_4777_房务清空配房信息与驳回按钮动作契约-前端待处理-管理后台.md
• 30_4782_房务配房价格快照与询房酒店名-修改接口-管理后台.md
• 32_4793_房务配房库存扣减选择与库存口径快照-前端待处理-管理后台.md
• 43_4826_房务月度对账增加核单实际花销-前端待处理-管理后台.md
• 56_4907_订单调整保留配房与房务驳回定制师待办-管理后台.md