docs(changelog-v2): 房务月度对账口径修复(已复核标签/订单数全局去重/生命周期过滤)前端对接(#4420 PR#4425)

changelogs-v2/2026-06/26_4420_房务月度对账_口径修复_已复核标签+全局去重+生命周期过滤_管理后台.md

@@ -0,0 +1,46 @@
+# 房务月度对账 — 口径修复(已付/待付改已复核/待复核 + 订单数全局去重 + 数据源生命周期过滤)
+
+> 变更类型：🐛 口径修复（后端，**对账数值口径与列头文案有变，前端需对照**）
+> 端类型：管理后台（房务·月度对账）
+> 日期：2026-06-26 ｜ 工单：#4420 ｜ PR：#4425 ｜ 服务：hl-order-service-v3（已部署测试服，API 实测通过）
+> 接口：`GET /v3/admin/house/reconciliation/monthly` + `GET /v3/admin/house/reconciliation/monthly/export?format=xlsx|pdf`
+
+---
+
+## 背景
+对账模块（#4074）经审计确认一批口径/契约问题，已按口径决策修复。**接口路径、JSON 字段名均不变**，但部分数值口径与导出列头文案有调整，前端对照知悉即可（无需改字段对接，注意数值含义）。
+
+---
+
+## 1. 「已付/待付」改称「已复核/待复核」（**列头文案变，JSON 字段名不变**）
+- 原「已付金额 / 待付金额」实际由订单级 `settlement_status=COMPLETED`（平台财务复核完成）驱动，**不等于「已付钱给酒店」**，易误读。现统一改称：
+  - **已复核金额**（settlement_status=COMPLETED 部分）
+  - **待复核金额**（应付 − 已复核）
+- **JSON 字段名保持 `paidAmount` / `unpaidAmount` 不变**（前端无需改取值）；变化的是语义口径与 **Excel/PDF 导出的列头/合计行文案**（「已复核金额(元)」「已复核合计(元)」等）。
+- 前端若自渲染列头，请同步把「已付/待付」展示文案改为「已复核/待复核」。
+
+## 2. 概览「订单数」改为全月全局去重（**数值口径变**）
+- 概览 `overview.orderCount` 原为各酒店去重订单数**相加** → 一个订单住 N 家酒店被重复计 N 次（违反字段「全月去重 orderId」约定）。
+- 现改为**全月全局去重 orderId**（一订单跨多酒店只计 1 次）。环比 `prevOrderCount`/`orderCountRatio` 同口径。
+- **影响**：跨酒店订单越多，新「订单数」会比旧值小（更准）。**列表行 `hotels[].orderCount`（按酒店）保持不变**。
+
+## 3. 数据源加「生命周期过滤」（**totalAmount/待复核数值可能变小**）
+- 对账原按 stay_date + 现结(CASH_PAID) 全捞，不看订单结算阶段。现只纳入**已进入结算流程的有效订单**（settlement_status ∈ {PENDING, COMPLETED}）。
+- **剔除**：未提交结算（NONE/空，即录了核单但从未 submit）+ 孤儿/已软删订单（回查不到）。
+- **影响**：`totalAmount`/`unpaidAmount` 会剔除这些虚增部分，比旧值更准（可能变小）。
+
+## 4. 同物理酒店「分裂两行」已收敛（**hotelCount/列表行可能变少**）
+- 原同一家酒店可能裂成「有 hotelId 的行」+「name 兜底行」两条独立账单行，`hotelCount` 虚高。
+- 现聚合后做 name→id 二次收敛（同名唯一命中即合并；同名不同 id 的不合并）。
+- **影响**：`hotelCount` 与 `hotels[]` 行数更准（可能比旧值少），合并行的间夜/金额/订单数已正确累加。
+
+## 5. 导出小修
+- PDF/Excel 环比行标签统一带「(较 YYYY-MM)」基准月后缀（原 Excel 缺、PDF 有，现对齐）。
+- 导出 `format` 参数行为不变（xlsx 默认 / pdf / 非法值报错）。
+
+---
+
+## 测试服实测（已通过）
+- `GET /monthly` 三月均 200、结构正确、内部一致性全 True（hotelCount==hotels长度、unpaidAmount==totalAmount−paidAmount、全局去重数 ≤ per-hotel 之和）。
+- Excel 导出解压确认列头为「已复核/待复核」、旧「已付/待付」已消除。
+- 注：测试库当前无现结(CASH_PAID)核单数据，数值为 0；行为正确性由单测（含跨酒店去重/收敛/生命周期过滤）覆盖。