diff --git a/docs/ENHANCED_FEATURES_GUIDE.md b/docs/ENHANCED_FEATURES_GUIDE.md
deleted file mode 100644
index 9fc726a5..00000000
--- a/docs/ENHANCED_FEATURES_GUIDE.md
+++ /dev/null
@@ -1,626 +0,0 @@
-# 通知系统增强功能 - 使用指南
-
-## 📋 概述
-
-本指南介绍通知系统的三大增强功能：
-1. **智能桌面通知** - 自动请求权限，系统级通知
-2. **性能监控** - 追踪推送效果，数据驱动优化
-3. **历史记录** - 持久化存储，随时查询
-
----
-
-## 🎯 功能 1：智能桌面通知
-
-### 功能说明
-
-首次收到重要/紧急通知时，自动请求浏览器通知权限，确保用户不错过关键信息。
-
-### 工作原理
-
-```javascript
-// 在 NotificationContext 中的逻辑
-if (priority === URGENT || priority === IMPORTANT) {
- if (browserPermission === 'default' && !hasRequestedPermission) {
- // 首次遇到重要通知，自动请求权限
- await requestBrowserPermission();
- setHasRequestedPermission(true); // 避免重复请求
- }
-}
-```
-
-### 权限状态
-
-- **granted**: 已授权，可以发送桌面通知
-- **denied**: 已拒绝，无法发送桌面通知
-- **default**: 未请求，首次重要通知时会自动请求
-
-### 使用示例
-
-**自动触发**（推荐）
-```javascript
-// 无需任何代码，系统自动处理
-// 首次收到重要/紧急通知时会自动弹出权限请求
-```
-
-**手动请求**
-```javascript
-import { useNotification } from 'contexts/NotificationContext';
-
-function SettingsPage() {
- const { requestBrowserPermission, browserPermission } = useNotification();
-
- return (
-
-
当前状态: {browserPermission}
-
-
- {/* 汇总卡片 */}
-
-
-
-
- {/* 类型分布饼图 */}
-
({
- name: type,
- value: data.received
- }))} />
-
- {/* 每日趋势折线图 */}
-
-
+
连接状态: {isConnected ? '已连接' : '未连接'}
+
+
WebSocket连接]
- F --> G{环境判断}
- G -->|Mock| H[mockSocketService
模拟服务]
- G -->|Real| I[socketService
生产服务]
-
+ C --> F[socketService
Socket.IO连接]
C --> J[browserNotificationService
浏览器通知]
C --> K[notificationHistoryService
历史记录]
C --> L[notificationMetricsService
性能监控]
end
subgraph "后端服务"
- I --> M[Flask Backend
Socket.IO Server]
+ F --> M[Flask Backend
Socket.IO Server]
M --> N[(ClickHouse
事件数据)]
M --> O[(MySQL
用户数据)]
end
@@ -379,7 +406,7 @@ graph TB
style F fill:#bfb,stroke:#333,stroke-width:2px
```
-### 技术栈选型
+### 📚 技术栈
#### 前端技术栈
- **React 18.3.1**: 并发渲染、Suspense、自动批处理
@@ -448,14 +475,15 @@ sequenceDiagram
---
-## 🧩 核心组件清单
+## 🧩 第四部分：核心组件详解
+
+### 📦 核心组件清单
| 组件名 | 类型 | 职责 | 文件路径 |
|-------|------|------|---------|
| **NotificationContext** | React Context | 通知系统核心逻辑、状态管理 | `src/contexts/NotificationContext.js` |
| **NotificationContainer** | React Component | 通知UI容器、动画、交互 | `src/components/NotificationContainer/index.js` |
-| **socketService** | Service Class | 真实WebSocket连接管理 | `src/services/socketService.js` |
-| **mockSocketService** | Service Class | Mock WebSocket模拟 | `src/services/mockSocketService.js` |
+| **socketService** | Service Class | WebSocket连接管理 | `src/services/socketService.js` |
| **browserNotificationService** | Service Class | 浏览器通知API封装 | `src/services/browserNotificationService.js` |
| **notificationHistoryService** | Service Class | 历史记录持久化 | `src/services/notificationHistoryService.js` |
| **notificationMetricsService** | Service Class | 性能监控埋点 | `src/services/notificationMetricsService.js` |
@@ -528,7 +556,7 @@ const {
showFirstFollowGuide();
```
-**源码位置**: `src/contexts/NotificationContext.js:1-829`
+**源码位置**: `src/contexts/NotificationContext.js`
---
@@ -590,7 +618,7 @@ const {
});
```
-**源码位置**: `src/components/NotificationContainer/index.js:1-757`
+**源码位置**: `src/components/NotificationContainer/index.js`
---
@@ -634,7 +662,7 @@ socket.subscribeToEvents({ eventType, importance, onNewEvent });
socket.unsubscribeFromEvents({ eventType });
```
-**源码位置**: `src/services/socketService.js:1-465`
+**源码位置**: `src/services/socketService.js`
---
@@ -671,7 +699,7 @@ notification.onclick = () => {
};
```
-**源码位置**: `src/services/browserNotificationService.js:1-209`
+**源码位置**: `src/services/browserNotificationService.js`
---
@@ -711,7 +739,7 @@ const stats = notificationHistoryService.getStats();
// { total, read, unread, clicked, clickRate, byType, byPriority }
```
-**源码位置**: `src/services/notificationHistoryService.js:1-403`
+**源码位置**: `src/services/notificationHistoryService.js`
---
@@ -749,11 +777,13 @@ const json = notificationMetricsService.exportToJSON();
const csv = notificationMetricsService.exportToCSV();
```
-**源码位置**: `src/services/notificationMetricsService.js:1-451`
+**源码位置**: `src/services/notificationMetricsService.js`
---
-## 🔄 消息推送完整流程
+## 🔄 第五部分：设计流程
+
+### 📡 消息推送完整流程
### 1. 初始化流程
@@ -761,19 +791,16 @@ const csv = notificationMetricsService.exportToCSV();
graph LR
A[App启动] --> B[AppProviders挂载]
B --> C[NotificationProvider初始化]
- C --> D{环境检测}
- D -->|Mock| E[连接mockSocketService]
- D -->|Real| F[连接socketService]
- E --> G[注册事件监听器]
- F --> G
- G --> H[触发connect事件]
- H --> I[更新连接状态]
- I --> J[检查浏览器通知权限]
- J --> K[加载历史记录]
- K --> L[初始化完成]
+ C --> D[连接socketService]
+ D --> E[注册事件监听器]
+ E --> F[触发connect事件]
+ F --> G[更新连接状态]
+ G --> H[检查浏览器通知权限]
+ H --> I[加载历史记录]
+ I --> J[初始化完成]
```
-**代码实现** (src/contexts/NotificationContext.js:573-712):
+**代码实现** (src/contexts/NotificationContext.js):
```javascript
useEffect(() => {
// 1. 注册事件监听器
@@ -785,12 +812,7 @@ useEffect(() => {
// 2. 连接Socket
socket.connect();
- // 3. Mock模式启动自动推送
- if (SOCKET_TYPE === 'MOCK') {
- socket.startMockPush(60000, 2); // 60秒推送1-2条
- }
-
- // 4. 清理函数
+ // 3. 清理函数
return () => {
socket.off('connect');
socket.off('disconnect');
@@ -859,7 +881,7 @@ const adaptEventToNotification = (event) => {
};
```
-**源码位置**: `src/contexts/NotificationContext.js:336-395`
+**源码位置**: `src/contexts/NotificationContext.js`
---
@@ -890,7 +912,7 @@ graph TB
R --> K
```
-**代码实现** (src/contexts/NotificationContext.js:558-570):
+**代码实现** (src/contexts/NotificationContext.js):
```javascript
const isPageHidden = document.hidden;
@@ -942,363 +964,9 @@ deliveryRate = (totalReceived / totalSent) * 100
---
-## 🧪 测试快速指南
+## 🎨 第六部分：通知类型与配置
-> 📖 **完整测试手册**: [notification-manual-testing-guide.md](./test-cases/notification-manual-testing-guide.md)
-
-### 本地测试
-
-#### Mock 模式（快速开发测试）
-
-```bash
-npm start
-```
-
-**关键检查**:
-```javascript
-// 1. 验证连接
-__SOCKET_DEBUG__.getStatus()
-// 预期: { type: "MOCK", connected: true }
-
-// 2. 查看可用工具
-__mockSocket
-// 包含: simulateDisconnection, pausePush, resumePush, sendTestNotification 等
-
-// 3. 快速触发测试通知（三种方式）
-__mockSocket.sendTestNotification() // 方式1: 快速触发1条公告通知
-__NOTIFY_DEBUG__.testNotify('announcement') // 方式2: 指定类型的测试通知
-__NOTIFY_DEBUG__.testNotify('stock_alert') // 方式3: 其他类型（股票/事件/报告）
-```
-
-#### Real 模式（后端联调）
-
-```bash
-npm run start:real
-```
-
-**关键检查**:
-```javascript
-// 1. 验证连接
-__SOCKET_DEBUG__.getStatus()
-// 预期: { type: "REAL", connected: true }
-
-// 2. 手动订阅
-__NOTIFY_DEBUG__.subscribe()
-
-// 3. 等待后端推送
-// 观察控制台: "✅ New event received"
-```
-
-### 线上测试
-
-**访问**: https://valuefrontier.cn
-
-```javascript
-// 一键诊断
-__NOTIFY_DEBUG__.checkAll()
-
-// 手动订阅
-__NOTIFY_DEBUG__.subscribe()
-
-// 导出报告
-__NOTIFY_DEBUG__.exportReport()
-```
-
-### 调试工具速查
-
-| 工具 | 适用环境 | 主要功能 |
-|------|---------|---------|
-| `__mockSocket` | Mock模式 | 模拟断线、暂停推送、测试重连 |
-| `__SOCKET_DEBUG__` | 所有环境 | 连接状态、配置检查、手动订阅 |
-| `__NOTIFY_DEBUG__` | 所有环境 | 完整诊断、模拟通知、导出报告 |
-
-**常用命令**:
-```javascript
-// 完整诊断
-__NOTIFY_DEBUG__.checkAll()
-
-// 查看帮助
-__NOTIFY_DEBUG__.help()
-
-// Mock模式：暂停自动推送
-__mockSocket.pausePush()
-
-// Mock模式：模拟断线
-__mockSocket.simulateDisconnection()
-```
-
-### 测试通知方法对比
-
-| 方法 | 环境 | 触发速度 | 通知类型 | 使用场景 |
-|------|------|---------|---------|---------|
-| `__mockSocket.sendTestNotification()` | Mock模式 | ⚡ 即时 | 固定：公告通知 | 快速验证通知UI是否正常显示 |
-| `__NOTIFY_DEBUG__.testNotify(type)` | Mock模式 | ⚡ 即时 | 可选：4种类型 | 测试不同类型通知的显示效果 |
-| 等待自动推送 | Mock模式 | 🐢 60秒/次 | 随机：所有类型 | 测试自动推送机制和真实场景 |
-| `__NOTIFY_DEBUG__.subscribe()` | Real模式 | ⏳ 等待后端 | 取决于后端 | 测试后端集成和真实数据 |
-
-**推荐用法**：
-```javascript
-// 场景1: 快速验证UI（最快）
-__mockSocket.sendTestNotification()
-
-// 场景2: 测试特定类型
-__NOTIFY_DEBUG__.testNotify('stock_alert') // 股票动向
-__NOTIFY_DEBUG__.testNotify('event_alert') // 事件动向
-__NOTIFY_DEBUG__.testNotify('analysis_report') // 分析报告
-
-// 场景3: 测试自动推送
-__mockSocket.resumePush() // 确保推送开启
-// 等待60秒...
-
-// 场景4: 暂停干扰
-__mockSocket.pausePush() // 暂停自动推送，专注测试单条
-```
-
----
-
-## ✅ 手动测试清单
-
-### 功能测试
-
-#### 1. 通知显示测试
-- [ ] 公告通知显示正确（蓝色系、图标、内容）
-- [ ] 股票上涨通知显示为红色系（+图标、红边框）
-- [ ] 股票下跌通知显示为绿色系（-图标、绿边框）
-- [ ] 事件动向通知显示正确（橙色系）
-- [ ] 分析报告（人工）显示正确（紫色系、作者信息）
-- [ ] 分析报告（AI）显示AI徽章
-- [ ] 预测通知显示"预测"徽章和状态提示
-
-#### 2. 优先级测试
-- [ ] 紧急通知：红色标签、粗边框、脉冲动画、不自动关闭
-- [ ] 重要通知：橙色标签、中等边框、30秒自动关闭
-- [ ] 普通通知：无标签、细边框、15秒自动关闭
-
-#### 3. 交互测试
-- [ ] 点击可点击通知跳转到正确页面
-- [ ] 点击不可点击通知无反应
-- [ ] 点击关闭按钮关闭通知
-- [ ] 音效开关正常工作
-- [ ] 清空全部按钮清空所有通知
-
-#### 4. 折叠展开测试
-- [ ] 通知数 ≤ 3 时不显示展开按钮
-- [ ] 通知数 > 3 时显示"还有X条通知"按钮
-- [ ] 点击展开显示所有通知
-- [ ] 点击收起恢复显示前3条
-- [ ] 展开状态保存到localStorage（刷新页面保持）
-- [ ] 展开状态2分钟后自动过期
-
-#### 5. 队列管理测试
-- [ ] 最多显示15条历史通知
-- [ ] 超过15条自动移除最旧的
-- [ ] 新通知在最上方
-- [ ] z-index层级正确（最新最高）
-
-### 浏览器通知测试
-
-#### 6. 权限管理测试
-- [ ] 首次访问显示权限状态为"default"
-- [ ] 点击请求权限按钮弹出浏览器授权对话框
-- [ ] 授权后状态变为"granted"
-- [ ] 拒绝后状态变为"denied"，显示设置指引
-- [ ] 权限状态正确显示
-
-#### 7. 浏览器通知显示测试
-- [ ] 权限授予后，切换到其他标签页，收到通知时显示系统通知
-- [ ] 点击浏览器通知聚焦窗口并跳转到详情页
-- [ ] 普通通知8秒后自动关闭
-- [ ] 紧急通知需手动关闭
-
-### Socket连接测试
-
-#### 8. Mock模式测试
-- [ ] 启动后显示"Connected" + "MOCK"状态
-- [ ] 控制台显示可用测试函数
-- [ ] `__mockSocket.simulateDisconnection()` 模拟断线成功
-- [ ] 断线后自动重连（10秒→20秒→40秒）
-- [ ] 重连成功后显示"✓ 已重新连接" 2秒后消失
-- [ ] `__mockSocket.simulateConnectionFailure()` 模拟持续失败
-- [ ] 手动关闭连接状态横幅后保存到localStorage
-- [ ] `__mockSocket.reconnect()` 立即重连成功
-
-#### 9. Real模式测试
-- [ ] 启动后显示"Connected" + "REAL"状态
-- [ ] 后端推送消息能正确接收
-- [ ] 断线后自动重连（1分钟→2分钟→4分钟）
-- [ ] 网络恢复时自动重连
-- [ ] 标签页重新聚焦时自动重连
-
-### UI测试
-
-#### 10. 响应式测试
-- [ ] 移动端（< 480px）：宽度 = 屏宽-32px，精简显示
-- [ ] 小屏（480-768px）：宽度 = 360px
-- [ ] 平板（768-992px）：宽度 = 380px
-- [ ] 桌面（> 992px）：宽度 = 400px
-- [ ] 底部偏移：移动端12px，桌面端112px（避开设置按钮）
-
-#### 11. 动画测试
-- [ ] 新通知从底部向上滑入（浮起效果）
-- [ ] 关闭通知向右滑出消失
-- [ ] 紧急通知边框脉冲动画流畅
-- [ ] 折叠/展开动画流畅无卡顿
-- [ ] 展开15条通知无明显性能问题
-
-#### 12. 无障碍测试
-- [ ] Tab键可以聚焦到可点击通知
-- [ ] 聚焦时显示蓝色轮廓线
-- [ ] Enter/Space键可以打开详情
-- [ ] 关闭按钮可键盘操作（Tab + Enter）
-- [ ] 屏幕阅读器朗读完整通知信息
-
-### 性能测试
-
-#### 13. 性能指标测试
-- [ ] 发送10条通知，打开控制台查看性能指标
-- [ ] 点击5条通知，检查点击率计算正确
-- [ ] 检查平均响应时间计算正确
-- [ ] 导出JSON/CSV文件正常
-- [ ] 查看每小时分布图表数据准确
-
-#### 14. 历史记录测试
-- [ ] 收到通知后自动保存到历史记录
-- [ ] 筛选功能正常（类型、优先级、日期范围、阅读状态）
-- [ ] 搜索功能返回正确结果
-- [ ] 分页功能正常
-- [ ] 统计数据准确
-- [ ] 导出JSON/CSV正常
-
-### 跨浏览器测试
-
-#### 15. 兼容性测试
-- [ ] Chrome: 所有功能正常
-- [ ] Edge: 所有功能正常
-- [ ] Firefox: 所有功能正常
-- [ ] Safari: 所有功能正常（注意浏览器通知权限）
-- [ ] 移动端Chrome: 响应式布局正确
-- [ ] 移动端Safari: 响应式布局正确
-
----
-
-## 🧪 自动化测试用例
-
-完整的自动化测试代码请参考: **[notification-tests.md](./test-cases/notification-tests.md)**
-
-以下是核心测试用例概览：
-
-### 单元测试
-
-#### NotificationContext 测试
-```javascript
-describe('NotificationContext', () => {
- test('应该正确初始化默认状态', () => {
- const { result } = renderHook(() => useNotification(), {
- wrapper: NotificationProvider,
- });
-
- expect(result.current.notifications).toEqual([]);
- expect(result.current.soundEnabled).toBe(true);
- });
-
- test('应该正确添加通知', () => {
- const { result } = renderHook(() => useNotification(), {
- wrapper: NotificationProvider,
- });
-
- act(() => {
- result.current.addNotification({
- type: 'announcement',
- priority: 'important',
- title: '测试通知',
- content: '内容',
- });
- });
-
- expect(result.current.notifications).toHaveLength(1);
- expect(result.current.notifications[0].title).toBe('测试通知');
- });
-
- // 更多测试用例...
-});
-```
-
-#### notificationHistoryService 测试
-```javascript
-describe('notificationHistoryService', () => {
- beforeEach(() => {
- localStorage.clear();
- });
-
- test('应该保存通知到历史记录', () => {
- const notification = {
- id: 'test001',
- type: 'announcement',
- title: '测试',
- content: '内容',
- };
-
- notificationHistoryService.saveNotification(notification);
- const { records } = notificationHistoryService.getHistory();
-
- expect(records).toHaveLength(1);
- expect(records[0].notification.id).toBe('test001');
- });
-
- // 更多测试用例...
-});
-```
-
-### 集成测试
-
-```javascript
-describe('通知系统集成测试', () => {
- test('完整流程：从接收到显示到点击', async () => {
- render(
-
-
-
- );
-
- // 1. 模拟接收通知
- act(() => {
- socket.emit('new_event', mockEventData);
- });
-
- // 2. 验证通知显示
- await waitFor(() => {
- expect(screen.getByText('测试通知')).toBeInTheDocument();
- });
-
- // 3. 模拟点击
- const notification = screen.getByText('测试通知').closest('[role="status"]');
- fireEvent.click(notification);
-
- // 4. 验证导航
- expect(mockNavigate).toHaveBeenCalledWith('/event-detail/test001');
-
- // 5. 验证性能指标
- const stats = notificationMetricsService.getSummary();
- expect(stats.totalClicked).toBe(1);
- });
-});
-```
-
-### 测试覆盖率目标
-
-| 模块 | 目标覆盖率 | 优先级 |
-|------|-----------|--------|
-| **notificationTypes.js** | 100% | 高 |
-| **notificationHistoryService.js** | 90%+ | 高 |
-| **notificationMetricsService.js** | 90%+ | 高 |
-| **browserNotificationService.js** | 80%+ | 中 |
-| **NotificationContext.js** | 70%+ | 中 |
-| **NotificationContainer/index.js** | 60%+ | 中 |
-| **socketService.js** | 50%+ | 低（难以测试） |
-
----
-
-## 🎨 通知类型配置
+### 🎯 通知类型配置
### 类型 1: 公告通知 (Announcement)
@@ -1426,7 +1094,7 @@ describe('通知系统集成测试', () => {
---
-## 📊 优先级配置
+### 📊 优先级配置
| 优先级 | 标签 | 边框 | 自动关闭 | 使用场景 |
|--------|------|------|---------|----------|
@@ -1463,126 +1131,939 @@ export const PRIORITY_CONFIGS = {
---
-## 🚀 快速开始
+### 环境配置
-### 1. 启用 Mock 模式
+### API 配置
-在 `.env` 文件中添加：
-```bash
-REACT_APP_ENABLE_MOCK=true
-```
-
-### 2. 启动项目
+在 `.env` 文件中配置后端地址：
```bash
-npm start
+# 开发环境
+REACT_APP_API_URL=http://49.232.185.254:5001
+
+# 生产环境
+REACT_APP_API_URL=
+# 空字符串表示使用相对路径
```
-### 3. 测试通知
+### Socket 连接配置
-打开浏览器控制台 (`F12` → `Console`)，使用以下命令测试：
+Socket 服务会自动读取 `REACT_APP_API_URL` 并连接到后端：
-#### **Mock 模式测试**（开发环境）
```javascript
-// 发送测试通知
-__mockSocket.sendTestNotification()
+// src/services/socketService.js
+const API_BASE_URL = getApiBase();
-// 模拟断线重连
-__mockSocket.simulateDisconnection()
-
-// 查看连接状态
-__mockSocket.isConnected()
+this.socket = io(API_BASE_URL, {
+ transports: ['websocket', 'polling'],
+ reconnection: false, // 使用自定义重连策略
+ timeout: 20000,
+ withCredentials: true,
+});
```
-#### **通用测试命令**
-```javascript
-// 查看系统状态
-__DEBUG__.diagnose()
-
-// 查看连接状态
-__DEBUG__.socket.getStatus()
-
-// 查看通知权限
-window.browserNotificationService.getPermissionStatus()
-```
-
-### 4. 自动推送
-
-Mock 模式下，系统会自动每 60 秒推送 1-2 条随机金融资讯。
-
-查看更多测试命令，请参考本文档开头的 [用户快速指南](#-用户快速指南)。
-
---
-## 💻 代码使用
+## ✨ 第七部分：增强功能详解
-### 在组件中使用
+### 🔔 功能 1：智能桌面通知
+
+#### 功能说明
+
+首次收到重要/紧急通知时，自动请求浏览器通知权限，确保用户不错过关键信息。
+
+#### 工作原理
+```javascript
+// 在 NotificationContext 中的逻辑
+if (priority === URGENT || priority === IMPORTANT) {
+ if (browserPermission === 'default' && !hasRequestedPermission) {
+ // 首次遇到重要通知，自动请求权限
+ await requestBrowserPermission();
+ setHasRequestedPermission(true); // 避免重复请求
+ }
+}
+```
+
+#### 权限状态
+
+- **granted**: 已授权，可以发送桌面通知
+- **denied**: 已拒绝，无法发送桌面通知
+- **default**: 未请求，首次重要通知时会自动请求
+
+#### 使用示例
+
+**自动触发**（推荐）
+```javascript
+// 无需任何代码，系统自动处理
+// 首次收到重要/紧急通知时会自动弹出权限请求
+```
+
+**手动请求**
```javascript
import { useNotification } from 'contexts/NotificationContext';
-import { NOTIFICATION_TYPES, PRIORITY_LEVELS } from 'constants/notificationTypes';
-function MyComponent() {
- const { addNotification, isConnected } = useNotification();
-
- 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',
- autoClose: 10000,
- });
- };
+function SettingsPage() {
+ const { requestBrowserPermission, browserPermission } = useNotification();
return (
-
连接状态: {isConnected ? '已连接' : '未连接'}
-
+
当前状态: {browserPermission}
+