docs(changelog-v2): 房务组长只读监督角色+组长房务订单聊天(#4493 PR#4494)

changelogs-v2/2026-06/30_4493_房务组长只读监督角色+组长房务订单聊天-新增接口-管理后台.md

@@ -0,0 +1,67 @@
+# 新增「房务组长」只读监督角色 + 组长↔房务基于订单的聊天
+
+> 变更类型：✨ 新增角色 + 新增接口（房务管家·监督视图/聊天）
+> 端类型：管理后台（房务管家）
+> 日期：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}` 隔离 ✓。
+
+> 后端已完成并实测，前端按本单接入。`808091` 文案在「普通房务调 all-claims 被拒」场景略偏（复用了组长只读文案），不影响行为，后续可微调。