# 房务月度对账 — 口径修复(已付/待付改已复核/待复核 + 订单数全局去重 + 数据源生命周期过滤)

> 变更类型：🐛 口径修复（后端，**对账数值口径与列头文案有变，前端需对照**）
> 端类型：管理后台（房务·月度对账）
> 日期：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；行为正确性由单测（含跨酒店去重/收敛/生命周期过滤）覆盖。
