vf_react/NOTIFICATION_SYSTEM.md

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

## 🆕 最新更新 (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 模式下测试断线重连：

1. **启用 Mock 模式**：
   ```bash
   # .env 文件
   REACT_APP_ENABLE_MOCK=true
   ```

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

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

   ```javascript
   // 查看可用测试函数
   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();
   ```

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

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

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

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

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

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

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

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

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

4. **测试手动关闭**：
   - 模拟断线后，点击状态横幅右侧的 ✕ 按钮
   - 横幅消失，保存到 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 条历史，可展开查看 🆕

---

## 🎯 功能特性

### ✅ 已实现功能

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 (
        <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）

```javascript
{
    // 必填字段
    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` 中可以配置：

```javascript
// 修改模拟数据（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` 中可以修改：

```javascript
// 修改类型配色
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` 中：

```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
// 调整通知宽度（默认 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：

```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_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. 后端推送示例

```python
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: 通知不显示

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

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

**解决方案：**
1. 检查 `extra.priceChange` 字段是否存在
2. 确认 `priceChange` 格式为 "+5.2%" 或 "-3.8%"（包含符号）
3. 确认使用了 `NOTIFICATION_TYPES.STOCK_ALERT` 类型

### 问题 3: AI 徽章不显示

**解决方案：**
1. 检查 `isAIGenerated` 字段是否为 `true`
2. 确认字段名拼写正确（驼峰命名）

### 问题 4: 点击跳转不工作

**解决方案：**
1. 检查 `clickable` 字段是否为 `true`
2. 确认 `link` 字段存在且格式正确
3. 检查路由配置是否正确

### 问题 5: 音效不播放

**解决方案：**
1. 检查浏览器是否允许自动播放音频
2. 确认音效开关已打开
3. 检查音频文件路径是否正确

### 问题 6: Mock 推送不工作

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

### 问题 7: Socket 连接失败

**解决方案：**
1. 检查后端 Flask-SocketIO 是否正确运行
2. 确认 CORS 配置正确
3. 检查 `src/utils/apiConfig.js` 中的 API 地址

---

## 📊 性能优化建议

1. **智能队列管理** ✅ 已实现
   - 系统自动限制最多 5 条通知
   - 超出自动移除最旧的，避免内存泄漏
   - 建议根据实际需求调整 `maxNotifications` 值

2. **合理设置自动关闭时长**
   - 公告通知：10 秒
   - 股票动向：10 秒
   - 事件动向：12 秒（内容较多）
   - 分析报告：12 秒（内容较多）
   - 重要消息可设置更长时间或 `autoClose: false`

3. **避免频繁推送**
   - 生产环境建议间隔至少 3 秒
   - Mock 模式默认 15 秒推送 1 条
   - 避免短时间内大量推送造成用户困扰

4. **视觉性能优化** ✅ 已实现
   - 使用 Chakra UI 的优化动画（Slide、ScaleFade）
   - z-index 合理分配，避免层叠问题
   - 间距适中（12px），不会过于紧密
   - 统一宽度（400px），避免布局抖动

5. **点击交互优化** ✅ 已实现
   - 使用 React Router `navigate` 实现客户端路由
   - 点击事件冒泡控制（关闭按钮 `stopPropagation`）
   - 悬停反馈平滑过渡（`transition: all 0.2s`）

---

## 🔮 未来扩展

可以考虑添加的功能：

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

---

## 📝 更新日志

### 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` 字段用于动态配色

**迁移指南：**
```javascript
// 旧版本（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`

---

**祝你使用愉快！** 🎉