# 二期 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 从空态切真实渲染即可。

如需任一接口的完整响应样例，或字段有疑问，回我即可。
