177 行
9.5 KiB
Markdown
177 行
9.5 KiB
Markdown
# 【前端总览·管理后台】房务全量 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`
|