Files

zdl 09db05c448 docs: 将所有文档迁移到 docs/ 目录

- 移动42个文档文件到 docs/ 目录
  - 更新 .gitignore 允许 docs/ 下的 .md 文件
  - 删除根目录下的重复文档文件

  📁 文档分类：
  - StockDetailPanel 重构文档（3个）
  - PostHog 集成文档（6个）
  - 系统架构和API文档（33个）

  🤖 Generated with [Claude Code](https://claude.com/claude-code)

  Co-Authored-By: Claude <noreply@anthropic.com>

2025-10-30 14:51:22 +08:00

54 KiB

Raw Blame History

实时消息推送系统使用指南

🆕 最新更新 (v2.11.0 - Socket 连接优化)

优化内容

1. 指数退避策略 🔄

✅ 智能重连间隔：从"激进"改为"渐进"策略
- Real Socket: 第1次 1分钟 → 第2次 2分钟 → 第3次+ 4分钟
- Mock Socket: 第1次 10秒 → 第2次 20秒 → 第3次+ 40秒（缩短10倍便于测试）
✅ 无限重试：不再在5次后停止，持续使用指数退避重连
✅ 自定义退避逻辑：禁用 Socket.IO 默认重连机制，实现更可控的重连策略

2. 连接状态横幅优化 📍

✅ 降低侵入性：zIndex 从 10000 → 1050，高度 py={3} → py={2}，半透明背景（opacity 0.95）
✅ 手动关闭：所有状态（DISCONNECTED/RECONNECTING/FAILED）都可手动关闭
✅ 状态持久化：用户关闭后保存到 localStorage，重连成功后自动清除
✅ 自动消失：重连成功显示"✓ 已重新连接" 2秒后自动消失
✅ 无限次数显示：支持 Infinity 最大重连次数，显示"尝试重连中 (第 N 次)"

3. Mock 模式测试功能 🧪

✅ 断线重连模拟：__mockSocket.simulateDisconnection() - 模拟意外断线，自动重连
✅ 连接状态查询：__mockSocket.isConnected() - 查看当前连接状态
✅ 手动重连：__mockSocket.reconnect() - 立即触发重连
✅ 重连次数查询：__mockSocket.getAttempts() - 查看当前重连次数
✅ 控制台提示：开发模式启动时自动显示可用测试函数

4. 环境说明 🌍

✅ 清晰注释：在 NotificationContext.js 添加详细的环境说明
- SOCKET_TYPE === 'REAL'：使用真实 Socket.IO，连接 wss://valuefrontier.cn（生产环境）
- SOCKET_TYPE === 'MOCK'：使用模拟服务（开发环境），用于本地测试
✅ 环境切换：设置 REACT_APP_ENABLE_MOCK=true 或 REACT_APP_USE_MOCK_SOCKET=true 切换到 MOCK 模式

测试方法

Mock 模式下测试断线重连：

启用 Mock 模式：

# .env 文件
REACT_APP_ENABLE_MOCK=true

场景1：模拟断线（自动重连成功）

打开控制台，运行以下命令：

// 查看可用测试函数
console.log(window.__mockSocket);

// 模拟断线（自动重连）
__mockSocket.simulateDisconnection();

// 观察重连过程：
// - 连接状态横幅会出现（"正在重新连接"）
// - 重连次数递增（第1次 10s → 第2次 20s → 第3次 40s）
// - 重连成功后显示"✓ 已重新连接" 2秒后自动消失

// 查看连接状态
__mockSocket.isConnected();  // true/false

// 查看重连次数
__mockSocket.getAttempts();  // 0, 1, 2, 3...

// 手动重连（立即重置重连次数）
__mockSocket.reconnect();

场景2：模拟持续连接失败 🆕

打开控制台，运行以下命令：

// 模拟持续连接失败
__mockSocket.simulateConnectionFailure();

// 观察效果：
// - 连接状态横幅出现："正在重新连接 (第 1 次)"
// - 10秒后："正在重新连接 (第 2 次)"
// - 20秒后："正在重新连接 (第 3 次)"
// - 40秒后："正在重新连接 (第 4 次)"
// - 继续以 40秒间隔重试... (第 5/6/7... 次)

// 测试手动关闭横幅
// 点击横幅右侧的 ✕ 按钮 → 横幅消失

// 查看重连次数（后台仍在重连）
__mockSocket.getAttempts();  // 递增中...

// 允许下次重连成功
__mockSocket.allowReconnection();

// 观察效果：
// - 如果横幅已关闭：下次重连成功时会重新出现 "✓ 已重新连接"，2秒后消失
// - 如果横幅未关闭：直接显示 "✓ 已重新连接"，2秒后消失

// 也可以手动立即重连
__mockSocket.reconnect();  // 立即成功（如果已调用 allowReconnection）

测试手动关闭：
- 模拟断线后，点击状态横幅右侧的 ✕ 按钮
- 横幅消失，保存到 localStorage
- 重连成功后，横幅会重新出现 2秒（"✓ 已重新连接"）然后自动消失

测试函数速查表

函数	说明	使用场景
`__mockSocket.simulateDisconnection()`	模拟断线，自动重连成功	测试正常重连流程
`__mockSocket.simulateConnectionFailure()`	模拟持续连接失败	测试重连失败、指数退避
`__mockSocket.allowReconnection()`	允许下次重连成功	配合 `simulateConnectionFailure()` 使用
`__mockSocket.isConnected()`	查看当前连接状态	调试连接状态
`__mockSocket.reconnect()`	手动立即重连	测试"立即重试"按钮
`__mockSocket.getAttempts()`	查看当前重连次数	验证指数退避逻辑

技术细节

文件修改：
- src/services/socketService.js - 指数退避逻辑，无限重试
- src/services/mockSocketService.js - 模拟断线重连，测试函数
- src/components/ConnectionStatusBar/index.js - UI 优化，手动关闭
- src/App.js - dismissed 状态管理，localStorage 持久化
- src/contexts/NotificationContext.js - 重连成功检测，maxReconnectAttempts 导出

v2.10.0 更新回顾

✅ 按钮加载态：点击"查看详情"后按钮显示 loading spinner，文字变为"跳转中..."（蓝色）
✅ 防重复点击：加载状态时禁用再次点击，cursor 变为 wait，避免误操作
✅ 延迟关闭：跳转后延迟 300ms 关闭通知，给用户足够的视觉反馈
✅ 整卡禁用：加载时通知变半透明（opacity 0.7），禁用所有交互（pointerEvents: none）
✅ 流畅体验：使用 Chakra UI Spinner (size="xs") 匹配图标大小，视觉一致
✅ 状态一致性：Loading 时 hover 效果禁用，确保用户知道正在跳转

v2.9.0 更新回顾

✅ 头部简化：移除 AI 和预测标签，只保留优先级标签（紧急/重要），避免换行拥挤
✅ 底部补充：AI 和预测标识移到底部元数据区，使用 xs size 小徽章，信息不丢失
✅ 预测状态合并：预测徽章与状态提示（"详细报告生成中..."）合并显示，更紧凑
✅ 响应式优化：移动端底部只显示时间和操作提示，AI/预测标识在小屏及以上显示
✅ 元数据顺序调整：时间优先，然后AI、预测、作者、操作提示，信息层次清晰
✅ 视觉平衡：头部更简洁清爽，优先级标签更醒目，辅助信息完整保留

v2.8.0 更新回顾

✅ ARIA 完全支持：为所有通知添加完整的 ARIA 属性（role、aria-live、aria-atomic、aria-label）
✅ 智能角色分配：紧急通知使用 role="alert" + aria-live="assertive"，其他使用 role="status" + aria-live="polite"
✅ 键盘导航：可点击通知支持 Tab 键聚焦，Enter/Space 键打开详情
✅ 屏幕阅读器优化：自动生成完整描述（类型、优先级、标题、内容、时间、操作提示）
✅ 焦点管理：添加蓝色聚焦轮廓（2px solid blue.500），符合 WCAG 2.1 AA 标准
✅ 关闭按钮增强：支持键盘操作，aria-label 包含通知标题
✅ 展开/收起按钮：aria-expanded 状态提示，描述性 aria-label
✅ 容器区域标识：通知中心使用 role="region"，动态更新统计信息

v2.7.0 更新回顾

✅ 智能动画：只对新增通知应用动画，已存在通知直接显示
✅ 移除双层嵌套：去除 ScaleFade，只保留 Slide 动画
✅ 展开/收起优化：展开15条通知无动画，避免卡顿
✅ 性能提升90%+：动画数量从30个减少到1-2个
✅ GPU 加速：添加 willChange CSS 优化

v2.6.0 更新回顾

✅ 状态持久化：展开/收起状态保存到 localStorage，刷新页面后保持
✅ 2分钟自动过期：展开状态2分钟后自动重置为收起，避免长期展开
✅ 跨标签页实时同步：多个标签页展开/收起状态自动同步
✅ 智能过期检查：每10秒自动检查过期，无需刷新页面
✅ 优雅降级：localStorage 不可用时仍正常工作

v2.5.0 更新回顾

✅ 避开设置按钮：桌面端底部偏移112px，完全避开右下角设置按钮冲突
✅ 响应式偏移：移动端保持12px贴近底部，桌面端112px留足空间
✅ 视觉优化：通知位置更合理，不再遮挡其他固定元素

v2.4.0 更新回顾

✅ 响应式宽度：移动端屏宽-32px，小屏360px，平板380px，桌面400px
✅ 响应式信息密度：移动端精简显示（标题1行、内容2行），桌面完整显示
✅ 响应式元数据：移动端仅显示时间，小屏+状态，平板+作者信息
✅ 响应式间距：移动端12px边距，平板+24px边距
✅ 完美适配：在手机、平板、桌面各种设备上都能舒适阅读

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 条历史，可展开查看 🆕

🎯 功能特性

✅ 已实现功能

4 种通知类型
- 公告通知 (Announcement)：财报、重组、分红等公司公告
- 股票动向 (Stock Alert)：价格预警、异常波动、持仓表现
- 事件动向 (Event Alert)：政策变化、行业事件、宏观消息
- 分析报告 (Analysis Report)：行业研报、策略报告、公司研报
3 级优先级系统
- 紧急 (Urgent)：红色标签，用于重大事件和高优先级预警
- 重要 (Important)：橙色标签，用于重要消息和一般预警
- 普通 (Normal)：无标签，用于常规消息和信息推送
智能元数据展示
- 发布时间：智能格式化（刚刚、X分钟前、今天 HH:mm、昨天 HH:mm、MM-DD HH:mm）
- 作者信息：仅分析报告显示，格式为"作者 - 机构"
- AI 标识：紫色 AI 徽章，标识 AI 生成的内容
动态配色方案
- 股票动向：根据 priceChange 字段自动判断
  - 涨（+）：红色系（icon、border、bg、hover）
  - 跌（-）：绿色系
- 其他类型：固定配色（蓝、橙、紫）
预测通知系统 🆕
- 预测通知：事件预测结果，详情未就绪（不可跳转）
- 详情通知：完整报告已生成（可跳转查看）
- 视觉区分：
  - 预测通知：灰色"预测"徽章 + "详细报告生成中..." 状态提示
  - 详情通知：优先级徽章 + "查看详情" 提示
- 典型场景：先推送预测（T+0秒），延迟推送详情（T+5分钟）
点击交互
- 可点击通知：鼠标悬停变化、点击跳转到详情页
- 不可点击通知：静态展示，无交互效果
- 视觉提示："📂 查看详情" 提示文本
- 严格判断：只有 clickable=true 且 link 存在才可点击
UI 展示
- 右下角固定定位
- 统一宽度 400px
- 新消息在最上方（符合行业标准）
- 从底部向上滑入动画（浮起效果）
- 层叠显示最多 5 条消息
- 智能队列管理：超出自动移除最旧消息
- 视觉层次：最新消息更突出（更强阴影、边框高亮）
- 自动关闭（可配置时长，默认 10-12 秒）
- 手动关闭按钮
- 流畅的进入/退出动画
音效提示
- 新消息音效播放
- 可开关音效
浏览器原生通知系统 🆕
- 系统级通知：显示在操作系统通知中心（Windows/macOS）
- 后台可见：即使标签页不在前台也能收到通知
- 智能分发策略：
  - 紧急通知（URGENT）：浏览器通知 + 网页通知（双重保障）
  - 重要通知（IMPORTANT）：后台=浏览器通知，前台=网页通知
  - 普通通知（NORMAL）：仅网页通知
- 权限管理：自动请求权限，状态实时显示
- 点击跳转：点击浏览器通知聚焦窗口并跳转详情
- 防重复：相同类型通知自动替换旧通知
- 自动关闭：普通通知 8 秒自动关闭，紧急通知需手动关闭
开发工具增强
- 右上角测试工具面板（仅开发环境）
- 浏览器权限管理 🆕：
  - 显示权限状态（已授权/未授权/已拒绝）
  - 一键请求权限按钮
  - 权限状态实时更新
- 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

示例数据：

{
    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

示例数据（涨）：

{
    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,
}

示例数据（跌）：

{
    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

示例数据：

{
    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 徽章）

示例数据（人工）：

{
    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）：

{
    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	❌ 不显示	常规消息、信息推送、日常报告

代码使用：

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 文件中添加：

REACT_APP_ENABLE_MOCK=true
# 或
REACT_APP_USE_MOCK_SOCKET=true

2. 启动项目

npm start

3. 测试通知

打开浏览器，右上角会显示 "金融资讯测试工具"，点击展开后可以：

通知类型测试（9 种场景）

公告通知：测试蓝色系公告通知
股票上涨：测试红色系股票涨幅预警
股票下跌：测试绿色系股票跌幅预警
事件动向：测试橙色系事件通知
分析报告：测试紫色系人工研报
AI 报告：测试紫色系 AI 研报（带 AI 徽章）
预测通知：测试灰色系预测通知（不可跳转）🆕

组合测试（3 种）

层叠测试（4种类型）：一次发送 4 条不同类型消息，测试层叠效果
优先级测试（3个级别）：测试紧急、重要、普通三个优先级
预测→详情流程：先推送预测（不可跳转），5秒后推送详情（可跳转）🆕

功能按钮

清空全部：一键清空所有通知
音效开关：切换音效开关
队列状态：实时显示当前队列中的消息数量（X / 5）
连接状态：查看 Socket 连接状态和服务类型（MOCK/REAL）

4. 自动推送

在 Mock 模式下，系统会自动每 15 秒推送 1-2 条随机金融资讯，用于测试层叠效果。

💻 代码使用

在组件中使用通知

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 (
        <div>
            <p>连接状态: {isConnected ? '已连接' : '未连接'}</p>
            <button onClick={handleAnnouncement}>公告通知</button>
            <button onClick={handleStockAlert}>股票预警</button>
            <button onClick={handleEventAlert}>事件动向</button>
            <button onClick={handleAnalysisReport}>分析报告</button>
            <button onClick={handlePrediction}>预测通知</button>
            <button onClick={handlePredictionFlow}>预测→详情流程</button>
        </div>
    );
}

消息格式（v2.0.0）

{
    // 必填字段
    type: 'announcement' | 'stock_alert' | 'event_alert' | 'analysis_report',
    priority: 'urgent' | 'important' | 'normal',
    title: '通知标题',
    content: '详细消息内容',

    // 时间字段
    publishTime: 1711611000000,     // 发布时间（毫秒时间戳）
    pushTime: Date.now(),           // 推送时间（毫秒时间戳）

    // 元数据
    isAIGenerated: false,           // 是否 AI 生成（显示 AI 徽章）
    clickable: true,                // 是否可点击
    link: '/event-detail/ann001',   // 点击跳转链接

    // 作者信息（仅 analysis_report 需要）
    author: {
        name: '李明',
        organization: '中信证券',
    },

    // 额外信息（自定义，根据类型不同）
    extra: {
        // announcement
        announcementType: '财报',
        companyCode: '600519',

        // stock_alert
        stockCode: '300750',
        priceChange: '+5.2%',       // 💡 重要：涨跌判断依据
        currentPrice: '245.50',

        // event_alert
        eventId: 'evt001',
        relatedStocks: 12,
        impactLevel: '重大利好',

        // analysis_report
        reportType: '行业研报',
        industry: '医药',
        rating: '强烈推荐',

        // 🆕 预测通知专用字段
        isPrediction: true,         // 是否为预测通知（显示"预测"徽章）
        statusHint: '详细报告生成中...',  // 状态提示文字（可选）
        relatedPredictionId: 'pred_001',  // 关联预测ID（用于追溯，可选）
    },

    // 自动关闭
    autoClose: 10000,               // 毫秒，0 或 false 表示不自动关闭

    // 自动生成字段（无需手动设置）
    id: 'unique_id',                // 自动生成
    timestamp: Date.now(),          // 自动生成
}

🔧 配置说明

Mock 服务配置

在 src/services/mockSocketService.js 中可以配置：

// 修改模拟数据（14 条金融资讯）
const mockFinancialNews = [
    // 3 条公告通知
    {
        type: NOTIFICATION_TYPES.ANNOUNCEMENT,
        priority: PRIORITY_LEVELS.IMPORTANT,
        title: '贵州茅台发布2024年度财报公告',
        content: '2024年度营收同比增长15.2%，净利润创历史新高...',
        // ...
    },

    // 3 条股票动向
    {
        type: NOTIFICATION_TYPES.STOCK_ALERT,
        priority: PRIORITY_LEVELS.URGENT,
        title: '您关注的股票触发预警',
        content: '宁德时代(300750) 当前价格 ¥245.50，涨幅 +5.2%...',
        extra: {
            priceChange: '+5.2%',  // 红色（涨）
        },
        // ...
    },

    // 3 条事件动向
    {
        type: NOTIFICATION_TYPES.EVENT_ALERT,
        priority: PRIORITY_LEVELS.IMPORTANT,
        title: '央行宣布降准0.5个百分点',
        // ...
    },

    // 4 条分析报告（2 条人工 + 2 条 AI）
    {
        type: NOTIFICATION_TYPES.ANALYSIS_REPORT,
        priority: PRIORITY_LEVELS.IMPORTANT,
        author: {
            name: '李明',
            organization: '中信证券',
        },
        isAIGenerated: false,
        // ...
    },
    {
        type: NOTIFICATION_TYPES.ANALYSIS_REPORT,
        author: {
            name: 'AI分析师',
            organization: '价值前沿',
        },
        isAIGenerated: true,  // AI 徽章
        // ...
    },
];

// 调整推送频率
socket.startMockPush(15000, 1); // 每15秒推送1条

通知类型常量配置

在 src/constants/notificationTypes.js 中可以修改：

// 修改类型配色
export const NOTIFICATION_TYPE_CONFIGS = {
    [NOTIFICATION_TYPES.ANNOUNCEMENT]: {
        name: '公告通知',
        icon: MdCampaign,
        colorScheme: 'blue',  // 修改颜色主题
        bg: 'blue.50',
        borderColor: 'blue.400',
        iconColor: 'blue.500',
        hoverBg: 'blue.100',
    },
    // ...
};

// 修改优先级标签
export const PRIORITY_CONFIGS = {
    [PRIORITY_LEVELS.URGENT]: {
        label: '紧急',
        colorScheme: 'red',
        show: true,
    },
    // ...
};

NotificationContext 配置

在 src/contexts/NotificationContext.js 中：

// 修改最大消息数量（默认 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 中：

// 调整通知宽度（默认 400px）
<Box w="400px">  // 修改为其他数值

// 调整动画方向
<Slide direction="bottom">  // bottom=从下向上, right=从右向左

// 调整消息间距
<VStack spacing={3}>  // 3 = 12px, 4 = 16px, 2 = 8px

// 调整位置
<Box
    position="fixed"
    bottom={6}  // 修改为 top={6} 可以显示在右上角
    right={6}   // 修改为 left={6} 可以显示在左侧
>

🌐 后端集成（生产环境）

1. Flask 后端配置

当 REACT_APP_ENABLE_MOCK=false 时，系统会连接真实的 Socket.IO 服务器。

在 app.py 中初始化 Flask-SocketIO：

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_financial_notification(user_id, data):
    """
    推送金融资讯通知到指定用户

    参数:
        user_id: 用户ID
        data: 通知数据（参考 v2.0.0 消息格式）
    """
    emit('trade_notification', data, room=user_id)

# 启动服务器
if __name__ == '__main__':
    socketio.run(app, host='0.0.0.0', port=5001)

2. 后端推送示例

import time

# 示例 1: 公告通知
socketio.emit('trade_notification', {
    'type': 'announcement',
    'priority': 'important',
    'title': '贵州茅台发布2024年度财报公告',
    'content': '2024年度营收同比增长15.2%，净利润创历史新高',
    'publishTime': int(time.time() * 1000),
    'pushTime': int(time.time() * 1000),
    'isAIGenerated': False,
    'clickable': True,
    'link': '/event-detail/ann001',
    'extra': {
        'announcementType': '财报',
        'companyCode': '600519',
        'companyName': '贵州茅台',
    },
    'autoClose': 10000
}, room=user_id)

# 示例 2: 股票动向（涨）
socketio.emit('trade_notification', {
    'type': 'stock_alert',
    'priority': 'urgent',
    'title': '您关注的股票触发预警',
    'content': f'宁德时代(300750) 当前价格 ¥{current_price}，涨幅 +{change_percent}%',
    'publishTime': int(time.time() * 1000),
    'pushTime': int(time.time() * 1000),
    'isAIGenerated': False,
    'clickable': True,
    'link': '/stock-overview?code=300750',
    'extra': {
        'stockCode': '300750',
        'stockName': '宁德时代',
        'priceChange': f'+{change_percent}%',  # 涨：红色
        'currentPrice': str(current_price),
    },
    'autoClose': 10000
}, room=user_id)

# 示例 3: 事件动向
socketio.emit('trade_notification', {
    'type': 'event_alert',
    'priority': 'important',
    'title': '央行宣布降准0.5个百分点',
    'content': '中国人民银行宣布下调金融机构存款准备金率0.5个百分点',
    'publishTime': int(time.time() * 1000),
    'pushTime': int(time.time() * 1000),
    'isAIGenerated': False,
    'clickable': True,
    'link': '/event-detail/evt001',
    'extra': {
        'eventId': 'evt001',
        'relatedStocks': 12,
        'impactLevel': '重大利好',
    },
    'autoClose': 12000
}, room=user_id)

# 示例 4: 分析报告（AI）
socketio.emit('trade_notification', {
    'type': 'analysis_report',
    'priority': 'normal',
    'title': 'AI产业链投资机会分析',
    'content': '随着大模型应用加速落地，算力、数据、应用三大方向均存在投资机会',
    'publishTime': int(time.time() * 1000),
    'pushTime': int(time.time() * 1000),
    'author': {
        'name': 'AI分析师',
        'organization': '价值前沿',
    },
    'isAIGenerated': True,  # AI 徽章
    'clickable': True,
    'link': '/forecast-report?id=rpt002',
    'extra': {
        'reportType': '策略报告',
        'industry': '人工智能',
        'rating': '推荐',
    },
    'autoClose': 12000
}, room=user_id)

🐛 故障排除

问题 1: 通知不显示

检查项：

确认 NotificationProvider 已包裹应用
检查浏览器控制台是否有错误
确认 socket 连接状态（查看测试工具）
检查通知数据格式是否正确（参考 v2.0.0 消息格式）

问题 2: 股票动向颜色不对

解决方案：

检查 extra.priceChange 字段是否存在
确认 priceChange 格式为 "+5.2%" 或 "-3.8%"（包含符号）
确认使用了 NOTIFICATION_TYPES.STOCK_ALERT 类型

问题 3: AI 徽章不显示

解决方案：

检查 isAIGenerated 字段是否为 true
确认字段名拼写正确（驼峰命名）

问题 4: 点击跳转不工作

解决方案：

检查 clickable 字段是否为 true
确认 link 字段存在且格式正确
检查路由配置是否正确

问题 5: 音效不播放

解决方案：

检查浏览器是否允许自动播放音频
确认音效开关已打开
检查音频文件路径是否正确

问题 6: Mock 推送不工作

检查项：

确认 .env 中设置了 REACT_APP_ENABLE_MOCK=true
查看控制台日志确认 Mock 服务已启动
检查 startMockPush 是否被调用

问题 7: Socket 连接失败

解决方案：

检查后端 Flask-SocketIO 是否正确运行
确认 CORS 配置正确
检查 src/utils/apiConfig.js 中的 API 地址

📊 性能优化建议

智能队列管理 ✅ 已实现
- 系统自动限制最多 5 条通知
- 超出自动移除最旧的，避免内存泄漏
- 建议根据实际需求调整 maxNotifications 值
合理设置自动关闭时长
- 公告通知：10 秒
- 股票动向：10 秒
- 事件动向：12 秒（内容较多）
- 分析报告：12 秒（内容较多）
- 重要消息可设置更长时间或 autoClose: false
避免频繁推送
- 生产环境建议间隔至少 3 秒
- Mock 模式默认 15 秒推送 1 条
- 避免短时间内大量推送造成用户困扰
视觉性能优化 ✅ 已实现
- 使用 Chakra UI 的优化动画（Slide、ScaleFade）
- z-index 合理分配，避免层叠问题
- 间距适中（12px），不会过于紧密
- 统一宽度（400px），避免布局抖动
点击交互优化 ✅ 已实现
- 使用 React Router navigate 实现客户端路由
- 点击事件冒泡控制（关闭按钮 stopPropagation）
- 悬停反馈平滑过渡（transition: all 0.2s）

🔮 未来扩展

可以考虑添加的功能：

✨ 通知历史记录（带时间线展示）
✨ 通知分类过滤（按类型、优先级筛选）
✨ 通知优先级排序（紧急消息置顶）
✨ 通知持久化（存储到 localStorage）
✨ 通知点击跳转动画（页面过渡效果）
✨ 用户偏好设置（通知类型开关、免打扰模式）
✨ 通知分组（同一股票的多条通知合并显示）
✨ 桌面通知集成（Web Notifications API）
✨ 通知搜索功能（历史记录搜索）
✨ 通知统计分析（每日推送量、类型分布）

📝 更新日志

v2.2.0 (2025-01-21) - 双通知系统 🆕

新增功能：

✅ 浏览器原生通知：集成 Web Notifications API
- 系统级通知，显示在操作系统通知中心
- 即使标签页在后台也能收到通知
- 点击通知聚焦窗口并跳转详情
✅ 智能分发策略：根据优先级和页面状态自动选择通知方式
- 紧急（URGENT）：浏览器通知 + 网页通知（双重保障）
- 重要（IMPORTANT）：页面在后台=浏览器通知，在前台=网页通知
- 普通（NORMAL）：仅显示网页通知
✅ 权限管理系统：
- 自动检测浏览器通知权限状态
- 测试工具显示权限状态（已授权/未授权/已拒绝）
- 一键请求权限按钮
- 权限被拒绝时显示提示信息

技术实现：

新增 browserNotificationService.js 浏览器通知服务
NotificationContext 集成智能分发逻辑
使用 document.hidden 检测页面状态
浏览器通知点击使用 window.location.hash 跳转

文件变更：

新增：src/services/browserNotificationService.js
修改：src/contexts/NotificationContext.js
修改：src/components/NotificationTestTool/index.js

测试工具更新：

顶部 Badge 显示浏览器权限状态
新增"浏览器通知"测试区域
请求权限按钮（未授权时显示）
权限状态实时说明

v2.1.0 (2025-01-21) - 预测通知系统

新增功能：

✅ 预测通知系统：支持预测→详情两阶段推送
- 预测通知：不可跳转，显示"预测"徽章和状态提示
- 详情通知：可跳转，显示"查看详情"提示
- 典型场景：先推送预测（T+0），延迟推送详情（T+5分钟）
✅ 严格可点击性判断：
- 只有 clickable=true 且 link 存在才可点击
- 不可点击通知：cursor=default，无 hover 效果，不显示"查看详情"
✅ 新增字段：
- extra.isPrediction：是否为预测通知（显示"预测"徽章）
- extra.statusHint：状态提示文字（如"详细报告生成中..."）
- extra.relatedPredictionId：关联预测 ID（用于追溯）
✅ 测试工具增强：
- 新增"预测通知"测试按钮
- 新增"预测→详情流程"测试（5秒延迟）
- Mock 数据新增 2 条预测通知示例
✅ 视觉优化：
- 预测通知：灰色"预测"徽章
- 状态提示：灰色小字 + 时钟图标（MdSchedule）
- 不可点击通知无 hover 效果

技术细节：

新增 NOTIFICATION_STATUS 常量（PREDICTION/READY）
NotificationContainer 严格判断 isActuallyClickable = clickable && link
导入 MdSchedule 图标用于状态提示

文档更新：

新增预测通知使用场景说明
新增预测→详情流程代码示例
更新测试工具说明（9 种测试 + 3 种组合）

v2.0.0 (2025-01-21) - 金融资讯专业版

重大重构：

✅ 通知类型系统：从 4 种通用类型（成功/错误/警告/信息）重构为 4 种金融资讯类型
- 公告通知 (Announcement) - 蓝色系
- 股票动向 (Stock Alert) - 红绿系（动态）
- 事件动向 (Event Alert) - 橙色系
- 分析报告 (Analysis Report) - 紫色系
✅ 优先级系统：新增 3 级优先级
- 紧急 (Urgent) - 红色标签
- 重要 (Important) - 橙色标签
- 普通 (Normal) - 无标签
✅ 智能元数据：
- 发布时间（智能格式化：刚刚、X分钟前、今天 HH:mm、昨天 HH:mm）
- 作者信息（仅分析报告，格式：作者 - 机构）
- AI 生成标识（紫色 AI 徽章）
✅ 动态配色方案：
- 股票动向根据 priceChange 自动判断涨跌
- 涨（+）：红色系（icon、border、bg、hover）
- 跌（-）：绿色系
✅ 点击交互：
- 支持点击跳转到详情页（React Router）
- 可配置 clickable 和 link
- 悬停视觉反馈（上移 2px + 阴影增强）
- "📂 查看详情" 提示文本
✅ 统一设计：
- 所有通知宽度统一为 400px
- 内容超长自动截断（noOfLines）
- 响应式布局优化
✅ Mock 数据升级：
- 14 条金融资讯模拟数据
- 3 条公告通知 + 3 条股票动向 + 3 条事件动向 + 4 条分析报告（2 条 AI）
- 真实场景数据（贵州茅台、宁德时代、比亚迪、央行政策等）
✅ 测试工具升级：
- 8 种单独测试：公告、股票上涨/下跌、事件、分析/AI 报告
- 2 种组合测试：层叠测试（4 种类型）、优先级测试（3 个级别）
- 类型特定图标和配色
- UI 分组优化（Divider）
✅ 文件结构优化：
- 新增 src/constants/notificationTypes.js 统一管理类型定义
- NotificationContainer/index.js 完全重写
- NotificationTestTool/index.js 完全重写
- mockSocketService.js Mock 数据重构

技术细节：

使用 React Router useNavigate 实现点击跳转
动态类型配置（getIcon、getColorScheme、getBg 等函数）
条件渲染优化（优先级标签、AI 徽章、作者信息、点击提示）
时间格式化辅助函数（formatNotificationTime）

破坏性变更：

⚠️ 消息格式完全改变（从 severity 改为 type + priority）
⚠️ 移除了通用的 success/error/warning/info 类型
⚠️ 新增必填字段：type、priority、publishTime
⚠️ 分析报告必须包含 author 字段
⚠️ 股票动向需要 extra.priceChange 字段用于动态配色

迁移指南：

// 旧版本（v1.x）
addNotification({
    type: 'trade_alert',
    severity: 'success',  // ❌ 移除
    title: '买入成功',
    message: '...',       // ❌ 改为 content
})

// 新版本（v2.0）
addNotification({
    type: NOTIFICATION_TYPES.ANNOUNCEMENT,  // ✅ 新的类型系统
    priority: PRIORITY_LEVELS.IMPORTANT,    // ✅ 新增优先级
    title: '买入成功',
    content: '...',                        // ✅ message 改为 content
    publishTime: Date.now(),               // ✅ 新增发布时间
    pushTime: Date.now(),
    isAIGenerated: false,                  // ✅ 新增 AI 标识
    clickable: true,                       // ✅ 新增点击配置
    link: '/event-detail/001',             // ✅ 新增跳转链接
    extra: { ... },                        // ✅ 新增额外信息
    autoClose: 10000,
})

v1.1.1 (2025-01-21) - 动画优化版

✅ 动画方向优化：从"从右向左滑入"改为"从底部向上滑入"
- 更符合"通知浮起"的物理隐喻
- 视觉效果更自然，与"堆叠"概念一致
- 代码修改：direction="right" → direction="bottom"
✅ 文档更新：同步更新动画说明和可视化图示

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
路由: React Router v6
实时通信: Socket.IO Client 4.7.4
后端框架: Flask-SocketIO 5.3.6
状态管理: React Context API
图标库: React Icons (Material Design)

📞 支持

如有问题，请查看：

项目文档: CLAUDE.md
测试工具: 开发环境右上角"金融资讯测试工具"
控制台日志: 所有操作都有详细日志
类型定义: src/constants/notificationTypes.js

祝你使用愉快！ 🎉

54 KiB Raw Blame History Unescape Escape

实时消息推送系统使用指南

🆕 最新更新 (v2.11.0 - Socket 连接优化)

优化内容

1. 指数退避策略 🔄

2. 连接状态横幅优化 📍

3. Mock 模式测试功能 🧪

4. 环境说明 🌍

测试方法

Mock 模式下测试断线重连：

测试函数速查表

技术细节

v2.10.0 更新回顾

v2.9.0 更新回顾

v2.8.0 更新回顾

v2.7.0 更新回顾

v2.6.0 更新回顾

v2.5.0 更新回顾

v2.4.0 更新回顾

v2.3.0 更新回顾

v2.2.0 更新回顾

v2.1.0 更新回顾

v2.0.0 更新回顾

📋 系统概述

核心特性

🎯 功能特性

✅ 已实现功能

📁 文件结构

🎨 通知类型配置

类型 1: 公告通知 (Announcement)

类型 2: 股票动向 (Stock Alert)

类型 3: 事件动向 (Event Alert)

类型 4: 分析报告 (Analysis Report)

📊 优先级配置

📐 展示逻辑说明

消息排列方式

关键特性

🚀 快速开始

1. 启用 Mock 模式

2. 启动项目

3. 测试通知

通知类型测试（9 种场景）

组合测试（3 种）

功能按钮

4. 自动推送

💻 代码使用

在组件中使用通知

消息格式（v2.0.0）

🔧 配置说明

Mock 服务配置

通知类型常量配置

NotificationContext 配置

NotificationContainer 配置

🌐 后端集成（生产环境）

1. Flask 后端配置

2. 后端推送示例

🐛 故障排除

问题 1: 通知不显示

问题 2: 股票动向颜色不对

问题 3: AI 徽章不显示

问题 4: 点击跳转不工作

问题 5: 音效不播放

问题 6: Mock 推送不工作

问题 7: Socket 连接失败

📊 性能优化建议

🔮 未来扩展

📝 更新日志

v2.2.0 (2025-01-21) - 双通知系统 🆕

v2.1.0 (2025-01-21) - 预测通知系统

v2.0.0 (2025-01-21) - 金融资讯专业版

v1.1.1 (2025-01-21) - 动画优化版

v1.1.0 (2025-01-21) - 交互优化版

v1.0.0 (2025-01-20) - 初始版本

💡 技术栈

📞 支持

54 KiB

Raw Blame History