docs(changelog-v2): 房务管家配房/酒店/员工/城市接通真实数据+房间分配写端点 (#3152/#3153/#3154/#3176/#3178)

changelogs-v2/2026-05/28_HOUSE批量_房务管家配房酒店员工城市真实化+房间分配写端点_PR3152-3154-3176-3178.md

@@ -0,0 +1,87 @@
+# 二期 v3 房务管家：配房/酒店/员工/城市等接口接通真实数据 + 新增房间分配写端点
+
+> **服务**: hl-order-service-v3（+ resource / user-service 内部接口）
+> **PR**: #3152、#3153、#3154、#3176、#3178
+> **Issue**: #3148、#3149、#3150、#3156、#3172、#3177
+> **日期**: 2026-05-28
+> **影响**: 🟡 房务管家（HOUSE）一批此前返空/null/桩的接口已接通真实数据；新增"房间分配写"端点；均已测试服双实例部署 + 真机验证
+
+---
+
+## ⚠️ 总览（前端 mmg 必读）
+
+房务管家相关接口此前多处因依赖未落地而返「空列表 / null 字段 / 占位」。现已跨 order-v3 / resource / user-service 三服务接通真实逻辑并真机验证。**接口路径、字段结构均不变**，只是**字段从空/占位变为真实值**，前端可据此把对应 UI 由"空状态"切到真实渲染。逐项如下。
+
+---
+
+## 1. 新增：房间分配写端点（§2.5）— PR #3152
+
+此前只有 `GET .../rooms`（按家庭分组查），**没有写入端点**，导致逐日 `assignments` 恒空。现补：
+
+```
+POST /v3/admin/order/assignments/{assignmentId}/rooms
+```
+- 幂等 + 分布式锁保护（重复提交安全）
+- 请求体：
+```jsonc
+{
+  "rooms": [
+    {
+      "roomGroupNo": "F1",         // 家庭/房间组号
+      "travelerCount": 2,           // 该房入住人数
+      "travelerNames": "张三,李四",  // 入住人姓名(逗号分隔)
+      "bedType": "double",          // 床型
+      "remark": "可选备注"
+    }
+  ]
+}
+```
+- 返回 `{ successCount, items:[{id, roomGroupNo, bedType, travelerCount}] }`
+- 写入后 `GET /v3/admin/order/orders/{orderId}/rooms` 的逐日 `assignments` 即非空（含床型/人数明细）
+
+---
+
+## 2. 酒店列表 / 详情接通真实数据（§6.1 / §6.2）— PR #3153
+
+`GET /v3/admin/house/hotels`（列表）与 `GET /v3/admin/house/hotels/{hotelId}`（详情 4 Tab）此前走 Fallback 返空，现接 resource 真实主数据：
+
+- **§6.1 列表**：返真实酒店（测试库 39 家），字段 `city/cityName/level/settleType/paymentMode/protoPrice/roomTypes/status` 等齐全
+  - `settleType` 字典 `hotel_settle_type`：`cash` 现付 / `sign` 签单 / `company` 公司付款
+  - `paymentMode` 字典 `hotel_payment_mode`：`prepay` 预付款 / `cash` 现结 / `monthly` 月结
+- **§6.2 详情**：`basic`（基础信息）/ `roomTypes`（房型，含 `protoPrice` + `facilities` 设施数组）/ `priceCalendar30d`（未来 30 天价格日历）/ `recentCheckLog`（核房记录）四 Tab 均返真实数据
+
+> 注：测试库酒店主数据已回填（结算/付款/协议价/房型价格），便于联调；正式环境以 resource 实际维护的数据为准。
+
+---
+
+## 3. 转单候选员工接通（§6.6）— PR #3154 + #3178
+
+`GET /v3/admin/house/staff` 此前 user-service 无对应接口返空，现接通：
+
+- user-service 新增房务员工接口，按**房务角色**筛选：`house_keeper`(房务) / `house_lead`(房务组长)
+- 返回 `{ list:[{ userId, name, avatar, online, superAdmin, activeCount }], total }`
+- **`activeCount`（在跟订单数）口径**（#3178 修正）：为该员工**当前仍持有的活跃配房需求数**（精确口径），不再是历史 CLAIM 次数近似 —— 转单选人时的负载/上限判断更准确
+
+---
+
+## 4. 行程城市接通（§1.5 / §2.0）— PR #3176
+
+此前 `cities` / `days[].city` 恒为 null。现按各天酒店反查城市接通：
+
+- **§1.5 我的接单** `GET /v3/admin/order/grab-pool/my-claims/hotel`：列表项 `cities` 返该单**行程去重城市数组**（如 `["呼伦贝尔市","兴安盟"]`）
+- **§2.0 订单详情** `GET /admin/house/orders/{orderId}`：`requirement.current.days[].city` 及行程日历 `itinerary[].cityCode/cityName` 返**中文城市名**
+- 数据缺失（酒店未维护城市 / 查询降级）时该字段如实 null，不报错
+
+---
+
+## 5. 转单接收人姓名真实化（§1.3）— PR #3178
+
+转单后归属人姓名（`claimer_name`，体现在我的接单 / 详情归属人）此前为占位 `user-{id}`，现解析为**真实员工姓名**（经房务员工接口反查；查不到时退回 `user-{id}` 兜底，不影响转单成功）。
+
+---
+
+## 验证
+
+以上全部已合并 dev-v3 + 测试服双实例滚动部署，并经真机（真 admin token，过网关 9443/本地 8080）验证：房间分配写→查 assignments 非空、酒店列表/详情字段齐全、员工列表真实、cities/city 中文城市、转单后 claimer_name 为真名。无接口路径/字段结构变更，前端按上述把对应 UI 从空态切真实渲染即可。
+
+如需任一接口的完整响应样例，或字段有疑问，回我即可。