feat: 配房差价 VO 新增 priceMissing + direction=UNPRICED 前端契约 (PR #1353)

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 行为