From c8e3769e3f4b886a71638607ba3359bf8045a5f2 Mon Sep 17 00:00:00 2001
From: API Changelog Bot <changelog@hulalv.com>
Date: Thu, 25 Jun 2026 15:06:01 +0800
Subject: [PATCH] =?UTF-8?q?docs(changelog-v2):=20=E7=AB=99=E5=86=85?=
 =?UTF-8?q?=E4=BF=A1=E9=A1=B6=E9=83=A8=E9=93=83=E9=93=9B=E6=9C=AA=E8=AF=BB?=
 =?UTF-8?q?=E8=A7=92=E6=A0=87=E5=89=8D=E7=AB=AF=E6=8E=A5=E5=85=A5spec(?=
 =?UTF-8?q?=E5=90=8E=E7=AB=AF=E5=B7=B2=E5=B0=B1=E7=BB=AA:=E6=9C=AA?=
 =?UTF-8?q?=E8=AF=BB=E8=90=BD=E5=BA=93+SSE=E5=B8=A6unreadCount=E4=BF=A1?=
 =?UTF-8?q?=E4=BB=A4+unread-count=E6=8E=A5=E5=8F=A3)?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 ...�信顶部铃铛未读角标接入_前端对接_管理后台.md | 44 +++++++++++++++++++
 1 file changed, 44 insertions(+)
 create mode 100644 changelogs-v2/2026-06/25_站内信顶部铃铛未读角标接入_前端对接_管理后台.md

diff --git a/changelogs-v2/2026-06/25_站内信顶部铃铛未读角标接入_前端对接_管理后台.md b/changelogs-v2/2026-06/25_站内信顶部铃铛未读角标接入_前端对接_管理后台.md
new file mode 100644
index 0000000..072a803
--- /dev/null
+++ b/changelogs-v2/2026-06/25_站内信顶部铃铛未读角标接入_前端对接_管理后台.md
@@ -0,0 +1,44 @@
+# 站内信顶部铃铛未读角标接入（前端对接 spec · 管理后台）
+
+- **类型**：前端对接说明（**后端零改动**，数据/信令均已就绪）
+- **端类型**：管理后台（hl-ui，各业务页顶部铃铛）
+- **日期**：2026-06-25
+- **后端联系人**：王骁（wx）
+
+> 现象（wx 反馈）：房务给定制师发了消息，定制师（在 order-v2 订单详情页）顶部铃铛 🔔 **没有红点**。
+> 排查结论：**后端完全正确**（收件方未读已落库、实时信令已推、未读数接口返真值），铃铛没红点是**前端没把未读数接到铃铛上**。
+
+---
+
+## 1 后端已就绪（实测确认）
+
+某条消息发给收件方后，后端做了三件事：
+
+1. **落库未读**：`admin_message`（收件方 adminId、`is_read=0`）+ 收件方 `member.unread_count+1`。实测房务发「4」后 `countUnread(定制师)=1`、`member.unread_count=1`。
+2. **推实时信令**（事务提交后 SSE 广播，跨实例）：
+   - 聊天消息 → 事件 `im-chat`（`type=CHAT`），payload 含 **`unreadCount`=收件方合并未读（NOTIFY+CHAT）**、`conversationKey`、`senderName`、`preview`、`priority`。
+   - 系统通知 → 事件 `message`（`type=NOTIFY`），payload 含 `unreadCount`。
+   - 标记已读后 → 事件 `unread-count`（`type=UNREAD`），payload 含最新 `unreadCount`（角标回落）。
+3. **未读数接口**：`GET /admin/message/unread-count` 返回当前登录员工合并未读总数（含聊天+通知）。
+
+---
+
+## 2 前端要做的（铃铛角标）
+
+铃铛红点/数字 = 当前登录员工的合并未读数，前端需两路驱动：
+
+1. **页面加载时**：调 `GET /admin/message/unread-count` 取初值，>0 显红点/数字。**每个有铃铛的页面都要调**（order-v2 订单详情、房务管家、各工作台…），不能只在某一个页面调。
+2. **实时更新**：订阅 SSE 流（`/ws/admin-msg/stream`，与聊天同一条连接），在以下事件里读 `payload.unreadCount` 刷新铃铛角标：
+   - `im-chat`（收到聊天）→ 取 `unreadCount` 刷角标（红点点亮/数字+1）。
+   - `message`（收到通知）→ 同上。
+   - `unread-count`（自己标已读后）→ 取 `unreadCount` 刷角标（回落）。
+
+> 关键：`im-chat` 事件**既驱动聊天 UI（live append）也驱动铃铛角标**——前端收到 `im-chat` 别只 append 聊天、要同时用 `payload.unreadCount` 刷铃铛。order-v2 订单详情页当前的铃铛大概率①没订阅这条 SSE 流，②或没在加载时调 unread-count，所以收了消息不亮红点。
+
+---
+
+## 3 注意
+
+1. 铃铛角标是**合并未读**（聊天+通知），口径就是 `GET /admin/message/unread-count`，SSE 各事件 payload 的 `unreadCount` 与之一致，直接用即可，不用前端自己累加计数。
+2. SSE 连接要保证在用户登录后的各页面都建立（铃铛是全局组件），否则切到没订阅的页面就收不到实时点亮（刷新时靠 unread-count 兜底）。
+3. 有疑问找后端（王骁/wx）。