142 行
4.4 KiB
Markdown
142 行
4.4 KiB
Markdown
# 房务月度对账增加“实际花销”只读展示
|
||
|
||
- 工单：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` 落在当前月份。
|