diff --git a/changelogs/2026-03/2026-03-20_hotel_assignment_upgrade.md b/changelogs/2026-03/2026-03-20_hotel_assignment_upgrade.md new file mode 100644 index 0000000..30cc60c --- /dev/null +++ b/changelogs/2026-03/2026-03-20_hotel_assignment_upgrade.md @@ -0,0 +1,176 @@ +# 配房接口升级 — 按天粒度 + 房型升级差价自动计算 + +> 日期: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` + +--- + +### 2. 配房升级差价预览(**新增接口**) + +``` +POST /admin/order/{orderId}/hotel-assignment/preview +``` + +**说明**:预览配房的房型升级差价(不创建任何记录),前端可在用户提交配房前展示差价信息。 + +**请求体**:同分配酒店信息接口 + +**响应**:`Result` + +| 字段 | 类型 | 说明 | +|------|------|------| +| 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 +```