vf_react/docs/MESSAGE_PUSH_INTEGRATION_TEST.md

消息推送系统整合 - 测试指南

📋 整合完成清单

✅ 统一事件名称

• Mock 和真实 Socket.IO 都使用 new_event 事件名
• 移除了 trade_notification 事件名

✅ 数据适配器

• 创建了 adaptEventToNotification 函数
• 自动识别后端事件格式并转换为前端通知格式
• 重要性映射：S → urgent, A → important, B/C → normal

✅ NotificationContext 升级

• 监听 new_event 事件
• 自动使用适配器转换事件数据
• 支持 Mock 和 Real 模式无缝切换

✅ EventList 实时推送

• 集成 useEventNotifications Hook
• 实时更新事件列表
• Toast 通知提示
• WebSocket 连接状态指示器

---

🧪 测试步骤

1. 测试 Mock 模式（开发环境）

1.1 配置环境变量

确保 .env 文件包含以下配置：

REACT_APP_USE_MOCK_SOCKET=true
# 或者
REACT_APP_ENABLE_MOCK=true

1.2 启动应用

npm start

1.3 验证功能

a) 右下角通知卡片

• 启动后等待 3 秒，应该看到 "连接成功" 系统通知
• 每隔 60 秒会自动推送 1-2 条模拟消息
• 通知类型包括：
  • 📢 公告通知（蓝色）
  • 📈 股票动向（红/绿色，根据涨跌）
  • 📰 事件动向（橙色）
  • 📊 分析报告（紫色）

b) 事件列表页面

• 访问事件列表页面（Community/Events）
• 顶部应显示 "🟢 实时推送已开启"
• 收到新事件时：
  • 右上角显示 Toast 通知
  • 事件自动添加到列表顶部
  • 无重复添加

c) 控制台日志 打开浏览器控制台，应该看到：

[Socket Service] Using MOCK Socket Service
NotificationContext: Socket connected
EventList: 收到新事件推送

---

2. 测试 Real 模式（生产环境）

2.1 配置环境变量

修改 .env 文件：

REACT_APP_USE_MOCK_SOCKET=false
# 或删除该配置项

2.2 启动后端 Flask 服务

python app_2.py

确保后端已启动 Socket.IO 服务并监听事件推送。

2.3 启动前端应用

npm start

2.4 创建测试事件（后端）

使用后端提供的测试脚本：

python test_create_event.py

2.5 验证功能

a) WebSocket 连接

• 检查控制台：[Socket Service] Using REAL Socket Service
• 事件列表顶部显示 "🟢 实时推送已开启"

b) 事件推送流程

1. 运行 test_create_event.py 创建新事件
2. 后端轮询检测到新事件（最多等待 30 秒）
3. 后端通过 Socket.IO 推送 new_event
4. 前端接收事件并转换格式
5. 同时显示：
   • 右下角通知卡片
   • 事件列表 Toast 提示
   • 事件添加到列表顶部

c) 数据格式验证 在控制台查看事件对象，应包含：

{
  id: 123,
  type: "event_alert",           // 适配器转换后
  priority: "urgent",            // importance: S → urgent
  title: "事件标题",
  content: "事件描述",
  clickable: true,
  link: "/event-detail/123",
  extra: {
    eventType: "tech",
    importance: "S",
    // ... 更多后端字段
  }
}

---

🔍 验证清单

功能验证

• Mock 模式下收到模拟通知
• Real 模式下收到真实后端推送
• 通知卡片正确显示（类型、颜色、内容）
• 事件列表实时更新
• Toast 通知正常弹出
• 连接状态指示器正确显示
• 点击通知可跳转到详情页
• 无重复事件添加

数据验证

• 后端事件格式正确转换
• 重要性映射正确（S/A/B/C → urgent/important/normal）
• 时间戳正确显示
• 链接路径正确生成
• 所有字段完整保留在 extra 中

性能验证

• 事件列表最多保留 100 条
• 通知自动关闭（紧急=不关闭，重要=30s，普通=15s）
• WebSocket 自动重连
• 无内存泄漏

---

🐛 常见问题排查

Q1: Mock 模式下没有收到通知？

A: 检查：

1. 环境变量 REACT_APP_USE_MOCK_SOCKET=true 是否设置
2. 控制台是否显示 "Using MOCK Socket Service"
3. 是否等待了 3 秒（首次通知延迟）

