diff --git a/changelogs-v2/2026-06/26_4420_房务月度对账_口径修复_已复核标签+全局去重+生命周期过滤_管理后台.md b/changelogs-v2/2026-06/26_4420_房务月度对账_口径修复_已复核标签+全局去重+生命周期过滤_管理后台.md new file mode 100644 index 0000000..37cbab3 --- /dev/null +++ b/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;行为正确性由单测(含跨酒店去重/收敛/生命周期过滤)覆盖。