# 房务月度对账增加“实际花销”只读展示

- 工单：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=呼伦贝尔香格里拉大酒店
```

2026-07-08 修正：订单明细里的兼容旧字段 `totalAmount` 也按“实际花销”口径返回，等于 `actualExpenseAmount`；未核单录入时两者都为 `null`。前端不要再把 `totalAmount` 当配房金额展示。

`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": "580.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. 如果现有列仍绑定 `totalAmount`，也会拿到同一实际花销金额；建议显示文案改为“实际花销”。
6. Excel / PDF 按后端导出结果展示即可。

## 只读边界

- 本次不新增任何录入接口。
- 不新增表。
- 不改订单/房务状态。
- 实际花销数据源：核单住宿表 `order_settlement_hotel.actual_cost`，入住日 `stay_date` 落在当前月份。