docs(changelog-v2): 抢单池 SSE 实时广播(新单入池/被抢/释放/加急) (#4358)

changelogs-v2/2026-06/24_4358_抢单池SSE实时广播_管理后台.md

@@ -0,0 +1,39 @@
+# 房务抢单池 SSE 实时广播（新单入池/被抢/释放/加急 → 在线房务实时刷列表）
+
+> 变更类型：✨ 实时能力（后端，**前端需接 SSE 实时刷新抢单池**）
+> 端类型：管理后台（房务管家·抢单池）
+> 日期：2026-06-24 ｜ 工单：#4357 ｜ PR：#4358 ｜ 服务：hl-order-service-v3 / hl-user-service（均已部署 health UP）
+
+---
+
+## 背景
+抢单池此前列表**不实时刷新**：A 房务抢走某单后，B 房务列表还显示「抢单」按钮，点了才返 `808001 需求已被其他房务抢到`（后端 CAS 早已防并发，但前端不知情）。现加 SSE 实时广播，前端实时刷列表（已抢单自动移除）。
+
+## 后端能力（前端需接）
+抢单池任一变更 → 实时广播给在线房务（经现有 SSE 长连接 `GET /ws/admin-msg/stream`）。
+- **新增 SSE 事件**：`event: grab-pool-changed`，`data` JSON 关键字段：
+  - `grabPoolEvent`：`ADDED`(新单入池) / `CLAIMED`(被抢，从池移除) / `RELEASED`(释放回池) / `URGENT`(加急，重排序)
+  - `orderId` / `requirementId`：变更的订单/配房需求 ID
+  - `type`：`GRAB_POOL`
+- **触发时机**：
+  - `ADDED`：定制师提交配房需求、核心订单进抢单池（团期审核单不进池不广播）。
+  - `CLAIMED`：房务抢单成功（该单应从所有人的抢单池移除）。
+  - `RELEASED`：房务释放回池（该单重新出现在抢单池）。
+  - `URGENT`：定制师加急/取消加急（抢单池重排序，加急单置顶）。
+
+## 前端配合（重点）
+抢单池页面**监听 SSE `grab-pool-changed` 事件**，按 `grabPoolEvent` 实时更新列表：
+- `CLAIMED` → 从当前抢单池列表移除该单（`orderId`/`requirementId` 匹配），解决「已被抢还显示抢单按钮」。
+- `ADDED` → 刷新/插入新入池单。
+- `RELEASED` → 刷新/插回该单。
+- `URGENT` → 重新拉列表（加急单置顶，配合 #4342 紧急度排序）。
+- 最简实现：收到任一 `grab-pool-changed` 就**重新拉一次抢单池列表**；进阶可按事件做局部增删。
+- 其他页面（非抢单池）忽略 `grab-pool-changed` 事件（广播给所有在线连接，按 event 名过滤）。
+
+## 说明
+- 后端 CAS 防并发（被抢单他人再抢返 `808001`）一直生效，本次 SSE 是**体验层**实时刷新，不改并发正确性。
+- 广播给所有在线连接（抢单池变更频率低、载荷轻）；将来如需精确到房务角色再优化。
+
+## 验证说明
+- ✅ 两服务部署 health UP；order-v3 全量 4443/0/0（含 IT）、user SSE 域单测全绿。
+- SSE 端到端（claim/release 触发 grab-pool-changed）建议前端接入后联调确认。