From eaa784994d54301b8c62ae0e7a845d46cc65793a Mon Sep 17 00:00:00 2001
From: API Changelog Bot <changelog@hulalv.com>
Date: Tue, 7 Jul 2026 18:17:50 +0800
Subject: [PATCH] docs(frontend): add house ledger order detail contract

---
 ...¡æœˆåº¦å¯¹è´¦é…’店订å�•æŸ¥çœ‹-å‰�端待处ç�†-管ç�†å�Žå�°.md | 88 +++++++++++++++++++
 1 file changed, 88 insertions(+)
 create mode 100644 changelogs-v2/2026-07/42_4821_房务月度对账酒店订�查看-�端待处�-管���.md

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` 查到订�。
+- 明细金��间夜数�自�房表快照��，和酒店汇总�径一致。