# 实时消息推送系统使用指南 ## 🆕 最新更新 (v1.1.0) - ✅ **新消息置顶展示**:采用行业标准,新消息显示在最上方 - ✅ **智能队列管理**:最多同时显示 5 条消息,超出自动移除最旧的 - ✅ **视觉层次优化**:最新消息更强的阴影和边框高亮效果 - ✅ **测试工具增强**:实时显示队列状态,新增"测试最大限制"功能 ## 📋 系统概述 本系统实现了完整的实时消息推送功能,支持 Mock 模式(开发)和真实 Socket.IO 模式(生产)。消息以右下角层叠弹窗的形式显示,**新消息在最上方**,符合主流桌面应用的交互习惯。 --- ## 🎯 功能特性 ### ✅ 已实现功能 1. **实时推送** - WebSocket (Socket.IO) 连接 - Mock 模式自动定期推送(开发环境) - 支持多种消息类型(成功、错误、警告、信息) 2. **UI 展示** - 右下角固定定位 - **新消息在最上方**(符合行业标准) - 层叠显示最多 5 条消息 - 智能队列管理:超出自动移除最旧消息 - 视觉层次:最新消息更突出(更强阴影、边框高亮) - 自动关闭(可配置时长) - 手动关闭按钮 - 流畅的进入/退出动画(从右侧滑入) 3. **音效提示** - 新消息音效播放 - 可开关音效 4. **开发工具** - 右上角测试工具面板(仅开发环境) - 手动触发测试通知(4种类型) - 层叠效果测试(4条消息) - 最大限制测试(6条→5条) - **实时队列状态显示**(当前消息数 / 5) - 连接状态显示 - 音效开关 - 测试计数统计 --- ## 📁 文件结构 ``` src/ ├── services/ │ ├── socket/ │ │ └── index.js # Socket 服务统一导出 │ ├── socketService.js # 真实 Socket.IO 服务 │ └── mockSocketService.js # Mock Socket 服务 ├── contexts/ │ └── NotificationContext.js # 通知上下文管理 ├── components/ │ ├── NotificationContainer/ │ │ └── index.js # 通知容器组件 │ └── NotificationTestTool/ │ └── index.js # 测试工具组件 └── assets/ └── sounds/ └── notification.wav # 通知音效 ``` --- ## 📐 展示逻辑说明 ### 消息排列方式 本系统采用**新消息在最上方**的展示模式,这是桌面应用的行业标准(Windows、macOS、Slack、Discord等)。 ``` 用户视角(右下角): 第1条消息到达: ┌────────────────────┐ │ 🔔 买入成功 🆕 │ ← 从右侧滑入 └────────────────────┘ 第2条消息到达: ┌────────────────────┐ │ 🔔 价格预警 🆕 │ ← 新消息(最上方) ├────────────────────┤ │ 🔔 买入成功 │ ← 旧消息向下平移 └────────────────────┘ 第6条消息到达(超过5条限制): ┌────────────────────┐ │ 🔔 第6条 🆕 │ ← 最新 ├────────────────────┤ │ 🔔 第5条 │ ├────────────────────┤ │ 🔔 第4条 │ ├────────────────────┤ │ 🔔 第3条 │ ├────────────────────┤ │ 🔔 第2条 │ ← 最旧(仍显示) └────────────────────┘ ↓ 自动移除 │ 第1条(已移除) │ ``` ### 关键特性 - **最新消息固定位置**:始终在右下角的顶部,便于快速注意 - **自动队列管理**:最多保留 5 条,超出自动移除最旧的 - **视觉区分**:最新消息有更强的阴影(2xl vs lg)和边框高亮 - **z-index 层级**:最新消息层级最高(9999),依次递减 - **间距优化**:消息之间 12px 间距(spacing={3}) --- ## 🚀 快速开始 ### 1. 启用 Mock 模式 在 `.env` 文件中添加: ```bash REACT_APP_ENABLE_MOCK=true # 或 REACT_APP_USE_MOCK_SOCKET=true ``` ### 2. 启动项目 ```bash npm start ``` ### 3. 测试通知 打开浏览器,右上角会显示 **"通知测试工具"**,点击展开后可以: - **单条测试**:测试不同类型的通知(成功、错误、警告、信息) - **层叠测试**:一次发送 4 条消息,测试层叠效果 - **最大限制测试**:发送 6 条消息,验证只保留最新 5 条 - **队列状态**:实时显示当前队列中的消息数量(X / 5) - **音效控制**:切换音效开关 - **清空功能**:一键清空所有通知 - **连接状态**:查看 Socket 连接状态和服务类型(MOCK/REAL) ### 4. 自动推送 在 Mock 模式下,系统会自动每 20 秒推送 1-2 条随机消息,用于测试层叠效果。 --- ## 💻 代码使用 ### 在组件中使用通知 ```javascript import { useNotification } from 'contexts/NotificationContext'; function MyComponent() { const { addNotification, isConnected } = useNotification(); const handleTradeSuccess = () => { addNotification({ type: 'trade_alert', severity: 'success', title: '买入成功', message: '您的订单已成功执行:买入 贵州茅台(600519) 100股', autoClose: 8000, // 8秒后自动关闭 }); }; return (

