diff --git a/changelogs-v2/2026-07/42_4821_房务月度对账酒店订单查看-前端待处理-管理后台.md b/changelogs-v2/2026-07/42_4821_房务月度对账酒店订单查看-前端待处理-管理后台.md new file mode 100644 index 0000000..bd59ec4 --- /dev/null +++ b/changelogs-v2/2026-07/42_4821_房务月度对账酒店订单查看-前端待处理-管理后台.md @@ -0,0 +1,88 @@ +# 房务月度对账酒店行增加订单查看 + +- 工单:HL #4821 +- 状态:front-end todo +- 影响端:管理后台房务管家 / 月度对账 `/housekeeper/ledger` + +## 背景 + +月度对账页现在只展示“配房完毕订单酒店汇总”,用户需要在每个酒店汇总行上继续查看该酒店本月涉及的订单明细。后端已补充按酒店查询订单明细接口,前端在酒店汇总行增加“订单(查看)”入口。 + +## 新增接口 + +```http +GET /v3/admin/house/reconciliation/monthly/hotel-orders?month=2026-07&hotelId=1234567890123&hotelName=呼伦贝尔香格里拉大酒店 +``` + +请求参数: + +| 参数 | 类型 | 必填 | 示例 | 说明 | +| --- | --- | --- | --- | --- | +| `month` | `String` | 是 | `2026-07` | 对账月份,格式 `YYYY-MM` | +| `hotelId` | `String` | 否 | `1234567890123` | 酒店 ID。酒店汇总行有 `hotelId` 时传 | +| `hotelName` | `String` | 条件必填 | `呼伦贝尔香格里拉大酒店` | 酒店名快照。`hotelId` 为空时必传;`hotelId` 有值时也建议一并传 | + +重要口径: + +- 前端从 `/monthly` 汇总接口拿到的酒店行,如果 `hotelId` 有值,也要把同一行的 `hotelName` 一起传给明细接口。 +- 原因:历史配房行可能只有酒店名没有 `hotelId`,汇总接口会在同名唯一命中时合并到有 ID 的酒店行;明细接口也用同样口径。 +- 如果酒店行 `hotelId=null`,只传 `hotelName`,后端只查无 `hotelId` 的同名历史行,避免误合并其他有 ID 的同名酒店。 + +## 响应示例 + +```json +{ + "code": 200, + "message": "成功", + "success": true, + "data": [ + { + "orderId": "2074303545149980674", + "orderNo": "HL20260707092437709", + "productName": "测试核心产品-单档-固定订金", + "departDate": "2026-07-23", + "hotelId": "1234567890123", + "hotelName": "呼伦贝尔香格里拉大酒店", + "roomNights": 2, + "totalAmount": "640.00" + } + ] +} +``` + +空结果: + +```json +{ + "code": 200, + "message": "成功", + "success": true, + "data": [] +} +``` + +缺少酒店筛选: + +```json +{ + "code": 808172, + "message": "hotelId 或 hotelName 至少传一个", + "success": false +} +``` + +## 前端渲染要求 + +1. 月度对账酒店汇总表每个酒店行增加“订单(查看)”入口;合计行不展示。 +2. 点击后调用新增接口,参数取当前筛选月份和该酒店行的 `hotelId` / `hotelName`。 +3. 明细弹窗建议展示列:订单号、产品名、出发日期、间夜数、金额。 +4. `orderId` 为字符串,跳订单详情时使用 `orderId`,不要转 Number。 +5. 明细列表订单数应与汇总行 `orderCount` 一致;不一致时前端保留后端返回结果并提示刷新,不要自行重新汇总。 +6. Excel / PDF 导出暂不变,仍导出酒店汇总。 + +## 验收 + +- `/housekeeper/ledger` 的酒店汇总行能看到“订单(查看)”。 +- 点击呼伦贝尔香格里拉大酒店,弹窗能展示该酒店本月订单明细。 +- `hotelId` 为空的历史酒店行也能通过 `hotelName` 查到订单。 +- 明细金额、间夜数来自配房表快照聚合,和酒店汇总口径一致。