vf/vf_react

Fork 0

Files

zdl 5a3a3ad42b feat: 添加消息推送能力，添加新闻催化分析页的合规提示

2025-10-21 10:59:52 +08:00

12 KiB

Raw Blame History

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

🆕 最新更新 (v1.1.0)

✅ 新消息置顶展示：采用行业标准，新消息显示在最上方
✅ 智能队列管理：最多同时显示 5 条消息，超出自动移除最旧的
✅ 视觉层次优化：最新消息更强的阴影和边框高亮效果
✅ 测试工具增强：实时显示队列状态，新增"测试最大限制"功能

📋 系统概述

本系统实现了完整的实时消息推送功能，支持 Mock 模式（开发）和真实 Socket.IO 模式（生产）。消息以右下角层叠弹窗的形式显示，新消息在最上方，符合主流桌面应用的交互习惯。

🎯 功能特性

✅ 已实现功能

实时推送
- WebSocket (Socket.IO) 连接
- Mock 模式自动定期推送（开发环境）
- 支持多种消息类型（成功、错误、警告、信息）
UI 展示
- 右下角固定定位
- 新消息在最上方（符合行业标准）
- 层叠显示最多 5 条消息
- 智能队列管理：超出自动移除最旧消息
- 视觉层次：最新消息更突出（更强阴影、边框高亮）
- 自动关闭（可配置时长）
- 手动关闭按钮
- 流畅的进入/退出动画（从右侧滑入）
音效提示
- 新消息音效播放
- 可开关音效
开发工具
- 右上角测试工具面板（仅开发环境）
- 手动触发测试通知（4种类型）
- 层叠效果测试（4条消息）
- 最大限制测试（6条→5条）
- 实时队列状态显示（当前消息数 / 5）
- 连接状态显示
- 音效开关
- 测试计数统计

📁 文件结构

src/
├── services/
│   ├── socket/
│   │   └── index.js                    # Socket 服务统一导出
│   ├── socketService.js                # 真实 Socket.IO 服务
│   └── mockSocketService.js            # Mock Socket 服务
├── contexts/
│   └── NotificationContext.js          # 通知上下文管理
├── components/
│   ├── NotificationContainer/
│   │   └── index.js                    # 通知容器组件
│   └── NotificationTestTool/
│       └── index.js                    # 测试工具组件
└── assets/
    └── sounds/
        └── notification.wav            # 通知音效

📐 展示逻辑说明

消息排列方式

本系统采用新消息在最上方的展示模式，这是桌面应用的行业标准（Windows、macOS、Slack、Discord等）。

用户视角（右下角）：

第1条消息到达：
┌────────────────────┐
│ 🔔 买入成功 🆕     │ ← 从右侧滑入
└────────────────────┘

第2条消息到达：
┌────────────────────┐
│ 🔔 价格预警 🆕     │ ← 新消息（最上方）
├────────────────────┤
│ 🔔 买入成功        │ ← 旧消息向下平移
└────────────────────┘

第6条消息到达（超过5条限制）：
┌────────────────────┐
│ 🔔 第6条 🆕        │ ← 最新
├────────────────────┤
│ 🔔 第5条           │
├────────────────────┤
│ 🔔 第4条           │
├────────────────────┤
│ 🔔 第3条           │
├────────────────────┤
│ 🔔 第2条           │ ← 最旧（仍显示）
└────────────────────┘
     ↓ 自动移除
│ 第1条（已移除）     │

关键特性

最新消息固定位置：始终在右下角的顶部，便于快速注意
自动队列管理：最多保留 5 条，超出自动移除最旧的
视觉区分：最新消息有更强的阴影（2xl vs lg）和边框高亮
z-index 层级：最新消息层级最高（9999），依次递减
间距优化：消息之间 12px 间距（spacing={3}）

🚀 快速开始

1. 启用 Mock 模式

在 .env 文件中添加：

REACT_APP_ENABLE_MOCK=true
# 或
REACT_APP_USE_MOCK_SOCKET=true

2. 启动项目

npm start

3. 测试通知

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

单条测试：测试不同类型的通知（成功、错误、警告、信息）
层叠测试：一次发送 4 条消息，测试层叠效果
最大限制测试：发送 6 条消息，验证只保留最新 5 条
队列状态：实时显示当前队列中的消息数量（X / 5）
音效控制：切换音效开关
清空功能：一键清空所有通知
连接状态：查看 Socket 连接状态和服务类型（MOCK/REAL）

4. 自动推送

在 Mock 模式下，系统会自动每 20 秒推送 1-2 条随机消息，用于测试层叠效果。

💻 代码使用

在组件中使用通知

import { useNotification } from 'contexts/NotificationContext';

function MyComponent() {
    const { addNotification, isConnected } = useNotification();

    const handleTradeSuccess = () => {
        addNotification({
            type: 'trade_alert',
            severity: 'success',
            title: '买入成功',
            message: '您的订单已成功执行：买入 贵州茅台(600519) 100股',
            autoClose: 8000, // 8秒后自动关闭
        });
    };

    return (
        <div>
            <p>连接状态: {isConnected ? '已连接' : '未连接'}</p>
            <button onClick={handleTradeSuccess}>模拟交易成功</button>
        </div>
    );
}

消息格式

{
    type: 'trade_alert',           // 消息类型
    severity: 'info',              // 'success' | 'error' | 'warning' | 'info'
    title: '通知标题',             // 主标题
    message: '详细消息内容',        // 详细内容
    timestamp: Date.now(),         // 时间戳（自动生成）
    autoClose: 8000,               // 自动关闭时长（毫秒），0 或 false 表示不自动关闭
    id: 'unique_id'                // 唯一ID（自动生成）
}

🔧 配置说明

Mock 服务配置

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

// 修改模拟数据
const mockTradeAlerts = [
    {
        severity: 'success',
        title: '自定义标题',
        message: '自定义消息',
        autoClose: 8000,
    },
    // 添加更多...
];

// 调整推送频率
socket.startMockPush(20000, 2); // 每20秒推送1-2条

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 中：

// 调整消息间距
<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_trade_notification(user_id, data):
    """
    推送交易通知到指定用户
    """
    emit('trade_notification', data, room=user_id)

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

2. 后端推送示例

# 交易成功后推送通知
socketio.emit('trade_notification', {
    'type': 'trade_alert',
    'severity': 'success',
    'title': '买入成功',
    'message': f'买入 {stock_name}({stock_code}) {quantity}股',
    'timestamp': int(time.time() * 1000),
    'autoClose': 8000
}, room=user_id)

🎨 自定义样式

修改通知位置

在 src/components/NotificationContainer/index.js：

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

修改通知颜色

在 src/components/NotificationContainer/index.js 中的 NOTIFICATION_STYLES：

const NOTIFICATION_STYLES = {
    success: {
        icon: MdCheckCircle,
        colorScheme: 'green',  // 修改颜色主题
        bg: 'green.50',
        borderColor: 'green.400',
        iconColor: 'green.500',
    },
    // ...
};

🐛 故障排除

问题 1: 通知不显示

检查项：

确认 NotificationProvider 已包裹应用
检查浏览器控制台是否有错误
确认 socket 连接状态（查看测试工具）

问题 2: 音效不播放

解决方案：

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

问题 3: Mock 推送不工作