连接状态: {isConnected ? '已连接' : '未连接'}

); } ``` ### 消息格式 ```javascript { type: 'trade_alert', // 消息类型 severity: 'info', // 'success' | 'error' | 'warning' | 'info' title: '通知标题', // 主标题 message: '详细消息内容', // 详细内容 timestamp: Date.now(), // 时间戳(自动生成) autoClose: 8000, // 自动关闭时长(毫秒),0 或 false 表示不自动关闭 id: 'unique_id' // 唯一ID(自动生成) } ``` --- ## 🔧 配置说明 ### Mock 服务配置 在 `src/services/mockSocketService.js` 中可以配置: ```javascript // 修改模拟数据 const mockTradeAlerts = [ { severity: 'success', title: '自定义标题', message: '自定义消息', autoClose: 8000, }, // 添加更多... ]; // 调整推送频率 socket.startMockPush(20000, 2); // 每20秒推送1-2条 ``` ### NotificationContext 配置 在 `src/contexts/NotificationContext.js` 中: ```javascript // 修改最大消息数量(默认 5 条) const maxNotifications = 5; // 修改为其他数值 // 修改默认音效状态 const [soundEnabled, setSoundEnabled] = useState(true); // false 关闭音效 // 修改音效音量 audioRef.current.volume = 0.5; // 0.0 - 1.0 ``` ### NotificationContainer 配置 在 `src/components/NotificationContainer/index.js` 中: ```javascript // 调整消息间距 // 3 = 12px, 4 = 16px, 2 = 8px // 调整位置 ``` --- ## 🌐 后端集成(生产环境) ### 1. Flask 后端配置 当 `REACT_APP_ENABLE_MOCK=false` 时,系统会连接真实的 Socket.IO 服务器。 在 `app.py` 中初始化 Flask-SocketIO: ```python from flask_socketio import SocketIO, emit # 初始化 SocketIO socketio = SocketIO(app, cors_allowed_origins=[ "http://localhost:3000", "https://valuefrontier.cn" ]) # 连接事件 @socketio.on('connect') def handle_connect(): print(f'Client connected: {request.sid}') # 推送交易通知 def send_trade_notification(user_id, data): """ 推送交易通知到指定用户 """ emit('trade_notification', data, room=user_id) # 启动服务器 if __name__ == '__main__': socketio.run(app, host='0.0.0.0', port=5001) ``` ### 2. 后端推送示例 ```python # 交易成功后推送通知 socketio.emit('trade_notification', { 'type': 'trade_alert', 'severity': 'success', 'title': '买入成功', 'message': f'买入 {stock_name}({stock_code}) {quantity}股', 'timestamp': int(time.time() * 1000), 'autoClose': 8000 }, room=user_id) ``` --- ## 🎨 自定义样式 ### 修改通知位置 在 `src/components/NotificationContainer/index.js`: ```javascript ``` ### 修改通知颜色 在 `src/components/NotificationContainer/index.js` 中的 `NOTIFICATION_STYLES`: ```javascript const NOTIFICATION_STYLES = { success: { icon: MdCheckCircle, colorScheme: 'green', // 修改颜色主题 bg: 'green.50', borderColor: 'green.400', iconColor: 'green.500', }, // ... }; ``` --- ## 🐛 故障排除 ### 问题 1: 通知不显示 **检查项:** 1. 确认 `NotificationProvider` 已包裹应用 2. 检查浏览器控制台是否有错误 3. 确认 socket 连接状态(查看测试工具) ### 问题 2: 音效不播放 **解决方案:** 1. 检查浏览器是否允许自动播放音频 2. 确认音效开关已打开 3. 检查音频文件路径是否正确 ### 问题 3: Mock 推送不工作 **检查项:** 1. 确认 `.env` 中设置了 `REACT_APP_ENABLE_MOCK=true` 2. 查看控制台日志确认 Mock 服务已启动 3. 检查 `startMockPush` 是否被调用 ### 问题 4: Socket 连接失败 **解决方案:** 1. 检查后端 Flask-SocketIO 是否正确运行 2. 确认 CORS 配置正确 3. 检查 `src/utils/apiConfig.js` 中的 API 地址 --- ## 📊 性能优化建议 1. **智能队列管理** ✅ 已实现 - 系统自动限制最多 5 条通知 - 超出自动移除最旧的,避免内存泄漏 - 建议根据实际需求调整 `maxNotifications` 值 2. **合理设置自动关闭时长** - 建议 5-10 秒(默认 8 秒) - 重要消息可设置更长时间或 `autoClose: false` 3. **避免频繁推送** - 生产环境建议间隔至少 3 秒 - 避免短时间内大量推送造成用户困扰 4. **视觉性能优化** ✅ 已实现 - 使用 Chakra UI 的优化动画(Slide、ScaleFade) - z-index 合理分配,避免层叠问题 - 间距适中(12px),不会过于紧密 --- ## 🔮 未来扩展 可以考虑添加的功能: 1. ✨ 通知历史记录 2. ✨ 通知分类过滤 3. ✨ 通知优先级 4. ✨ 通知持久化(存储到 localStorage) 5. ✨ 通知点击交互(跳转到相关页面) 6. ✨ 用户偏好设置(通知类型开关) --- ## 📝 更新日志 ### v1.1.0 (2025-01-21) - 交互优化版 - ✅ **新消息置顶展示**(行业标准,参考 Windows/macOS/Slack) - ✅ **智能队列管理**:最多保留 5 条,超出自动移除最旧的 - ✅ **视觉层次优化**: - 最新消息:boxShadow='2xl' + 边框高亮 - 其他消息:boxShadow='lg' - 消息间距:12px(spacing={3}) - ✅ **z-index 优化**:最新消息层级最高(9999),依次递减 - ✅ **测试工具增强**: - 新增"测试最大限制"按钮(6条→5条) - 实时显示队列状态(X / 5) - 队列满时红色提示 - ✅ **文档完善**:添加展示逻辑说明、配置指南 ### v1.0.0 (2025-01-20) - 初始版本 - ✅ 实现基础通知系统 - ✅ 支持 Mock 和真实 Socket.IO 模式 - ✅ 右下角层叠显示 - ✅ 音效提示 - ✅ 开发工具面板 - ✅ 4 种消息类型(成功、错误、警告、信息) --- ## 💡 技术栈 - **前端框架**: React 18.3.1 - **UI 库**: Chakra UI 2.8.2 - **实时通信**: Socket.IO Client 4.7.4 - **后端框架**: Flask-SocketIO 5.3.6 - **状态管理**: React Context API --- ## 📞 支持 如有问题,请查看: - 项目文档: `CLAUDE.md` - 测试工具: 开发环境右上角 - 控制台日志: 所有操作都有详细日志 --- **祝你使用愉快!** 🎉