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

工单：HL #4826
状态：front-end todo
影响端：管理后台房务管家 / 月度对账 /housekeeper/ledger

背景

月度对账页需要在酒店汇总中展示“实际花销”。该金额不是新增录入功能，来源为核单 Step 1 已保存的住宿实际成本 order_settlement_hotel.actual_cost。

汇总接口字段变更

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"`	当前酒店核单住宿行最近更新时间

响应示例：

{
  "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"
      }
    ]
  }
}

未录入示例：

{
  "hotelId": "1234567890123",
  "hotelName": "呼伦贝尔香格里拉大酒店",
  "orderCount": 1,
  "roomNights": 2,
  "totalAmount": "640.00",
  "actualExpenseAmount": null,
  "expenseEntered": false,
  "expenseOperatorName": null,
  "expenseUpdatedAt": null
}

酒店订单明细字段变更

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`	该订单在该酒店是否存在核单住宿行

响应示例：

{
  "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 酒店汇总表新增列：实际花销。

前端渲染要求

月度对账酒店汇总列表增加“实际花销”列。
expenseEntered=false 或 actualExpenseAmount=null 时显示 —，不要显示 0。
已录入时展示 actualExpenseAmount。
订单明细弹窗也展示每个订单的 actualExpenseAmount，未录入显示 —。
如果现有列仍绑定 totalAmount，也会拿到同一实际花销金额；建议显示文案改为“实际花销”。
Excel / PDF 按后端导出结果展示即可。

只读边界

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

4.4 KiB 原始文件 Blame 文件历史 Unescape Escape