From 2b37f6124b8088471011919c0fe07c9ebe37e870 Mon Sep 17 00:00:00 2001 From: API Changelog Bot Date: Tue, 14 Jul 2026 23:58:36 +0800 Subject: [PATCH] =?UTF-8?q?docs(house):=20=E8=A1=A5=E5=85=85=E6=88=BF?= =?UTF-8?q?=E5=8A=A1=E5=85=A8=E9=87=8F=E5=A4=8D=E6=B5=8B=E4=B8=8E=E5=89=8D?= =?UTF-8?q?=E7=AB=AF=E6=8E=A5=E5=85=A5=E6=80=BB=E8=A7=88?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- ...调整保留配房与房务驳回定制师待办-管理后台.md | 8 +- ...务全量API复测与前端最终接入核对-管理后台.md | 176 ++++++++++++++++++ 2 files changed, 181 insertions(+), 3 deletions(-) create mode 100644 changelogs-v2/2026-07/57_房务全量API复测与前端最终接入核对-管理后台.md diff --git a/changelogs-v2/2026-07/56_4907_订单调整保留配房与房务驳回定制师待办-管理后台.md b/changelogs-v2/2026-07/56_4907_订单调整保留配房与房务驳回定制师待办-管理后台.md index be72d6b..c4bb193 100644 --- 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. 后端验证证据 diff --git a/changelogs-v2/2026-07/57_房务全量API复测与前端最终接入核对-管理后台.md b/changelogs-v2/2026-07/57_房务全量API复测与前端最终接入核对-管理后台.md new file mode 100644 index 0000000..cea0d44 --- /dev/null +++ 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`