连接状态: {isConnected ? '已连接' : '未连接'}
);
}
```
---
## 🔧 环境配置
### Mock 模式 vs Real 模式
| 配置项 | Mock 模式 | Real 模式 |
|--------|----------|----------|
| **启用方式** | `REACT_APP_ENABLE_MOCK=true` | `REACT_APP_ENABLE_MOCK=false` |
| **Socket 服务** | mockSocketService | socketService (Socket.IO) |
| **推送数据** | 14条模拟金融资讯 | 后端 Flask-SocketIO 推送 |
| **自动推送** | 60秒推送1-2条 | 无自动推送，按需推送 |
| **重连间隔** | 10s→20s→40s | 1min→2min→4min |
| **测试函数** | `window.__mockSocket.*` | 无 |
### 修改推送频率
在 `src/services/mockSocketService.js` 中：
```javascript
// 默认: 60秒推送1-2条
socket.startMockPush(60000, 2);
// 修改为: 30秒推送1条
socket.startMockPush(30000, 1);
// 修改为: 5秒推送3条（压力测试）
socket.startMockPush(5000, 3);
```
---
## 🌐 后端集成（生产环境）
### Flask-SocketIO 配置
```python
from flask_socketio import SocketIO, emit
# 初始化 SocketIO
socketio = SocketIO(app, cors_allowed_origins=[
"http://localhost:3000",
"https://valuefrontier.cn"
])
# 推送金融资讯通知
def send_financial_notification(user_id, data):
"""
推送金融资讯通知到指定用户
参数:
user_id: 用户ID
data: 通知数据（参考通知类型配置）
"""
socketio.emit('new_event', data, room=user_id)
# 启动服务器
if __name__ == '__main__':
socketio.run(app, host='0.0.0.0', port=5001)
```
### 后端推送示例
```python
import time
# 推送事件动向
socketio.emit('new_event', {
'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)
```
---
## 🐛 故障排除
### 问题 1: 通知不显示
**检查项**：
1. 确认 `NotificationProvider` 已包裹应用
2. 检查浏览器控制台是否有错误
3. 确认 socket 连接状态（使用 `__DEBUG__.socket.getStatus()`）
4. 检查通知数据格式是否正确
### 问题 2: 股票动向颜色不对
**解决方案**：
1. 检查 `extra.priceChange` 字段是否存在
2. 确认格式为 "+5.2%" 或 "-3.8%"（包含符号）
3. 确认使用了 `NOTIFICATION_TYPES.STOCK_ALERT` 类型
### 问题 3: AI 徽章不显示
**解决方案**：
1. 检查 `isAIGenerated` 字段是否为 `true`
2. 确认字段名拼写正确（驼峰命名）
### 问题 4: 浏览器通知不工作
**解决方案**：
1. 检查浏览器通知权限是否已授予
2. macOS: 关闭"专注模式"或"勿扰模式"
3. Chrome: 检查 `chrome://settings/content/notifications`
4. 退出全屏模式（某些浏览器全屏时不显示通知）
5. **无痕/隐私模式特别说明**：
- Chrome 无痕模式：可以授权，但关闭窗口后权限会被清除
- Safari 隐私模式：通知权限被永久拒绝，无法更改
- 建议：使用普通浏览器窗口以获得完整体验
**快速诊断**：
```javascript
// 在浏览器控制台运行
console.log('Permission:', Notification.permission); // 'granted' | 'denied' | 'default'
console.log('Supported:', 'Notification' in window); // true | false
// 完整诊断
window.__NOTIFY_DEBUG__.checkAll();
```
### 问题 5: Chrome 无痕模式/隐私模式下 `Notification.permission = 'denied'` 怎么办？
#### 🔍 问题分析
当在 Chrome 无痕模式或其他浏览器隐私模式下遇到通知权限被拒绝的情况，需要了解不同浏览器的行为差异：
**浏览器行为对比表**：
| 浏览器模式 | 初始权限状态 | 是否可授权 | 权限持久性 | 推荐方案 |
|-----------|-------------|-----------|-----------|----------|
| **Chrome 正常模式** | `default` | ✅ 可以 | ✅ 永久保存 | ⭐ 推荐使用 |
| **Chrome 无痕模式** | `default` | ✅ 可以 | ❌ 关闭窗口后清除 | 可用但需重复授权 |
| **Safari 隐私模式** | `denied` | ❌ 不可以 | ❌ 永久拒绝 | 仅网页内通知 |
| **Firefox 隐私模式** | `default` | ✅ 可以 | ❌ 关闭窗口后清除 | 可用但需重复授权 |
**关键点**：
- ✅ Chrome 无痕模式的初始状态通常是 `default`（未决定），**不是** `denied`
- ⚠️ 如果看到 `denied`，说明用户点击了"阻止"按钮
- 🚫 Safari 隐私模式会直接显示 `denied`，且无法通过代码更改
- 🔄 权限在无痕/隐私窗口关闭后会被清除（Chrome/Firefox）
#### ✅ 当前系统已自动处理
**好消息**：您的通知系统已经完美处理了这种情况！
**自动降级策略**：
```javascript
// 在 NotificationContext.js 中
if (browserPermission !== 'granted') {
// 跳过浏览器通知，只显示网页内通知
logger.warn('NotificationContext', 'Browser permission not granted');
return;
}
```
**用户引导机制**：
- 当权限为 `denied` 时，自动显示橙色提示框
- 提示内容："浏览器通知已被拒绝"
- 引导文案："💡 如需接收桌面通知，请在浏览器设置中允许通知权限"
**实际效果**：
- ✅ 网页内通知卡片继续正常显示
- ⏭️ 浏览器桌面通知被优雅跳过
- ✅ 所有核心功能不受影响
- ✅ 用户体验降级合理
#### 🛠️ 三种解决方案
**方案 1：退出无痕模式（强烈推荐）**
```bash
# 原因：
# - 权限会永久保存
# - 获得完整通知体验
# - 不需要每次重新授权
# 操作：使用普通浏览器窗口访问应用
```
**方案 2：接受降级体验（推荐）**
```bash
# 系统已自动处理：
# ✅ 网页内通知正常显示（通知卡片）
# ⏭️ 桌面通知被跳过
# ✅ 不影响核心功能
# ✅ 用户体验合理
# 操作：无需任何操作，系统自动降级
```
**方案 3：在无痕模式中重新授权（仅 Chrome/Firefox）**
**Chrome 无痕模式**：
1. 点击地址栏左侧的 🔒 锁图标
2. 找到"通知"设置项
3. 将"阻止"改为"允许"
4. 刷新页面（F5）
5. ⚠️ **注意**：关闭无痕窗口后需要重新授权
**Safari 隐私模式**：
```bash
# ❌ Safari 隐私模式无法更改权限
# 💡 建议：退出隐私模式或接受降级体验
```
#### 📊 调试与验证
**快速检查权限状态**：
```javascript
// 在浏览器控制台运行
// 方法 1：直接查看
console.log('Permission:', Notification.permission);
// 输出: 'granted' | 'denied' | 'default'
// 方法 2：检查是否支持
console.log('Supported:', 'Notification' in window);
// 输出: true | false
// 方法 3：完整诊断（推荐）
window.__NOTIFY_DEBUG__.checkAll();
```
**完整诊断输出示例**：
```bash
========== 【通知系统诊断】 ==========
✓ Socket 配置检查完成
✓ 连接状态: ✅ 已连接
✓ API Base: http://49.232.185.254:5001
✓ 浏览器通知权限: denied
========== 诊断报告 ==========
┌─────────────┬────────────────────┐
│ socket.type │ MOCK │
│ connected │ true │
│ permission │ denied │
└─────────────┴────────────────────┘
⚠️ 发现问题: ['浏览器通知权限被拒绝']
💡 修复建议:
1. 如在无痕/隐私模式，建议退出使用正常模式
2. Chrome: 点击地址栏🔒 → 通知 → 允许
3. 或接受降级体验：继续使用网页内通知
====================================
```
**测试通知（仅 Mock 模式）**：
```javascript
// 测试不同类型通知
window.__NOTIFY_DEBUG__.testNotify('announcement'); // 公告通知
window.__NOTIFY_DEBUG__.testNotify('stock_alert'); // 股票动向
window.__NOTIFY_DEBUG__.testNotify('event_alert'); // 事件动向
window.__NOTIFY_DEBUG__.testNotify('analysis_report'); // 分析报告
// 查看帮助
window.__NOTIFY_DEBUG__.help();
```
#### 🎯 最佳实践建议
**开发环境**：
```javascript
// 使用 Mock 模式 + Chrome 正常窗口
// .env.mock
REACT_APP_ENABLE_MOCK=true
// 一次授权，永久有效
```
**测试环境**：
```javascript
// 测试多种权限状态
// 1. granted - 正常授权
// 2. denied - 测试降级体验
// 3. default - 测试首次访问流程
```
**生产环境**：
```javascript
// 引导用户使用正常浏览器窗口
// 提供清晰的权限说明
// 降级体验要优雅
```
#### 📝 相关代码位置
**权限处理逻辑**：
- `src/services/browserNotificationService.js:26-31` - 权限状态获取
- `src/services/browserNotificationService.js:85-88` - 权限检查
- `src/contexts/NotificationContext.js:295-298` - 发送前权限验证
- `src/contexts/NotificationContext.js:477-506` - 拒绝时用户引导
**调试工具**：
- `src/services/socket/index.js:192-362` - `window.__NOTIFY_DEBUG__` API
---
### 问题 6: Socket 连接失败
**解决方案**：
1. 检查后端 Flask-SocketIO 是否正确运行
2. 确认 CORS 配置正确
3. 检查 `src/utils/apiConfig.js` 中的 API 地址
4. 查看控制台日志确认错误信息
### 调试工具
**控制台日志**：
```javascript
// 所有操作都有详细日志
logger.info('NotificationContext', 'Event', data);
logger.warn('NotificationContext', 'Warning', error);
logger.error('NotificationContext', 'Error', error);
```
**Mock模式测试函数**：
```javascript
// 查看可用函数
console.log(window.__mockSocket);
// 模拟断线
__mockSocket.simulateDisconnection();
// 查看连接状态
__mockSocket.isConnected();
// 查看重连次数
__mockSocket.getAttempts();
```
### 日志分析
**正常日志流程**：
```
1. [NotificationContext] Initializing socket connection...
2. [NotificationContext] Socket connected
3. [NotificationContext] Received new event { id: 'evt001', title: '...' }
4. [NotificationContext] Adding notification { id: 'evt001', type: 'event_alert' }
5. [NotificationContext] Page visible: sending web notification
```
**异常日志排查**：
```
ERROR: Socket connect_error
→ 检查后端是否运行，网络是否通畅
WARN: Duplicate notification ignored at socket level
→ 正常，去重机制工作正常
ERROR: Browser permission not granted
→ 用户未授权浏览器通知，提示用户授权
```
---
## 📏 开发规范
### 1. 添加新通知类型
**步骤**：
1. 在 `src/constants/notificationTypes.js` 添加类型定义
2. 添加类型配置（图标、颜色、样式）
3. 在 `NotificationContainer` 中添加渲染逻辑
4. 使用控制台命令测试（Mock 模式：`__mockSocket.sendTestNotification()`）
5. 更新文档
**示例**：
```javascript
// 1. 添加类型
export const NOTIFICATION_TYPES = {
// ...现有类型
MARKET_NEWS: 'market_news', // 新增
};
// 2. 添加配置
export const NOTIFICATION_TYPE_CONFIGS = {
// ...现有配置
[NOTIFICATION_TYPES.MARKET_NEWS]: {
name: '市场快讯',
icon: MdNewspaper,
colorScheme: 'teal',
bg: 'teal.50',
borderColor: 'teal.400',
iconColor: 'teal.500',
hoverBg: 'teal.100',
},
};
```
### 2. 自定义通知组件
如需完全自定义通知样式：
```javascript
import { useNotification } from 'contexts/NotificationContext';
function CustomNotification({ notification }) {
const { removeNotification, trackNotificationClick } = useNotification();
const handleClick = () => {
trackNotificationClick(notification.id);
// 自定义导航逻辑
removeNotification(notification.id, true);
};
return (