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` 文件包含以下配置：
```bash
REACT_APP_USE_MOCK_SOCKET=true
# 或者
REACT_APP_ENABLE_MOCK=true
```

#### 1.2 启动应用
```bash
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` 文件：
```bash
REACT_APP_USE_MOCK_SOCKET=false
# 或删除该配置项
```

#### 2.2 启动后端 Flask 服务
```bash
python app_2.py
```

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

#### 2.3 启动前端应用
```bash
npm start
```

#### 2.4 创建测试事件（后端）
使用后端提供的测试脚本：
```bash
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) 数据格式验证**
在控制台查看事件对象，应包含：
```javascript
{
  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 模拟数据类型

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

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

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

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

### 真实后端事件格式

```javascript
{
  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. 用户设置
允许用户控制通知偏好：
```jsx
<Switch
  isChecked={enableNotifications}
  onChange={handleToggle}
>
  启用实时通知
</Switch>
```

### 2. 通知过滤
按重要性、类型过滤通知：
```javascript
useEventNotifications({
  eventType: 'tech',      // 只订阅科技类
  importance: 'S',        // 只订阅 S 级
  enabled: true
})
```

### 3. 声音提示
添加音效提醒：
```javascript
onNewEvent: (event) => {
  if (event.priority === 'urgent') {
    new Audio('/alert.mp3').play();
  }
}
```

### 4. 桌面通知
利用浏览器通知 API：
```javascript
if (Notification.permission === 'granted') {
  new Notification(event.title, {
    body: event.content,
    icon: '/logo.png'
  });
}
```

---

## 📝 技术说明

### 架构优势

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

### 关键文件

- `src/services/socketService.js` - Socket.IO 服务
- `src/services/socket/index.js` - Socket 服务导出
- `src/contexts/NotificationContext.js` - 通知上下文
- `src/hooks/useEventNotifications.js` - React Hook
- `src/views/Community/components/EventList.js` - 事件列表集成

> **注意**: `mockSocketService.js` 已移除（2025-01-10），现仅使用真实 Socket 连接。

### 数据流

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

---

## ✅ 整合完成

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

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

**祝测试顺利！🎉**