docs(house): 补充房务全量复测与前端接入总览

2026-07-14 23:58:36 +08:00 · 2026-07-14 23:58:36 +08:00 · 2b37f6124b
--- a/changelogs-v2/2026-07/56_4907_订单调整保留配房与房务驳回定制师待办-管理后台.md
+++ b/changelogs-v2/2026-07/56_4907_订单调整保留配房与房务驳回定制师待办-管理后台.md
@ -1,5 +1,7 @@
 # 【行为变更·管理后台】订单调整保留配房与房务驳回定制师待办（#4907）

+> 2026-07-14 最终状态：#4907 后端链路已完成并关闭；最终全量复测与前端接入总览见 `57_房务全量API复测与前端最终接入核对-管理后台.md`。前端页面验收属于独立交付，不作为后端工单关单门禁。
+
 > 服务：`hl-order-service-v3`
 >
 > 生效分支：`dev-v3`
@ -60,7 +62,7 @@ GET /v3/admin/order/todos?scope=mine&status=OPEN&page=1&pageSize=20
 - `REQUIREMENT_ADJUSTED` 与同一需求的 `PENDING_ARRANGE` 后端已互斥，`stats.PENDING_ARRANGE` 同口径排除。
 - 前端禁止根据 `houseStatus=CLAIMING` 自行补“刚抢单待配房”。
 - `HOTEL_REPLY_TIMEOUT`、`UNREAD_CHAT` 可与返工标签并存，不能因为互斥普通新抢标签而一并隐藏。
- 当前未完成阻塞项仍是 §1 的目标晚次选择和“调整”入口；该页面未验收前 Issue #4907 保持 OPEN。
+- §1 的目标晚次选择和“调整”入口属于前端实现清单；前端完成后独立验收，不再用于控制后端 Issue #4907 状态。

 ### 0.4 首页、待办列表、订单详情必须保持一致

@ -77,7 +79,7 @@ GET /v3/admin/order/todos?scope=mine&status=OPEN&page=1&pageSize=20
 - `HOTEL_REPLY_TIMEOUT`、`UNREAD_CHAT` 等独立提醒可以与返工主标签共存，但不得自行拼接同需求的 `PENDING_ARRANGE`。
 - 调整配房只能提交目标 `dayNumber`，不得自行提交或计算 `stayDate`；入住日期由后端根据当前行程晚次推导。

-Issue #4907 的前端关闭证据必须包含同一订单在“房务首页、待办列表、订单详情”三处的刷新后截图，并能证明标签、数量和当前业务状态一致。缺少任一页面截图，或详情仍无“调整”入口，Issue 保持 OPEN。
+前端独立验收建议包含同一订单在“房务首页、待办列表、订单详情”三处的刷新后截图，并证明标签、数量和当前业务状态一致；该证据用于前端交付验收，不反向重开已完成的后端 Issue。

 ## 1. 订单调整后的房务口径

@ -241,7 +243,7 @@ Content-Type: application/json
 11. 需求变更返工订单只展示 `需求变更重配` 主标签，不得再从 `CLAIMING` 自行补出 `刚抢单待配房`；询房超时、未读消息等独立标签照常展示。
 12. 每条已有配房均提供“调整”入口，可选择当前有效晚次并同时修改酒店、房型、房间数和库存口径；改期后从 6 月 1 日调整到当前第 1 晚 6 月 5 日时提交 `dayNumber=1`。
 13. 同一返工订单在房务首页、待办列表、订单详情三处的主标签、数量和当前状态一致；动作成功后均使用重新请求的数据，不使用本地旧缓存补标签。
-14. 前端提交单条配房调整时只提交 `dayNumber`，不得提交 `stayDate`；关闭 #4907 前提供三处页面刷新后的同订单截图。
+14. 前端提交单条配房调整时只提交 `dayNumber`，不得提交 `stayDate`；完成前端适配时提供三处页面刷新后的同订单截图。

 ## 5. 后端验证证据

--- a/changelogs-v2/2026-07/57_房务全量API复测与前端最终接入核对-管理后台.md
+++ b/changelogs-v2/2026-07/57_房务全量API复测与前端最终接入核对-管理后台.md
@ -0,0 +1,176 @@
+# 【前端总览·管理后台】房务全量 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`