diff --git a/changelogs-v2/2026-05/28_HOUSE批量_房务管家配房酒店员工城市真实化+房间分配写端点_PR3152-3154-3176-3178.md b/changelogs-v2/2026-05/28_HOUSE批量_房务管家配房酒店员工城市真实化+房间分配写端点_PR3152-3154-3176-3178.md new file mode 100644 index 0000000..343f09e --- /dev/null +++ b/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 从空态切真实渲染即可。 + +如需任一接口的完整响应样例,或字段有疑问,回我即可。