From 2c00668800ba5d8f5b6100cbad95116008c2d2de Mon Sep 17 00:00:00 2001
From: API Changelog Bot <changelog@hulalv.com>
Date: Mon, 22 Jun 2026 11:39:01 +0800
Subject: [PATCH] =?UTF-8?q?docs(admin):=20=E6=88=BF=E5=8A=A1=E6=9C=88?=
 =?UTF-8?q?=E5=BA=A6=E5=AF=B9=E8=B4=A6=20=E6=9C=88=E5=BA=A6=E7=8E=AF?=
 =?UTF-8?q?=E6=AF=94+PDF=E5=AF=BC=E5=87=BA=20+=20=E7=BC=BA=E5=8F=A3?=
 =?UTF-8?q?=E7=AD=94=E5=A4=8D=20(PR=20#4202)?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 ...¦_月度环比+PDF导出_缺å�£ç­”å¤�-修改接å�£-管ç�†å�Žå�°.md | 89 +++++++++++++++++++
 1 file changed, 89 insertions(+)
 create mode 100644 changelogs-v2/2026-06/22_4201_4202_房务月度对账_月度环比+PDF导出_缺�答�-修改接�-管���.md

diff --git a/changelogs-v2/2026-06/22_4201_4202_房务月度对账_月度环比+PDF导出_缺�答�-修改接�-管���.md b/changelogs-v2/2026-06/22_4201_4202_房务月度对账_月度环比+PDF导出_缺�答�-修改接�-管���.md
new file mode 100644
index 0000000..eddcbb2
--- /dev/null
+++ b/changelogs-v2/2026-06/22_4201_4202_房务月度对账_月度环比+PDF导出_缺�答�-修改接�-管���.md
@@ -0,0 +1,89 @@
+# �修改接�·管���】房务月度对账 新增月度环比 + PDF 导出(mmg ledger 缺�答�) (#4202)
+
+> **PR**: #4202 | **工�**: #4201 | **�务**: hl-order-service-v3 | **更新时间**: 2026-06-22
+
+## ⚠� 关键说明（先读）
+
+针对 mmg �馈的「ledger 月度对账页原型有 4 � UI 当��端无端点�缺�，�项答� + �地：
+
+- ✅ **环比**：已加，`GET /monthly` 的 `overview.monthOverMonth`（� §2）。
+- ✅ **PDF 导出**：已加，`GET /monthly/export?format=pdf`（� §3）。
+- 🟢 **间夜**：�端**一直就有** `overview.roomNights`，�端直接��「本月间夜����（无需�端改动）。
+- �� **预付核销 / 预付余�**：维�移除（与既定「预付先���一致）。
+- �� **毛利**：**本轮��**，原型「毛利��请暂���，原因� §4（数�真相）。
+
+金� / 环比比率字段�为 **String**（�端 `@JsonSerialize`），�端按字符串收。
+
+---
+
+## 1. 月度环比（新增 `overview.monthOverMonth`）
+
+`GET /v3/admin/house/reconciliation/monthly?month=YYYY-MM` 的 `data.overview` **新增**一个嵌套对象 `monthOverMonth`（与上月��径对比）：
+
+| 字段 | 类型 | 说明 |
+|------|------|------|
+| `prevMonth` | String | 上月（YYYY-MM，如 "2026-05"） |
+| `prevRoomNights` | Integer | 上月间夜�计 |
+| `roomNightsRatio` | String | 间夜环比 %（本月较上月）；**上月为 0/无数�时为 `null`** |
+| `prevTotalAmount` | String | 上月应付�计（元） |
+| `totalAmountRatio` | String | 应付环比 %；上月为 0 时 `null` |
+| `prevOrderCount` | Integer | 上月订�数 |
+| `orderCountRatio` | String | 订�数环比 %；上月为 0 时 `null` |
+
+- 环比�径：`环比% = (本月 − 上月) / 上月 × 100`，�留 2 ��数，符��留（下�为负，如 `"-12.50"`）。
+- **`ratio` 为 `null` 时�端显示「—�**（上月基数为 0 无法定义增长率，�端�返 0% 或 ∞）。
+- `/monthly/export?format=xlsx` 的概览�也追加了 3 行环比（间夜环比 / 应付环比 / 订�数环比）。
+
+## 2. PDF 导出（`/monthly/export` 加 `format` �）
+
+�用既有导出端点，**新增�选查询� `format`**：
+
+`GET /v3/admin/house/reconciliation/monthly/export?month=YYYY-MM&format=pdf`
+
+| format | 行为 | Content-Type |
+|--------|------|-------------|
+| �传 / `xlsx` | 原 Excel 导出（**��兼容，行为��**） | `application/vnd.openxmlformats-officedocument.spreadsheetml.sheet` |
+| `pdf` | PDF 导出（概览� + 环比 + 按酒店账�表，A4） | `application/pdf` |
+| 其它值 | 业务错误（HTTP 200 + `code:808171`） | `application/json` |
+
+- PDF 文件� `house-reconciliation-{month}.pdf`；中文正常（�务端 Chromium 渲染 HTML）。
+- �端「生� PDF�按钮直接 `window.open` / 下载该 URL ��（带 `format=pdf`）。
+
+## 3. 三个「����项的明确答�
+
+- **间夜�**：`overview.roomNights`（本月）+ �酒店 `hotels[].roomNights` 一直都有，�端���片��。
+- **预付核销 tab / 预付余��**：维�移除。月度对账当��覆盖现结（CASH_PAID），预付维度属「先���范围。
+- **毛利�**：本轮��，**请暂���**。原因：月度对账是「按酒店应付�视角，�宿域数��有**�本**（实际�本 / �议价 / 实际�交价），**全域没有「客户为�宿付了多少�的按酒店收入**（定制�宿收入�在订�产�总价里�未按酒店/晚拆分）。原型「毛利 = 收入 − �本�缺收入这一�，真售�毛利需产�/财务先定义「订��宿收入如何归集到酒店�的�径��能算，届时�独立项�通知。
+
+## 4. curl 实测（2026-06-22 测试�，已通过网关）
+
+```bash
+# 1) 月度对账(�环比)
+curl 'https://api.test.1814.love:9443/v3/admin/house/reconciliation/monthly?month=2026-06' \
+  -H 'Authorization: Bearer <admin-token>'
+# → data.overview.monthOverMonth = {"prevMonth":"2026-05","prevRoomNights":0,"roomNightsRatio":null,
+#     "prevTotalAmount":"0","totalAmountRatio":null,"prevOrderCount":0,"orderCountRatio":null}
+#   (该月无现结数�故� ratio=null；有数�时如 "20.00")
+
+# 2) PDF 导出
+curl 'https://api.test.1814.love:9443/v3/admin/house/reconciliation/monthly/export?month=2026-06&format=pdf' \
+  -H 'Authorization: Bearer <admin-token>' -o recon.pdf
+# → 200 application/pdf, %PDF- 开头(实测 141KB)
+
+# 3) 默认�是 xlsx(��兼容)
+curl '.../monthly/export?month=2026-06' -H 'Authorization: Bearer <token>' -o recon.xlsx   # PK zip
+# 4) �法 format
+curl '.../monthly/export?month=2026-06&format=csv' ...   # → 200 {"code":808171,"message":"导出格��法,仅支� xlsx/pdf"}
+```
+
+## 5. �端处�建议
+
+- 「本月间夜��：��，读 `overview.roomNights`。
+- 「环比 %�：读 `overview.monthOverMonth.*Ratio`，为 `null` 显示「—�，�则显示 `值 + "%"`（注�带符�）。
+- 「生� PDF�按钮：下载 `/monthly/export?month=...&format=pdf`。
+- 「毛利�� / 「预付�相关 UI：��移除（待产�决议）。
+
+## 6. 影�评估 / 回滚
+
+- **兼容性**：`overview` 加字段�导出加 `format` �，**���兼容**（旧�端�读新字段 / �传 format 行为��）。
+- **回滚**：revert PR #4202 �新部署 hl-order-service-v3（无 DB �移，纯代�）。