# 【前端总览·管理后台】房务全量 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. 抢单、权限与待办

主要接口：

```http
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. 订单调整后的住宿需求与既有配房

定制师提交订单调整：

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

前端展示规则：

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

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

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

```http
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. 清空、驳回、重开与最终确认

```http
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. 详情、历史与操作日志

```http
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. 月度对账

```http
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`