Q2: Real 模式下无法连接？

A: 检查：

1. Flask 后端是否启动：python app_2.py
2. API_BASE_URL 是否正确配置
3. CORS 设置是否包含前端域名
4. 控制台是否有连接错误

Q3: 收到重复通知？

A: 检查：

1. 是否多次渲染了 EventList 组件
2. 是否在多个地方调用了 useEventNotifications
3. 控制台日志中是否有 "事件已存在，跳过添加"

Q4: 通知卡片样式异常？

A: 检查：

1. 事件的 type 字段是否正确
2. 是否缺少必要的字段（title, content）
3. NOTIFICATION_TYPE_CONFIGS 是否定义了该类型

Q5: 事件列表不更新？

A: 检查：

1. WebSocket 连接状态（顶部 Badge）
2. onNewEvent 回调是否触发（控制台日志）
3. setLocalEvents 是否正确执行

---

📊 测试数据示例

Mock 模拟数据类型

公告通知

{
  type: "announcement",
  priority: "urgent",
  title: "贵州茅台发布2024年度财报公告",
  content: "2024年度营收同比增长15.2%..."
}

股票动向

{
  type: "stock_alert",
  priority: "urgent",
  title: "您关注的股票触发预警",
  extra: {
    stockCode: "300750",
    priceChange: "+5.2%"
  }
}

事件动向

{
  type: "event_alert",
  priority: "important",
  title: "央行宣布降准0.5个百分点",
  extra: {
    eventId: "evt001",
    sectors: ["银行", "地产", "基建"]
  }
}

分析报告

{
  type: "analysis_report",
  priority: "important",
  title: "医药行业深度报告：创新药迎来政策拐点",
  author: {
    name: "李明",
    organization: "中信证券"
  }
}

真实后端事件格式

{
  id: 123,
  title: "新能源汽车补贴政策延期",
  description: "财政部宣布新能源汽车购置补贴政策延长至2024年底",
  event_type: "policy",
  importance: "S",
  status: "active",
  created_at: "2025-01-21T14:30:00",
  hot_score: 95.5,
  view_count: 1234,
  related_avg_chg: 5.2,
  related_max_chg: 15.8,
  keywords: ["新能源", "补贴", "政策"]
}

---

🎯 下一步建议

1. 用户设置

允许用户控制通知偏好：

<Switch
  isChecked={enableNotifications}
  onChange={handleToggle}
>
  启用实时通知
</Switch>

2. 通知过滤

按重要性、类型过滤通知：

useEventNotifications({
  eventType: 'tech',      // 只订阅科技类
  importance: 'S',        // 只订阅 S 级
  enabled: true
})

3. 声音提示

添加音效提醒：

onNewEvent: (event) => {
  if (event.priority === 'urgent') {
    new Audio('/alert.mp3').play();
  }
}

4. 桌面通知

利用浏览器通知 API：

if (Notification.permission === 'granted') {
  new Notification(event.title, {
    body: event.content,
    icon: '/logo.png'
  });
}

---

📝 技术说明

架构优势

1. 统一接口：Mock 和 Real 完全相同的 API
2. 自动适配：智能识别数据格式并转换
3. 解耦设计：通知系统和事件列表独立工作
4. 向后兼容：不影响现有功能

关键文件

• src/services/mockSocketService.js - Mock Socket 服务
• src/services/socketService.js - 真实 Socket.IO 服务
• src/services/socket/index.js - 统一导出
• src/contexts/NotificationContext.js - 通知上下文（含适配器）
• src/hooks/useEventNotifications.js - React Hook
• src/views/Community/components/EventList.js - 事件列表集成

数据流

后端创建事件
    ↓
后端轮询检测（30秒）
    ↓
Socket.IO 推送 new_event
    ↓
前端 socketService 接收
    ↓
NotificationContext 监听并适配
    ↓
同时触发：
    ├─ NotificationContainer（右下角卡片）
    └─ EventList onNewEvent（Toast + 列表更新）

---

✅ 整合完成

所有代码和功能已经就绪！你现在可以：

1. ✅ 在 Mock 模式下测试实时推送
2. ✅ 在 Real 模式下连接后端
3. ✅ 查看右下角通知卡片
4. ✅ 体验事件列表实时更新
5. ✅ 随时切换 Mock/Real 模式

祝测试顺利！🎉