# 实时消息推送系统使用指南 ## 🆕 最新更新 (v2.3.0 - 通知体验优化) - ✅ **按优先级区分自动关闭**:紧急通知不自动关闭,重要30秒,普通15秒 - ✅ **简单折叠机制**:最多显示3条通知,超过显示"还有X条"展开按钮 - ✅ **推送频率优化**:60秒推送1-2条(随机),更符合真实金融场景 - ✅ **历史保留增加**:从5条增加到15条,支持查看更多历史通知 - ✅ **集中配置管理**:所有配置统一在 `NOTIFICATION_CONFIG` 中管理 --- ### v2.2.0 更新回顾 - ✅ **浏览器原生通知**:支持系统级通知,即使标签页在后台也能收到 - ✅ **智能分发策略**:根据优先级和页面状态智能选择通知方式 - 紧急(urgent)→ 浏览器通知 + 网页通知(双重保障) - 重要(important)→ 后台=浏览器,前台=网页 - 普通(normal)→ 仅网页通知 - ✅ **权限管理**:测试工具显示权限状态,一键请求授权 - ✅ **点击跳转**:浏览器通知点击聚焦窗口并跳转详情 --- ### v2.1.0 更新回顾 - ✅ **预测通知系统**:支持预测→详情两阶段推送,解决详情延迟生成问题 - ✅ **严格可点击性**:只有真正可跳转的通知才显示"查看详情"和 hover 效果 - ✅ **视觉区分优化**:预测通知显示灰色"预测"徽章和状态提示 - ✅ **测试工具增强**:新增预测通知测试和预测→详情流程测试(5秒延迟) - ✅ **新增字段**:isPrediction、statusHint、relatedPredictionId --- ### v2.0.0 更新回顾 - ✅ **通知类型重构**:4 种金融资讯通知类型(公告、股票、事件、分析) - ✅ **优先级系统**:紧急、重要、普通三级优先级,带视觉标签 - ✅ **智能元数据**:发布时间、作者信息、AI 生成标识 - ✅ **动态配色**:股票动向根据涨跌自动变色(红涨绿跌) - ✅ **点击交互**:支持点击跳转到详情页面,带视觉反馈 - ✅ **统一设计**:所有通知宽度统一为 400px ## 📋 系统概述 本系统是专为**金融资讯场景**设计的实时消息推送系统,支持 Mock 模式(开发)和真实 Socket.IO 模式(生产)。消息以右下角层叠弹窗的形式显示,**新消息在最上方**,符合主流桌面应用的交互习惯。 ### 核心特性 - **双通知系统**:网页通知 + 浏览器原生通知,智能分发 - **4 种通知类型**:公告通知、股票动向、事件动向、分析报告 - **3 级优先级**:紧急(不关闭)、重要(30秒)、普通(15秒)🆕 - **智能折叠**:最多显示3条,超过显示展开按钮 🆕 - **智能配色**:股票动向根据涨跌自动变色(涨红 🔴 / 跌绿 🟢) - **丰富元数据**:发布时间、作者、AI 标识 - **点击跳转**:可配置点击跳转链接 - **队列管理**:最多保留 15 条历史,可展开查看 🆕 --- ## 🎯 功能特性 ### ✅ 已实现功能 1. **4 种通知类型** - **公告通知** (Announcement):财报、重组、分红等公司公告 - **股票动向** (Stock Alert):价格预警、异常波动、持仓表现 - **事件动向** (Event Alert):政策变化、行业事件、宏观消息 - **分析报告** (Analysis Report):行业研报、策略报告、公司研报 2. **3 级优先级系统** - **紧急** (Urgent):红色标签,用于重大事件和高优先级预警 - **重要** (Important):橙色标签,用于重要消息和一般预警 - **普通** (Normal):无标签,用于常规消息和信息推送 3. **智能元数据展示** - **发布时间**:智能格式化(刚刚、X分钟前、今天 HH:mm、昨天 HH:mm、MM-DD HH:mm) - **作者信息**:仅分析报告显示,格式为"作者 - 机构" - **AI 标识**:紫色 AI 徽章,标识 AI 生成的内容 4. **动态配色方案** - **股票动向**:根据 `priceChange` 字段自动判断 - 涨(+):红色系(icon、border、bg、hover) - 跌(-):绿色系 - **其他类型**:固定配色(蓝、橙、紫) 5. **预测通知系统** 🆕 - **预测通知**:事件预测结果,详情未就绪(不可跳转) - **详情通知**:完整报告已生成(可跳转查看) - **视觉区分**: - 预测通知:灰色"预测"徽章 + "详细报告生成中..." 状态提示 - 详情通知:优先级徽章 + "查看详情" 提示 - **典型场景**:先推送预测(T+0秒),延迟推送详情(T+5分钟) 6. **点击交互** - **可点击通知**:鼠标悬停变化、点击跳转到详情页 - **不可点击通知**:静态展示,无交互效果 - **视觉提示**:"📂 查看详情" 提示文本 - **严格判断**:只有 `clickable=true` 且 `link` 存在才可点击 7. **UI 展示** - 右下角固定定位 - **统一宽度 400px** - **新消息在最上方**(符合行业标准) - **从底部向上滑入动画**(浮起效果) - 层叠显示最多 5 条消息 - 智能队列管理:超出自动移除最旧消息 - 视觉层次:最新消息更突出(更强阴影、边框高亮) - 自动关闭(可配置时长,默认 10-12 秒) - 手动关闭按钮 - 流畅的进入/退出动画 8. **音效提示** - 新消息音效播放 - 可开关音效 9. **浏览器原生通知系统** 🆕 - **系统级通知**:显示在操作系统通知中心(Windows/macOS) - **后台可见**:即使标签页不在前台也能收到通知 - **智能分发策略**: - **紧急通知(URGENT)**:浏览器通知 + 网页通知(双重保障) - **重要通知(IMPORTANT)**:后台=浏览器通知,前台=网页通知 - **普通通知(NORMAL)**:仅网页通知 - **权限管理**:自动请求权限,状态实时显示 - **点击跳转**:点击浏览器通知聚焦窗口并跳转详情 - **防重复**:相同类型通知自动替换旧通知 - **自动关闭**:普通通知 8 秒自动关闭,紧急通知需手动关闭 10. **开发工具增强** - 右上角测试工具面板(仅开发环境) - **浏览器权限管理** 🆕: - 显示权限状态(已授权/未授权/已拒绝) - 一键请求权限按钮 - 权限状态实时更新 - **9 种测试场景**: - 公告通知 - 股票上涨 / 股票下跌 - 事件动向 - 分析报告 / AI 报告 - 预测通知(不可跳转) - **3 种组合测试**: - 层叠测试(4 种类型) - 优先级测试(3 个级别) - 预测→详情流程(5秒延迟) - **实时队列状态**:当前消息数 / 5 - 连接状态显示 - 音效开关 - 测试计数统计 --- ## 📁 文件结构 ``` src/ ├── constants/ │ └── notificationTypes.js # 通知类型定义和常量 🆕 ├── services/ │ ├── socket/ │ │ └── index.js # Socket 服务统一导出 │ ├── socketService.js # 真实 Socket.IO 服务 │ └── mockSocketService.js # Mock Socket 服务(含 14 条金融资讯数据)🔄 ├── contexts/ │ └── NotificationContext.js # 通知上下文管理 ├── components/ │ ├── NotificationContainer/ │ │ └── index.js # 通知容器组件(完全重写)🔄 │ └── NotificationTestTool/ │ └── index.js # 测试工具组件(升级 8 种测试)🔄 └── assets/ └── sounds/ └── notification.wav # 通知音效 ``` **图例**:🆕 新增 | 🔄 重构 --- ## 🎨 通知类型配置 ### 类型 1: 公告通知 (Announcement) **适用场景**:公司财报、重大资产重组、分红派息、停复牌公告等 **配色方案**: - 主色:蓝色 (Blue) - 图标:📢 MdCampaign - 背景:`blue.50` - 边框:`blue.400` - 图标色:`blue.500` - 悬停:`blue.100` **示例数据**: ```javascript { type: NOTIFICATION_TYPES.ANNOUNCEMENT, priority: PRIORITY_LEVELS.IMPORTANT, title: '贵州茅台发布2024年度财报公告', content: '2024年度营收同比增长15.2%,净利润创历史新高,董事会建议每10股派息180元', publishTime: 1711611000000, pushTime: Date.now(), isAIGenerated: false, clickable: true, link: '/event-detail/ann001', extra: { announcementType: '财报', companyCode: '600519', companyName: '贵州茅台', }, autoClose: 10000, } ``` --- ### 类型 2: 股票动向 (Stock Alert) **适用场景**:价格预警、异常波动、持仓表现、目标价触达 **配色方案**:**动态配色**(根据 `priceChange` 字段) - **涨(+)**: - 主色:红色 (Red) - 图标:📈 MdTrendingUp - 背景:`red.50` - 边框:`red.400` - 图标色:`red.500` - 悬停:`red.100` - **跌(-)**: - 主色:绿色 (Green) - 图标:📉 MdTrendingDown - 背景:`green.50` - 边框:`green.400` - 图标色:`green.500` - 悬停:`green.100` **示例数据(涨)**: ```javascript { type: NOTIFICATION_TYPES.STOCK_ALERT, priority: PRIORITY_LEVELS.URGENT, title: '您关注的股票触发预警', content: '宁德时代(300750) 当前价格 ¥245.50,盘中涨幅达 +5.2%,已触达您设置的目标价位', publishTime: Date.now(), pushTime: Date.now(), isAIGenerated: false, clickable: true, link: '/stock-overview?code=300750', extra: { stockCode: '300750', stockName: '宁德时代', priceChange: '+5.2%', // 💡 重要:根据此字段判断涨跌 currentPrice: '245.50', triggerType: '目标价', }, autoClose: 10000, } ``` **示例数据(跌)**: ```javascript { type: NOTIFICATION_TYPES.STOCK_ALERT, priority: PRIORITY_LEVELS.IMPORTANT, title: '您关注的股票异常波动', content: '比亚迪(002594) 5分钟内跌幅达 -3.8%,当前价格 ¥198.20,建议关注', publishTime: Date.now(), pushTime: Date.now(), isAIGenerated: false, clickable: true, link: '/stock-overview?code=002594', extra: { stockCode: '002594', stockName: '比亚迪', priceChange: '-3.8%', // 💡 负数:使用绿色配色 currentPrice: '198.20', triggerType: '异常波动', }, autoClose: 10000, } ``` --- ### 类型 3: 事件动向 (Event Alert) **适用场景**:央行政策、行业政策、监管动态、宏观事件 **配色方案**: - 主色:橙色 (Orange) - 图标:📄 MdArticle - 背景:`orange.50` - 边框:`orange.400` - 图标色:`orange.500` - 悬停:`orange.100` **示例数据**: ```javascript { type: NOTIFICATION_TYPES.EVENT_ALERT, priority: PRIORITY_LEVELS.IMPORTANT, title: '央行宣布降准0.5个百分点', content: '中国人民银行宣布下调金融机构存款准备金率0.5个百分点,释放长期资金约1万亿元,利好股市', publishTime: 1711590000000, pushTime: Date.now(), isAIGenerated: false, clickable: true, link: '/event-detail/evt001', extra: { eventId: 'evt001', relatedStocks: 12, impactLevel: '重大利好', sectors: ['银行', '地产', '基建'], }, autoClose: 12000, } ``` --- ### 类型 4: 分析报告 (Analysis Report) **适用场景**:行业研报、策略报告、公司研报、市场分析 **配色方案**: - 主色:紫色 (Purple) - 图标:📊 MdAssessment - 背景:`purple.50` - 边框:`purple.400` - 图标色:`purple.500` - 悬停:`purple.100` **特殊字段**: - `author`:作者信息(必填,包含 `name` 和 `organization`) - `isAIGenerated`:是否 AI 生成(显示紫色 AI 徽章) **示例数据(人工)**: ```javascript { type: NOTIFICATION_TYPES.ANALYSIS_REPORT, priority: PRIORITY_LEVELS.IMPORTANT, title: '医药行业深度报告:创新药迎来政策拐点', content: 'CXO板块持续受益于全球创新药研发外包需求,建议关注药明康德、凯莱英等龙头企业', publishTime: 1711584000000, pushTime: Date.now(), author: { name: '李明', organization: '中信证券', }, isAIGenerated: false, // 人工报告 clickable: true, link: '/forecast-report?id=rpt001', extra: { reportType: '行业研报', industry: '医药', rating: '强烈推荐', }, autoClose: 12000, } ``` **示例数据(AI)**: ```javascript { type: NOTIFICATION_TYPES.ANALYSIS_REPORT, priority: PRIORITY_LEVELS.NORMAL, title: 'AI产业链投资机会分析', content: '随着大模型应用加速落地,算力、数据、应用三大方向均存在投资机会,重点关注海光信息、寒武纪', publishTime: 1711582200000, pushTime: Date.now(), author: { name: 'AI分析师', organization: '价值前沿', }, isAIGenerated: true, // 💡 AI 生成:显示紫色 AI 徽章 clickable: true, link: '/forecast-report?id=rpt002', extra: { reportType: '策略报告', industry: '人工智能', rating: '推荐', }, autoClose: 12000, } ``` --- ## 📊 优先级配置 | 优先级 | 级别 | 颜色主题 | 标签显示 | 使用场景 | |--------|------|---------|---------|----------| | **Urgent** | 紧急 | 🔴 Red | ✅ 显示"紧急" | 重大事件、高优先级预警、异常波动 | | **Important** | 重要 | 🟠 Orange | ✅ 显示"重要" | 重要消息、一般预警、关键公告 | | **Normal** | 普通 | ⚪ Gray | ❌ 不显示 | 常规消息、信息推送、日常报告 | **代码使用**: ```javascript import { PRIORITY_LEVELS } from '../constants/notificationTypes'; // 紧急消息 priority: PRIORITY_LEVELS.URGENT // 重要消息 priority: PRIORITY_LEVELS.IMPORTANT // 普通消息 priority: PRIORITY_LEVELS.NORMAL ``` --- ## 📐 展示逻辑说明 ### 消息排列方式 本系统采用**新消息在最上方**的展示模式,这是桌面应用的行业标准(Windows、macOS、Slack、Discord等)。 ``` 用户视角(右下角): 第1条消息到达: ┌────────────────────────────────────────┐ │ 📢 贵州茅台发布财报 🆕 [重要] │ ↑ 从底部向上滑入(浮起) │ 2024年度营收同比增长15.2%... │ 宽度 400px │ 📅 15分钟前 │ └────────────────────────────────────────┘ 第2条消息到达: ┌────────────────────────────────────────┐ │ 📈 宁德时代触发预警 🆕 [紧急] │ ↑ 新消息(最上方,从下浮起) │ 当前价格 ¥245.50,涨幅 +5.2% │ 红色系(涨) │ 📅 刚刚 | 📂 查看详情 │ ├────────────────────────────────────────┤ │ 📢 贵州茅台发布财报 [重要] │ ↑ 旧消息同时向上推动 │ 2024年度营收同比增长15.2%... │ │ 📅 16分钟前 │ └────────────────────────────────────────┘ 第6条消息到达(超过5条限制): ┌────────────────────────────────────────┐ │ 📊 AI产业链投资机会 🆕 [AI] │ ↑ 最新(从底部滑入) │ 👤 AI分析师 - 价值前沿 │ 紫色系 + AI 徽章 │ 📅 刚刚 | 📂 查看详情 │ ├────────────────────────────────────────┤ │ 📈 宁德时代触发预警 [紧急] │ ↑ 向上推 ├────────────────────────────────────────┤ │ 📢 贵州茅台发布财报 [重要] │ ↑ 向上推 ├────────────────────────────────────────┤ │ 📄 央行宣布降准 [重要] │ ↑ 向上推 ├────────────────────────────────────────┤ │ 📊 医药行业深度报告 │ ↑ 最旧(仍显示) └────────────────────────────────────────┘ ↓ 自动移除 │ 第1条(已移除) │ ``` ### 关键特性 - **统一宽度 400px**:所有通知宽度一致,整齐美观 - **最新消息固定位置**:始终在右下角的顶部,便于快速注意 - **自动队列管理**:最多保留 5 条,超出自动移除最旧的 - **视觉区分**: - 最新消息:boxShadow='2xl' + 边框高亮(4 个边) - 其他消息:boxShadow='lg' + 左边框 - **z-index 层级**:最新消息层级最高(9999),依次递减 - **间距优化**:消息之间 12px 间距(spacing={3}) - **点击反馈**: - 可点击:cursor=pointer,hover 时上移 2px + 阴影增强 - 不可点击:cursor=default,无 hover 效果 --- ## 🚀 快速开始 ### 1. 启用 Mock 模式 在 `.env` 文件中添加: ```bash REACT_APP_ENABLE_MOCK=true # 或 REACT_APP_USE_MOCK_SOCKET=true ``` ### 2. 启动项目 ```bash npm start ``` ### 3. 测试通知 打开浏览器,右上角会显示 **"金融资讯测试工具"**,点击展开后可以: #### 通知类型测试(9 种场景) - **公告通知**:测试蓝色系公告通知 - **股票上涨**:测试红色系股票涨幅预警 - **股票下跌**:测试绿色系股票跌幅预警 - **事件动向**:测试橙色系事件通知 - **分析报告**:测试紫色系人工研报 - **AI 报告**:测试紫色系 AI 研报(带 AI 徽章) - **预测通知**:测试灰色系预测通知(不可跳转)🆕 #### 组合测试(3 种) - **层叠测试(4种类型)**:一次发送 4 条不同类型消息,测试层叠效果 - **优先级测试(3个级别)**:测试紧急、重要、普通三个优先级 - **预测→详情流程**:先推送预测(不可跳转),5秒后推送详情(可跳转)🆕 #### 功能按钮 - **清空全部**:一键清空所有通知 - **音效开关**:切换音效开关 - **队列状态**:实时显示当前队列中的消息数量(X / 5) - **连接状态**:查看 Socket 连接状态和服务类型(MOCK/REAL) ### 4. 自动推送 在 Mock 模式下,系统会自动每 15 秒推送 1-2 条随机金融资讯,用于测试层叠效果。 --- ## 💻 代码使用 ### 在组件中使用通知 ```javascript import { useNotification } from 'contexts/NotificationContext'; import { NOTIFICATION_TYPES, PRIORITY_LEVELS } from 'constants/notificationTypes'; function MyComponent() { const { addNotification, isConnected } = useNotification(); // 示例 1: 公告通知 const handleAnnouncement = () => { addNotification({ type: NOTIFICATION_TYPES.ANNOUNCEMENT, priority: PRIORITY_LEVELS.IMPORTANT, title: '贵州茅台发布2024年度财报公告', content: '2024年度营收同比增长15.2%,净利润创历史新高', publishTime: Date.now(), pushTime: Date.now(), isAIGenerated: false, clickable: true, link: '/event-detail/ann001', extra: { announcementType: '财报', companyCode: '600519', }, autoClose: 10000, }); }; // 示例 2: 股票动向(涨) const handleStockAlert = () => { addNotification({ type: NOTIFICATION_TYPES.STOCK_ALERT, priority: PRIORITY_LEVELS.URGENT, title: '您关注的股票触发预警', content: '宁德时代(300750) 当前价格 ¥245.50,盘中涨幅达 +5.2%', publishTime: Date.now(), pushTime: Date.now(), isAIGenerated: false, clickable: true, link: '/stock-overview?code=300750', extra: { stockCode: '300750', stockName: '宁德时代', priceChange: '+5.2%', // 💡 涨:使用红色配色 currentPrice: '245.50', }, autoClose: 10000, }); }; // 示例 3: 事件动向 const handleEventAlert = () => { addNotification({ type: NOTIFICATION_TYPES.EVENT_ALERT, priority: PRIORITY_LEVELS.IMPORTANT, title: '央行宣布降准0.5个百分点', content: '中国人民银行宣布下调金融机构存款准备金率0.5个百分点', publishTime: Date.now(), pushTime: Date.now(), isAIGenerated: false, clickable: true, link: '/event-detail/evt001', extra: { eventId: 'evt001', relatedStocks: 12, impactLevel: '重大利好', }, autoClose: 12000, }); }; // 示例 4: 分析报告(AI) const handleAnalysisReport = () => { addNotification({ type: NOTIFICATION_TYPES.ANALYSIS_REPORT, priority: PRIORITY_LEVELS.NORMAL, title: 'AI产业链投资机会分析', content: '随着大模型应用加速落地,算力、数据、应用三大方向均存在投资机会', publishTime: Date.now(), pushTime: Date.now(), author: { name: 'AI分析师', organization: '价值前沿', }, isAIGenerated: true, // 💡 显示 AI 徽章 clickable: true, link: '/forecast-report?id=rpt002', extra: { reportType: '策略报告', industry: '人工智能', }, autoClose: 12000, }); }; // 示例 5: 预测通知(不可跳转)🆕 const handlePrediction = () => { addNotification({ type: NOTIFICATION_TYPES.EVENT_ALERT, priority: PRIORITY_LEVELS.NORMAL, title: '【预测】央行可能宣布降准政策', content: '基于最新宏观数据分析,预计央行将在本周宣布降准0.5个百分点', publishTime: Date.now(), pushTime: Date.now(), isAIGenerated: true, clickable: false, // ❌ 不可点击 link: null, extra: { isPrediction: true, // 💡 显示"预测"徽章 statusHint: '详细报告生成中...', // 💡 状态提示 }, autoClose: 15000, }); }; // 示例 6: 预测→详情流程 🆕 const handlePredictionFlow = () => { // 阶段 1: 推送预测 addNotification({ type: NOTIFICATION_TYPES.EVENT_ALERT, priority: PRIORITY_LEVELS.NORMAL, title: '【预测】新能源补贴政策或将延期', content: '根据政策趋势分析,财政部可能宣布新能源汽车购置补贴政策延长至2025年底', publishTime: Date.now(), pushTime: Date.now(), isAIGenerated: true, clickable: false, link: null, extra: { isPrediction: true, statusHint: '详细报告生成中...', relatedPredictionId: 'pred_001', }, autoClose: 15000, }); // 阶段 2: 5分钟后推送详情(实际业务中由后端触发) setTimeout(() => { addNotification({ type: NOTIFICATION_TYPES.EVENT_ALERT, priority: PRIORITY_LEVELS.IMPORTANT, title: '新能源补贴政策延期至2025年底', content: '财政部宣布新能源汽车购置补贴政策延长至2025年底,涉及比亚迪、理想汽车等5家龙头企业', publishTime: Date.now(), pushTime: Date.now(), isAIGenerated: false, clickable: true, // ✅ 可点击 link: '/event-detail/evt001', extra: { isPrediction: false, relatedPredictionId: 'pred_001', // 关联原预测 }, autoClose: 12000, }); }, 300000); // 300000ms = 5分钟 }; return (
连接状态: {isConnected ? '已连接' : '未连接'}