docs(admin-ui): 配房弹窗房型回显为数字 ID 前端修复指引 (后端零改动)

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

@@ -0,0 +1,80 @@
+# 配房弹窗房型回显为数字 ID(前端问题指引,后端零改动)
+
+**日期**: 2026-04-24
+**类型**: 前端回显 BUG 指引
+**受众**: hl-ui 管理后台
+**对应界面**: 订单详情 → 行程安排 tab → 点「编辑」房间 → 配房信息弹窗
+
+---
+
+## 现场
+
+订单 `HL20260423175303-5448` 编辑配房信息,弹窗第 1 天家庭 1:
+- 酒店下拉正确:**呼伦贝尔香格里拉大酒店**
+- 房型下拉**显示为 `20237274031...` 数字 ID**,而非中文房型名「普通标间」
+
+## 后端自检结论:无问题
+
+测试服实测 `GET /admin/order/2047252402389598209/hotel-assignment`:
+
+```json
+{
+  "code": 200,
+  "data": [
+    {
+      "assignmentId": "2047488048786018306",
+      "hotelId": "2023714929877450753",
+      "hotelName": "呼伦贝尔香格里拉大酒店",
+      "roomTypeId": "2023727403196502017",
+      "roomType": "普通标间",                ← 中文名已返回
+      "dayNumber": 1,
+      "assignmentDate": "2026-04-25",
+      "remark": "1111"
+    },
+    {
+      "assignmentId": "2047488048790212610",
+      "hotelId": "2023714929877450753",
+      "hotelName": "呼伦贝尔香格里拉大酒店",
+      "roomTypeId": "3002000000000000013",
+      "roomType": "大床房",                  ← 中文名已返回
+      "dayNumber": 3,
+      ...
+    }
+  ]
+}
+```
+
+每条 assignment 都同时返回 `roomTypeId`(雪花 ID)+ `roomType`(中文名),字段已就绪,**后端零改动**。
+
+## 根因(前端)
+
+从弹窗现象看,大概率是以下组合之一:
+
+1. **回显时只绑 `roomTypeId`,没把 `roomType` 喂给 n-select tag 模式的 options 做 label 兜底**
+   - n-select 的 tag 模式在 options 异步加载前,会直接把 value 当 label 渲染 → ID 数字裸露
+   - 典型场景参考:MEMORY 里 `experience/backend-dev/nselect-tag-mode-stringify-race.md`(CitySelect 集合地/解散地同类坑)
+
+2. **房型 options 列表加载顺序错**
+   - 酒店切换后应该先调 `GET /admin/resource/hotel/{hotelId}/room-type`(或对应房型下拉接口)拉 options,再回填 `roomTypeId`
+   - 如果 options 空,n-select 就用 value 字符串渲染
+
+## 修复建议
+
+- **方案 A(推荐)**:初始化弹窗时,把后端 `hotel-assignment` 返回的每条记录的 `{roomTypeId, roomType}` **当作一条 option 先 unshift 进 options 数组**,保证回显 label 一定有。后续拉接口来的 options 合并去重。
+- **方案 B**:n-select 组件改用 `:render-tag` slot,显式从 `props.option.label` 取值;或 `:fallback-option` 属性指定 label=props.value 兜底时用的模板(改成 `房型 ${val}` 或从 assignment 行数据里查)。
+- **方案 C**:如果 n-select 非 tag 模式,直接传 `:default-value="row.roomTypeId"` + `:default-option="{ label: row.roomType, value: row.roomTypeId }"`。
+
+三种方案核心都是:**不要等异步 options 加载完才有 label,用行数据的 `roomType` 字段立刻兜住回显**。
+
+## 验证标准
+
+- 点「编辑」打开弹窗 → 房型列立刻显示中文房型名(「普通标间」/「大床房」/「俄式标准房」)而不是数字 ID
+- 切换酒店时,房型列表刷新,新房型依然显示中文
+
+## 为什么不建 Gitea 工单
+
+前端问题,按约定直接提供指引,不占 Gitea 待办通道。前端同事按本 changelog 接入即可。
+
+## 同类预防
+
+MEMORY `feedback_ui-mismatch-verify-backend-data-first.md` + `experience/bug-analyst/ui-not-displaying-data-verify-db-first.md`:遇到"UI 显示不对"类 BUG,先三尺实证(curl 接口 → 看 DB → 看网关)定位后端/前端归属,这次也是先 curl 拿到完整响应才能判定后端零问题。