177 行
6.0 KiB
Markdown
177 行
6.0 KiB
Markdown
# 配房接口升级 — 按天粒度 + 房型升级差价自动计算
|
||
|
||
> 日期：2026-03-20 | 涉及服务：hl-order-service、hl-resource-service
|
||
|
||
## 功能说明
|
||
|
||
配房接口从「按家庭+日期区间」改为「按天按家庭」粒度，每天可填备注。同时新增**房型升级差价自动计算**：如果配房时选的房型与产品默认不同（CORE产品默认标间），系统自动算出差价，临时加到尾款中，等定制师确认后正式生效。
|
||
|
||
---
|
||
|
||
## 接口变更清单
|
||
|
||
### 1. 分配酒店信息（**破坏性变更**）
|
||
|
||
```
|
||
PUT /admin/order/{orderId}/hotel-assignment
|
||
```
|
||
|
||
**请求体变更**：assignments 数组结构改为按天粒度
|
||
|
||
| 字段 | 类型 | 必填 | 说明 |
|
||
|------|------|------|------|
|
||
| assignments | Array | 是 | 酒店分配列表（按天按家庭，每天每个家庭一条） |
|
||
| assignments[].familyIndex | Integer | 是 | 家庭序号 |
|
||
| assignments[].hotelId | Long | **是（新增）** | 酒店ID |
|
||
| assignments[].hotelName | String | 是 | 酒店名称 |
|
||
| assignments[].roomTypeId | Long | **是（新增）** | 房型ID |
|
||
| assignments[].roomType | String | 是 | 房型名称 |
|
||
| assignments[].date | String | **是（新增，替代 checkInDate/checkOutDate）** | 单天日期，格式 `yyyy-MM-dd` |
|
||
| assignments[].remark | String | 否（新增） | 当天备注 |
|
||
| assignments[].upgradePrice | BigDecimal | 否（新增） | 手动覆盖升级差价（null=使用系统计算值） |
|
||
|
||
**删除的字段**：`checkInDate`、`checkOutDate`
|
||
|
||
**示例请求**：
|
||
```json
|
||
{
|
||
"assignments": [
|
||
{
|
||
"familyIndex": 1,
|
||
"hotelId": 1001,
|
||
"hotelName": "呼伦贝尔大酒店",
|
||
"roomTypeId": 2001,
|
||
"roomType": "豪华大床房",
|
||
"date": "2026-04-01",
|
||
"remark": "需要加床"
|
||
},
|
||
{
|
||
"familyIndex": 1,
|
||
"hotelId": 1001,
|
||
"hotelName": "呼伦贝尔大酒店",
|
||
"roomTypeId": 2001,
|
||
"roomType": "豪华大床房",
|
||
"date": "2026-04-02",
|
||
"remark": ""
|
||
},
|
||
{
|
||
"familyIndex": 2,
|
||
"hotelId": 1001,
|
||
"hotelName": "呼伦贝尔大酒店",
|
||
"roomTypeId": 2002,
|
||
"roomType": "标间",
|
||
"date": "2026-04-01",
|
||
"remark": ""
|
||
}
|
||
]
|
||
}
|
||
```
|
||
|
||
**房型升级逻辑（自动触发）**：
|
||
- 如果分配的 roomTypeId 与产品快照中该天默认房型不同 → 自动计算差价
|
||
- CORE产品（快照中 roomTypeId 为 null）→ 默认基准为该酒店的标间（STANDARD）
|
||
- 差价 = 新房型日价格 - 默认房型日价格（来自价格日历）
|
||
- `upgradePrice` 可手动覆盖系统计算的差价
|
||
- **定制师操作**：差价自动确认，直接调整订单总售价
|
||
- **其他角色操作**：差价设为「待确认」临时加到尾款，通知定制师确认
|
||
|
||
**响应**：无变化，`Result<Void>`
|
||
|
||
---
|
||
|
||
### 2. 配房升级差价预览（**新增接口**）
|
||
|
||
```
|
||
POST /admin/order/{orderId}/hotel-assignment/preview
|
||
```
|
||
|
||
**说明**：预览配房的房型升级差价（不创建任何记录），前端可在用户提交配房前展示差价信息。
|
||
|
||
**请求体**：同分配酒店信息接口
|
||
|
||
**响应**：`Result<RoomUpgradePreviewVO>`
|
||
|
||
| 字段 | 类型 | 说明 |
|
||
|------|------|------|
|
||
| details | Array | 各天差价明细（仅有差价的天） |
|
||
| details[].familyIndex | Integer | 家庭序号 |
|
||
| details[].date | String | 日期 |
|
||
| details[].defaultRoomTypeId | Long | 产品默认房型ID |
|
||
| details[].defaultRoomTypeName | String | 产品默认房型名称 |
|
||
| details[].assignedRoomTypeId | Long | 实际分配房型ID |
|
||
| details[].assignedRoomTypeName | String | 实际分配房型名称 |
|
||
| details[].defaultPrice | BigDecimal | 默认房型当天单价 |
|
||
| details[].assignedPrice | BigDecimal | 实际房型当天单价 |
|
||
| details[].dayDiff | BigDecimal | 当天差价（正=补款，负=退款） |
|
||
| details[].direction | String | UPGRADE / DOWNGRADE / SAME |
|
||
| details[].remark | String | 备注 |
|
||
| totalDiff | BigDecimal | 差价合计 |
|
||
| direction | String | UPGRADE / DOWNGRADE / SAME / MIXED |
|
||
| description | String | 差价描述 |
|
||
|
||
**示例响应**：
|
||
```json
|
||
{
|
||
"code": 200,
|
||
"data": {
|
||
"details": [
|
||
{
|
||
"familyIndex": 1,
|
||
"date": "2026-04-01",
|
||
"defaultRoomTypeId": 2002,
|
||
"defaultRoomTypeName": "标间",
|
||
"assignedRoomTypeId": 2001,
|
||
"assignedRoomTypeName": "豪华大床房",
|
||
"defaultPrice": 300.00,
|
||
"assignedPrice": 500.00,
|
||
"dayDiff": 200.00,
|
||
"direction": "UPGRADE",
|
||
"remark": "需要加床"
|
||
}
|
||
],
|
||
"totalDiff": 200.00,
|
||
"direction": "UPGRADE",
|
||
"description": "共 1 天有差价，合计 +200.00"
|
||
}
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
### 3. 尾款调整汇总（**字段增强**）
|
||
|
||
```
|
||
GET /admin/order/{orderId}/itinerary/balance-summary
|
||
```
|
||
|
||
**响应新增字段**：
|
||
|
||
| 字段 | 类型 | 说明 |
|
||
|------|------|------|
|
||
| confirmedAdjustment | BigDecimal | **新增** — 已确认的调整金额（已计入总售价） |
|
||
| pendingAdjustment | BigDecimal | **新增** — 待确认的调整金额（临时，待定制师确认） |
|
||
| totalAdjustment | BigDecimal | 合计（已确认 + 待确认） |
|
||
| details[].confirmStatus | String | **新增** — `CONFIRMED` 或 `PENDING_CONFIRM` |
|
||
|
||
---
|
||
|
||
## 页面影响
|
||
|
||
### 配房页面
|
||
1. **数据结构改造**：从日期区间改为按天列表，每天一条记录
|
||
2. **新增字段**：每天增加备注输入框（remark）
|
||
3. **房型选择联动**：选择房型后，调用 preview 接口展示差价
|
||
4. **差价展示**：如果有差价，在提交前展示差价明细和合计，支持手动修改 upgradePrice
|
||
5. **提交**：PUT hotel-assignment 时传入完整按天列表
|
||
|
||
### 订单详情页 — 尾款区域
|
||
1. 展示「已确认调整」和「待确认调整（临时）」两个金额
|
||
2. 待确认项标记为临时状态，提示「待定制师确认」
|
||
|
||
### 推荐交互流程
|
||
```
|
||
选择酒店+房型 → 填写每天备注 → 点击「预览差价」
|
||
→ 展示差价明细（可修改 upgradePrice）
|
||
→ 点击「确认配房」→ 调用 PUT hotel-assignment
|
||
```
|