diff --git a/changelogs-v2/2026-07/43_4826_房务月度对账增加核单实际花销-前端待处理-管理后台.md b/changelogs-v2/2026-07/43_4826_房务月度对账增加核单实际花销-前端待处理-管理后台.md new file mode 100644 index 0000000..f36df49 --- /dev/null +++ b/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` 落在当前月份。