# 新增「房务组长」只读监督角色 + 组长↔房务基于订单的聊天

> 变更类型：✨ 新增角色 + 新增接口（房务管家·监督视图/聊天）
> 端类型：管理后台（房务管家）
> 日期：2026-06-27 ｜ 工单：#4493 ｜ PR：#4494 ｜ 服务：hl-order-service-v3 + hl-user-service（双服务已部署测试服，house_keeper_lead 账号 API 实测通过）

---

## 一、新增角色：房务组长（house_keeper_lead）

新增 sys_role `role_key=house_keeper_lead`（房务组长）。**只读监督角色**：
- 看**全部房务**抢到的订单 + 全部房务待办（标明属哪个房务）。
- **不可任何写操作**、**不能抢单**。
- 可基于订单与对应房务在线聊天。

由超管在「管理员管理」给账号指派该角色。登录后 JWT `role=house_keeper_lead`。

---

## 二、新增：组长监督全部已抢订单

`GET /v3/admin/order/grab-pool/all-claims/hotel`（入参同「我的接单」`HouseMyOrderPageReqVO`：page/pageSize/houseStatus 等）
- **权限**：仅 `house_keeper_lead` / `SUPER_ADMIN` 可调；普通房务调用返 `808091`（无权）。
- **出参**：同「我的接单」`HouseMyOrderPageRespVO`（`total` + `stats` 全局计数 + `list[]`），**列表项新增 2 字段**：
  - `claimerId`（String，雪花）—— 该单所属房务 ID，**前端开「组长↔房务」会话时作 peerAdminId 传入**。
  - `claimerName`（String）—— 该单所属房务姓名，用于「属哪个房务」展示。

> 「我的接单」`GET .../my-claims/hotel`（房务看自己的）不变。

---

## 三、组长待办（复用现有端点）

`GET /v3/admin/order/todos?scope=all`：组长传 `scope=all` 即看全部房务待办；待办项 `ownerUserId` / `ownerName` 标明归属房务。**无需新接口、无字段变更**。

---

## 四、组长写操作一律被拒（只读铁律）

组长调用任何房务写端点（抢单 claim / 配房保存 / 单日确认 / 整体确认 / release / transfer / close / reopen / 删配房 / 改价 / 验房日志 / 水单回执 等）一律返：
- `code: 808091`「房务组长为只读监督角色，无权执行该操作」。

前端：组长视图隐藏所有操作按钮（抢单/配房/确认/释放/转单等），仅保留查看 + 聊天入口。

---

## 五、新增：组长↔房务基于订单的聊天（方案 A 独立会话）

`POST /admin/message/chat/open-house-lead`
- Body：`{ "orderId": Long, "peerAdminId": Long }` —— `peerAdminId` = 该订单房务（claimer），**前端从 all-claims 列表的 `claimerId` 取**。两者均必填。
- 行为：幂等找回/新建会话，键 = **`HOUSE_LEAD:{orderId}`**（与定制师↔房务的 `HOUSE:{orderId}` **独立隔离**，互不污染）。转单后房务变更，再调自动对齐对端。
- 出参：`ChatOpenRespVO`（`conversationKey=HOUSE_LEAD:{orderId}` + `isNew` + 对端/未读信息）。
- **后续发消息/拉线程/标已读/会话列表/未读总数全部复用现有端点**（按 `conversationKey` 工作）：
  - 发消息 `POST /admin/message/chat/{conversationKey}/messages`
  - 拉线程 `GET /admin/message/chat/{conversationKey}/messages`
  - 标已读 `POST /admin/message/chat/{conversationKey}/read`
- 房务侧：该会话出现在房务现有聊天 Tab（对端角色 `HOUSE_LEAD`「房务组长」），可正常读取与回复。`senderRole` 自动正确（组长发=HOUSE_LEAD，房务回=HOUSE）。

前端需：聊天角色徽章新增 `HOUSE_LEAD`「房务组长」；组长在订单行点「联系房务」走 `/open-house-lead`（传 orderId + claimerId）。

---

## 六、测试服实测（house_keeper_lead 账号）

组长看 all-claims（带 claimerId/claimerName）✓；纯房务调 all-claims 拒 808091 ✓；组长抢单/配房/release/reopen 全拒 808091 ✓，普通房务写不被误拦 ✓；组长 open-house-lead→`HOUSE_LEAD:{orderId}`、发消息→房务成员行建出 unread+1、房务可读可回复、与 `HOUSE:{orderId}` 隔离 ✓。

> 后端已完成并实测，前端按本单接入。
>
> 补充（#4496 已落地）：**普通房务调 all-claims 被拒的错误码为 `808092`「无权查看全部房务订单（仅房务组长或超管可查看）」**（与组长写操作被拒的 `808091`「房务组长为只读监督角色」语义区分）。前端：`808092` 出现在普通房务误调监督端点时，按普通无权提示即可。