docs: add house reconciliation actual expense changelog

changelogs-v2/2026-07/43_4826_房务月度对账增加核单实际花销-前端待处理-管理后台.md

@@ -0,0 +1,138 @@
+# 房务月度对账增加“实际花销”只读展示
+
+- 工单：HL #4826
+- 状态：front-end todo
+- 影响端：管理后台房务管家 / 月度对账 `/housekeeper/ledger`
+
+## 背景
+
+月度对账页需要在酒店汇总中展示“实际花销”。该金额不是新增录入功能，来源为核单 Step 1 已保存的住宿实际成本 `order_settlement_hotel.actual_cost`。
+
+## 汇总接口字段变更
+
+```http
+GET /v3/admin/house/reconciliation/monthly?month=2026-07
+```
+
+响应新增字段：
+
+| 路径 | 类型 | 示例 | 说明 |
+| --- | --- | --- | --- |
+| `overview.totalActualExpense` | `String/null` | `"81200.00"` | 本月已录入核单住宿实际成本合计；全部未录入时为 `null` |
+| `hotels[].actualExpenseAmount` | `String/null` | `"21800.00"` | 当前酒店本月核单住宿实际成本合计；未录入时为 `null` |
+| `hotels[].expenseEntered` | `Boolean` | `true` | 当前酒店是否存在核单住宿行 |
+| `hotels[].expenseOperatorName` | `String/null` | `null` | 当前核单住宿表未保存录入人姓名，先返回 `null` |
+| `hotels[].expenseUpdatedAt` | `String/null` | `"2026-07-08T10:30:00"` | 当前酒店核单住宿行最近更新时间 |
+
+响应示例：
+
+```json
+{
+  "code": 200,
+  "message": "成功",
+  "success": true,
+  "data": {
+    "month": "2026-07",
+    "overview": {
+      "hotelCount": 3,
+      "orderCount": 30,
+      "roomNights": 94,
+      "totalAmount": "86400.00",
+      "paidAmount": "86400.00",
+      "unpaidAmount": "0.00",
+      "totalActualExpense": "81200.00"
+    },
+    "hotels": [
+      {
+        "hotelId": "1234567890123",
+        "hotelName": "呼伦贝尔香格里拉大酒店",
+        "orderCount": 26,
+        "roomNights": 90,
+        "totalAmount": "80000.00",
+        "avgPrice": "888.89",
+        "paidAmount": "80000.00",
+        "unpaidAmount": "0.00",
+        "actualExpenseAmount": "76000.00",
+        "expenseEntered": true,
+        "expenseOperatorName": null,
+        "expenseUpdatedAt": "2026-07-08T10:30:00"
+      }
+    ]
+  }
+}
+```
+
+未录入示例：
+
+```json
+{
+  "hotelId": "1234567890123",
+  "hotelName": "呼伦贝尔香格里拉大酒店",
+  "orderCount": 1,
+  "roomNights": 2,
+  "totalAmount": "640.00",
+  "actualExpenseAmount": null,
+  "expenseEntered": false,
+  "expenseOperatorName": null,
+  "expenseUpdatedAt": null
+}
+```
+
+## 酒店订单明细字段变更
+
+```http
+GET /v3/admin/house/reconciliation/monthly/hotel-orders?month=2026-07&hotelId=1234567890123&hotelName=呼伦贝尔香格里拉大酒店
+```
+
+`data[]` 新增字段：
+
+| 字段 | 类型 | 示例 | 说明 |
+| --- | --- | --- | --- |
+| `actualExpenseAmount` | `String/null` | `"580.00"` | 该订单在该酒店的核单住宿实际成本合计 |
+| `expenseEntered` | `Boolean` | `true` | 该订单在该酒店是否存在核单住宿行 |
+
+响应示例：
+
+```json
+{
+  "code": 200,
+  "message": "成功",
+  "success": true,
+  "data": [
+    {
+      "orderId": "2074303545149980674",
+      "orderNo": "HL20260707092437709",
+      "productName": "测试核心产品-单档-固定订金",
+      "departDate": "2026-07-23",
+      "hotelId": "1234567890123",
+      "hotelName": "呼伦贝尔香格里拉大酒店",
+      "roomNights": 2,
+      "totalAmount": "640.00",
+      "actualExpenseAmount": "580.00",
+      "expenseEntered": true
+    }
+  ]
+}
+```
+
+## 导出变更
+
+- `GET /v3/admin/house/reconciliation/monthly/export?month=2026-07&format=xlsx`
+- `GET /v3/admin/house/reconciliation/monthly/export?month=2026-07&format=pdf`
+
+Excel / PDF 酒店汇总表新增列：`实际花销`。
+
+## 前端渲染要求
+
+1. 月度对账酒店汇总列表增加“实际花销”列。
+2. `expenseEntered=false` 或 `actualExpenseAmount=null` 时显示 `—`，不要显示 `0`。
+3. 已录入时展示 `actualExpenseAmount`。
+4. 订单明细弹窗也展示每个订单的 `actualExpenseAmount`，未录入显示 `—`。
+5. Excel / PDF 按后端导出结果展示即可。
+
+## 只读边界
+
+- 本次不新增任何录入接口。
+- 不新增表。
+- 不改订单/房务状态。
+- 实际花销数据源：核单住宿表 `order_settlement_hotel.actual_cost`，入住日 `stay_date` 落在当前月份。