桌面通知（系统级消息提醒

2026-06-05 20:06:50 +08:00
parent e32362f425
commit bdd1ba6052
8 changed files with 383 additions and 17 deletions
@@ -0,0 +1,112 @@
+# 桌面通知功能说明
+
+## 功能概述
+
+系统已集成浏览器桌面通知功能，当收到新消息时会在 Windows/Mac 系统级别发送通知。
+
+## 触发条件
+
+桌面通知会在以下情况触发：
+1. 收到新消息（非自己发送的）
+2. 页面不在前台（浏览器最小化或切换到其他标签页）
+3. 或者正在查看其他会话（不在当前消息的会话页面）
+
+## 通知内容
+
+- **标题**：发送者角色 + 昵称（如："客服 · 张三"）
+- **内容**：消息文本（最多显示100字）
+- **图片消息**：显示 "[图片消息]"
+- **点击通知**：自动跳转到对应会话
+
+## 使用方式
+
+### 用户端
+1. 进入 `/messages` 消息列表页面
+2. 点击页面右上角的铃铛图标
+3. 浏览器会弹出权限请求，点击"允许"
+4. 之后收到新消息时会自动发送桌面通知
+
+### 管理端
+1. 进入 `/admin/chats` 客服管理页面
+2. 首次进入会在用户交互后自动请求权限
+3. 允许权限后即可接收通知
+
+### 移动端
+- iOS Safari：不支持桌面通知
+- Android Chrome：支持桌面通知
+
+## 权限状态
+
+- **未开启**：默认状态，首次需要点击允许
+- **已开启**：绿色铃铛图标，正常接收通知
+- **已拒绝**：用户点击了拒绝，需要在浏览器设置中手动开启
+  - Chrome: 设置 → 隐私和安全 → 网站设置 → 通知
+  - Safari: 偏好设置 → 网站 → 通知
+
+## 技术实现
+
+### 前端文件
+- `frontend/src/features/chats/composables/useDesktopNotification.ts` - 通知核心逻辑
+- `frontend/src/features/chats/components/NotificationSettings.vue` - 通知设置组件
+- `frontend/src/features/chats/views/ChatView.vue` - 用户端聊天页集成
+- `frontend/src/features/chats/views/MobileChatView.vue` - 移动端聊天页集成
+- `frontend/src/features/admin/views/AdminChatsView.vue` - 管理端集成
+
+### 核心 API
+```typescript
+const { notify, requestPermission, permission } = useDesktopNotification('user')
+
+// 发送通知
+notify(chatEvent, currentConversationId)
+
+// 请求权限
+await requestPermission()
+
+// 权限状态：'default' | 'granted' | 'denied'
+console.log(permission.value)
+```
+
+## 浏览器兼容性
+
+| 浏览器 | 桌面通知支持 |
+|--------|-------------|
+| Chrome | ✅ 完全支持 |
+| Firefox | ✅ 完全支持 |
+| Safari (macOS) | ✅ 完全支持 |
+| Edge | ✅ 完全支持 |
+| Safari (iOS) | ❌ 不支持 |
+| 微信内置浏览器 | ❌ 不支持 |
+
+## 通知特性
+
+1. **智能去重**：相同会话的通知会自动替换（不会堆积）
+2. **自动关闭**：通知5秒后自动消失
+3. **点击跳转**：点击通知会自动跳转到对应会话并聚焦浏览器窗口
+4. **不干扰当前会话**：如果正在查看该会话，不会发送通知
+5. **仅限他人消息**：自己发送的消息不会触发通知
+
+## 注意事项
+
+1. **首次使用需要用户授权**：浏览器安全策略要求用户主动允许
+2. **需要 HTTPS**：生产环境必须使用 HTTPS（本地开发 localhost 除外）
+3. **系统勿扰模式**：如果操作系统开启了勿扰模式，通知可能不会显示
+4. **浏览器设置**：用户可以在浏览器设置中随时关闭网站通知
+
+## 测试方法
+
+1. 打开两个浏览器窗口（或使用隐私模式）
+2. 窗口A：登录用户/客服A，进入某个会话
+3. 窗口B：登录用户/客服B，进入相同会话
+4. 在窗口B发送消息
+5. 将窗口A最小化或切换到其他标签页
+6. 应该会收到系统通知
+
+## 排查问题
+
+如果没有收到通知，检查：
+1. 浏览器是否支持 Notification API
+2. 网站通知权限是否被拒绝（检查浏览器地址栏左侧的锁图标）
+3. 操作系统通知设置是否开启
+4. 浏览器是否开启了勿扰模式
+5. 是否在查看当前会话（查看当前会话不会发通知）
+6. 是否是自己发送的消息（自己发送的不会通知）