diff --git a/changelogs/2026-04/24_fix_order-v2_room-diff-preview-unpriced-direction.md b/changelogs/2026-04/24_fix_order-v2_room-diff-preview-unpriced-direction.md new file mode 100644 index 0000000..b694339 --- /dev/null +++ b/changelogs/2026-04/24_fix_order-v2_room-diff-preview-unpriced-direction.md @@ -0,0 +1,101 @@ +# 配房差价 VO 新增 priceMissing 字段 + direction 新值 UNPRICED(价格未录入提示) + +**日期**: 2026-04-24 +**PR**: #1353 (dev) +**Issue**: #1349 +**类型**: fix / enhance +**服务**: hl-order-service-v2 + +--- + +## 摘要 + +`POST /admin/order/{orderId}/hotel-assignment/preview` 返回的 `RoomUpgradePreviewVO` 和内嵌 `DayUpgradeDetail`: + +1. **新增字段 `priceMissing: Boolean`** — 标记该天/该 VO 是否因房型价格未录入而无法算差价 +2. **`direction` 字段新增枚举值 `UNPRICED`** — 所有差价天均为价格未录入时 `RoomUpgradePreviewVO.direction=UNPRICED`;单天 `DayUpgradeDetail.direction=UNPRICED` +3. **`description` 文案增强** — 含未录入天数时拼接「另有 N 天房型价格未录入,请联系运营补录后再算差价」 + +## 背景 + +PR #1348 在房型价格未录入(`queryDayPrice` 返 0)时把整天跳过不进 `details`,保住了「防假扣 280」但造成副作用:用户配非默认房型依然显示「无差价」(details 空)。本 PR 把 unpriced 天保留进 `details` 并明确标记,前端可区分「真无差价」和「价格待录入」。 + +## 字段契约 + +### `DayUpgradeDetail` +```jsonc +{ + "familyIndex": 1, + "date": "2026-04-27", + "defaultRoomTypeId": "2023727403196502017", + "defaultRoomTypeName": "普通标间", + "assignedRoomTypeId": "3002000000000000013", + "assignedRoomTypeName": "大床房", + "defaultPrice": 280.00, + "assignedPrice": 0, + "dayDiff": 0, + "direction": "UNPRICED", // 新枚举值 + "priceMissing": true, // 新字段: true 表示价格未录入 + "remark": "1111" +} +``` + +### `RoomUpgradePreviewVO` +```jsonc +{ + "details": [ ... ], + "totalDiff": 0, + "direction": "UNPRICED", // 所有天都 unpriced 时;否则仍是 UPGRADE/DOWNGRADE/MIXED/SAME + "description": "共 2 天有差价,合计+200;另有 1 天房型价格未录入,请联系运营补录后再算差价" +} +``` + +## direction 枚举值完整表 + +| 值 | 含义 | +|---|---| +| `UPGRADE` | 升级(`dayDiff > 0`) | +| `DOWNGRADE` | 降级(`dayDiff < 0`) | +| `SAME` | 一致 / 无差价 / details 空 | +| `MIXED` | 既有升级又有降级 | +| **`UNPRICED`**(新) | 房型价格未录入,该天/该 VO 不计入差价,仅提示 | + +## 前端渲染建议 + +- **`DayUpgradeDetail.direction === 'UNPRICED' / priceMissing === true`** — 该行用红字/tag 提示「价格未录入, 请联系运营补录」,不显示 dayDiff 数字(或显示灰色 0) +- **`RoomUpgradePreviewVO.direction === 'UNPRICED'`** — 顶部 alert 用 warning 色调而不是 info +- **`totalDiff === 0` 且 `description` 含「价格未录入」** — 保留「确认提交」按钮但提示「本订单存在价格未录入天,本次提交不会产生差价,建议运营补录后重新配房」 +- `priceMissing` 的条目**不影响**顶部 totalDiff 数字 + +## 测试服实测(订单 2047252402389598209 第 3 天大床房) + +``` +POST /preview +{ + "assignments": [ + {"familyIndex":1,"hotelId":...,"roomTypeId":3002000000000000013,"roomType":"大床房","dayNumber":3} + ] +} + +响应: +{ + "code": 200, + "data": { + "details": [{ + "priceMissing": true, + "direction": "UNPRICED", + "dayDiff": 0, + ... + }], + "totalDiff": 0, + "direction": "UNPRICED", + "description": "另有 1 天房型价格未录入,请联系运营补录后再算差价" + } +} +``` + +## 风险与回滚 + +- 新增字段 `priceMissing` 和新枚举值 `UNPRICED` 对历史前端**向后兼容**:不识别 UNPRICED 的旧前端会把它当 SAME 处理(退化到「无差价」),不会崩 +- 接口路径/其它字段/DB 不变 +- 回滚:revert PR #1353 恢复 PR #1348 行为