docs(admin-ui): 房间安排日期列/编辑回显两处渲染修正指引(后端零改动)

changelogs/2026-04/2026-04-23_admin-ui_hotel-assignment-render-fix.md

@@ -0,0 +1,130 @@
+---
+date: 2026-04-23
+type: fix-guidance
+scope: hl-ui (admin 订单详情)
+pr: "无后端 PR (纯前端渲染问题)"
+issue: "无(前端直接修)"
+breaking: false
+audience: [hl-ui]
+---
+
+# admin 订单详情 · 房间安排区域两处渲染 BUG 修正指引(后端零改动)
+
+## 背景
+
+用户反馈订单详情 → 行程安排 → 房间安排 两处不对:
+
+1. **编辑回显失效**:点「编辑」打开配房弹窗,现有已配数据不预填,等于从零配。
+2. **日期列显示「-」**:表格「日期」列应显示真实入住日期,现在渲染成 `-`。
+
+后端 API 已具备正确数据,属前端渲染绑错字段/未调回显接口。**后端不做改动**,本文档只给前端改动指引。
+
+## 问题 1:编辑弹窗不回显
+
+### 根因
+
+前端编辑弹窗打开时未调 GET 拉当前已配数据,直接开空表单。
+
+### 正确做法
+
+弹窗打开的 `onMounted` / `open()` 钩子里调:
+
+```http
+GET /admin/order/{orderId}/hotel-assignment
+Authorization: Bearer {token}
+```
+
+**响应**(已上线,PR #1049 起):
+
+```json
+{
+  "code": 200,
+  "data": [
+    {
+      "assignmentId": "2047139323009990657",
+      "orderId": "2046864526866886657",
+      "familyIndex": 1,
+      "hotelId": "2023714929877450753",
+      "hotelName": "呼伦贝尔香格里拉大酒店",
+      "roomTypeId": "3002000000000000013",
+      "roomType": "大床房",
+      "dayNumber": 4,
+      "assignmentDate": "2026-04-27",
+      "upgradePrice": null,
+      "remark": "bug1257-execute"
+    }
+  ]
+}
+```
+
+按 `(familyIndex, dayNumber)` 预填编辑表格即可。空数组代表尚未配过,弹窗走空态。
+
+## 问题 2:日期列显示「-」
+
+### 根因
+
+前端列表绑的是 `OrderDetailVO.hotelAssignments` —— **这是 Entity 原始 JSON 字符串**(为兼容 V1 保留),**不含 `assignmentDate` 字段**,所以日期列恒为空。
+
+### 正确做法
+
+改绑 `OrderDetailVO.hotelAssignmentDetails`(已结构化 + 含计算好的日期):
+
+```js
+// ❌ 错误(老 V1 兼容字段,无日期)
+const list = JSON.parse(orderDetail.hotelAssignments || '[]')
+
+// ✅ 正确(结构化列表,含 assignmentDate)
+const list = orderDetail.hotelAssignmentDetails || []
+```
+
+字段对照:
+
+| 展示列 | 取字段 |
+|--------|--------|
+| 家庭 | `familyIndex` |
+| 日期 | `assignmentDate`(YYYY-MM-DD) |
+| 酒店 | `hotelName` |
+| 房型 | `roomType` |
+| 备注 | `remark` |
+
+`assignmentDate` 由后端按 `order.departureDate + dayNumber - 1` 现算,前端直接展示即可。
+
+## 相关字段来源
+
+`OrderDetailVO` 内两个字段并存(`hl-order-service-v2`):
+
+```java
+@ApiModelProperty("酒店分配信息JSON（原始数据，V1 兼容，不建议新代码使用）")
+private String hotelAssignments;
+
+@ApiModelProperty("酒店分配详情列表（含酒店名/房型/入住日期等结构化数据，推荐使用）")
+private List<HotelAssignmentDetailVO> hotelAssignmentDetails;
+```
+
+**以后所有新代码统一走 `hotelAssignmentDetails`**。`hotelAssignments` 字段保留但标记为 V1 兼容字段,后续不再扩展新字段。
+
+## 验证
+
+### 测试服订单
+
+`2046864526866886657`(HL20260422161146-2849,南线经典 5 天 4 晚,2026-04-24 出发)
+
+当前 DB 状态(PR #1262 测试残留,实际业务测试时可重新配房):
+
+| day | hotelName | roomType | assignmentDate |
+|-----|-----------|----------|---------------:|
+| 4 | 呼伦贝尔香格里拉大酒店 | 大床房 | 2026-04-27 |
+
+### 验收清单
+
+- [ ] 打开订单 `2046864526866886657` 详情 → 行程安排 → 房间安排表格,日期列显示 `2026-04-27`(不是 `-`)
+- [ ] 点「编辑」按钮 → 弹窗自动预填 `家庭1 / 第4天 / 呼伦贝尔香格里拉大酒店 / 大床房`
+- [ ] 空态订单(从未配房)→ 弹窗打开为空表单,不报错
+- [ ] 改完提交 → 刷新详情页,列表正确显示新数据 + 日期
+
+## 相关
+
+- 后端接口(现有,无改动):`GET /admin/order/{orderId}/hotel-assignment`
+- 后端字段(现有,无改动):`OrderDetailVO.hotelAssignmentDetails[]`
+- 前置历史:PR #1049(字段 `assignmentDate` → `dayNumber` 迁移,Service 层现算日期回填 VO)
+- 后端 PR 关联:PR #1250(配房差价预览 3 BUG 修复)/ #1262(差价 execute 联动费用项)