# 通知系统增强功能 - 使用指南

## 📋 概述

本指南介绍通知系统的三大增强功能：
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 (
    <div>
      <p>当前状态: {browserPermission}</p>
      <button onClick={requestBrowserPermission}>
        开启桌面通知
      </button>
    </div>
  );
}
```

### 通知分发策略

| 优先级 | 页面在前台 | 页面在后台 |
|-------|----------|----------|
| 紧急 | 桌面通知 + 网页通知 | 桌面通知 + 网页通知 |
| 重要 | 网页通知 | 桌面通知 |
| 普通 | 网页通知 | 网页通知 |

### 测试步骤

1. **清除已保存的权限状态**
   ```javascript
   localStorage.removeItem('browser_notification_requested');
   ```

2. **刷新页面**

3. **触发一个重要/紧急通知**
   - Mock 模式：等待自动推送
   - Real 模式：创建测试事件

4. **观察权限请求弹窗**
   - 浏览器会弹出通知权限请求
   - 点击"允许"授权

5. **验证桌面通知**
   - 切换到其他标签页
   - 收到重要通知时应该看到桌面通知

---

## 📊 功能 2：性能监控

### 功能说明

追踪通知推送的各项指标，包括：
- **到达率**: 发送 vs 接收
- **点击率**: 点击 vs 接收
- **响应时间**: 收到通知到点击的平均时间
- **类型分布**: 各类型通知的数量和效果
- **时段分布**: 每小时推送量

### API 参考

#### 获取汇总统计

```javascript
import { notificationMetricsService } from 'services/notificationMetricsService';

const summary = notificationMetricsService.getSummary();
console.log(summary);
/* 输出:
{
  totalSent: 100,
  totalReceived: 98,
  totalClicked: 45,
  totalDismissed: 53,
  avgResponseTime: 5200, // 毫秒
  clickRate: '45.92',    // 百分比
  deliveryRate: '98.00'  // 百分比
}
*/
```

#### 获取按类型统计

```javascript
const byType = notificationMetricsService.getByType();
console.log(byType);
/* 输出:
{
  announcement: { sent: 20, received: 20, clicked: 15, dismissed: 5, clickRate: '75.00' },
  stock_alert: { sent: 30, received: 30, clicked: 20, dismissed: 10, clickRate: '66.67' },
  event_alert: { sent: 40, received: 38, clicked: 10, dismissed: 28, clickRate: '26.32' },
  analysis_report: { sent: 10, received: 10, clicked: 0, dismissed: 10, clickRate: '0.00' }
}
*/
```

#### 获取按优先级统计

```javascript
const byPriority = notificationMetricsService.getByPriority();
console.log(byPriority);
/* 输出:
{
  urgent: { sent: 10, received: 10, clicked: 9, dismissed: 1, clickRate: '90.00' },
  important: { sent: 40, received: 39, clicked: 25, dismissed: 14, clickRate: '64.10' },
  normal: { sent: 50, received: 49, clicked: 11, dismissed: 38, clickRate: '22.45' }
}
*/
```

#### 获取每日数据

```javascript
const dailyData = notificationMetricsService.getDailyData(7); // 最近 7 天
console.log(dailyData);
/* 输出:
[
  { date: '2025-01-15', sent: 15, received: 14, clicked: 6, dismissed: 8, clickRate: '42.86' },
  { date: '2025-01-16', sent: 20, received: 20, clicked: 10, dismissed: 10, clickRate: '50.00' },
  ...
]
*/
```

#### 获取完整指标

```javascript
const allMetrics = notificationMetricsService.getAllMetrics();
console.log(allMetrics);
```

#### 导出数据

```javascript
// 导出为 JSON
const json = notificationMetricsService.exportToJSON();
console.log(json);

// 导出为 CSV
const csv = notificationMetricsService.exportToCSV();
console.log(csv);
```

#### 重置指标

```javascript
notificationMetricsService.reset();
```

### 在控制台查看实时指标

打开浏览器控制台，执行：

```javascript
// 引入服务
import { notificationMetricsService } from './services/notificationMetricsService.js';

// 查看汇总
console.table(notificationMetricsService.getSummary());

// 查看按类型分布
console.table(notificationMetricsService.getByType());

// 查看最近 7 天数据
console.table(notificationMetricsService.getDailyData(7));
```

### 监控埋点（自动）

监控服务已自动集成到 `NotificationContext`，无需手动调用：

- **trackReceived**: 收到通知时自动调用
- **trackClicked**: 点击通知时自动调用
- **trackDismissed**: 关闭通知时自动调用

### 可视化展示（可选）

你可以基于监控数据创建仪表板：

```javascript
import { notificationMetricsService } from 'services/notificationMetricsService';
import { PieChart, LineChart } from 'recharts';

function MetricsDashboard() {
  const summary = notificationMetricsService.getSummary();
  const dailyData = notificationMetricsService.getDailyData(7);
  const byType = notificationMetricsService.getByType();

  return (
    <div>
      {/* 汇总卡片 */}
      <StatsCard title="总推送数" value={summary.totalSent} />
      <StatsCard title="点击率" value={`${summary.clickRate}%`} />
      <StatsCard title="平均响应时间" value={`${summary.avgResponseTime}ms`} />

      {/* 类型分布饼图 */}
      <PieChart data={Object.entries(byType).map(([type, data]) => ({
        name: type,
        value: data.received
      }))} />

      {/* 每日趋势折线图 */}
      <LineChart data={dailyData} />
    </div>
  );
}
```

---

## 📜 功能 3：历史记录

### 功能说明

持久化存储所有接收到的通知，支持：
- 查询和筛选
- 搜索关键词
- 标记已读/已点击
- 批量删除
- 导出（JSON/CSV）

### API 参考

#### 获取历史记录（支持筛选和分页）

```javascript
import { notificationHistoryService } from 'services/notificationHistoryService';

const result = notificationHistoryService.getHistory({
  type: 'event_alert',      // 可选：筛选类型
  priority: 'urgent',       // 可选：筛选优先级
  readStatus: 'unread',     // 可选：'read' | 'unread' | 'all'
  startDate: Date.now() - 7 * 24 * 60 * 60 * 1000, // 可选：开始日期
  endDate: Date.now(),      // 可选：结束日期
  page: 1,                  // 页码
  pageSize: 20,             // 每页数量
});

console.log(result);
/* 输出:
{
  records: [...],   // 当前页的记录
  total: 150,       // 总记录数
  page: 1,          // 当前页
  pageSize: 20,     // 每页数量
  totalPages: 8     // 总页数
}
*/
```

#### 搜索历史记录

```javascript
const results = notificationHistoryService.searchHistory('降准');
console.log(results); // 返回标题/内容中包含"降准"的所有记录
```

#### 标记已读/已点击

```javascript
// 标记已读
notificationHistoryService.markAsRead('notification_id');

// 标记已点击
notificationHistoryService.markAsClicked('notification_id');
```

#### 删除记录

```javascript
// 删除单条
notificationHistoryService.deleteRecord('notification_id');

// 批量删除
notificationHistoryService.deleteRecords(['id1', 'id2', 'id3']);

// 清空所有
notificationHistoryService.clearHistory();
```

#### 获取统计数据

```javascript
const stats = notificationHistoryService.getStats();
console.log(stats);
/* 输出:
{
  total: 500,           // 总记录数
  read: 320,            // 已读数
  unread: 180,          // 未读数
  clicked: 150,         // 已点击数
  clickRate: '30.00',   // 点击率
  byType: {             // 按类型统计
    announcement: 100,
    stock_alert: 150,
    event_alert: 200,
    analysis_report: 50
  },
  byPriority: {         // 按优先级统计
    urgent: 50,
    important: 200,
    normal: 250
  }
}
*/
```

#### 导出历史记录

```javascript
// 导出为 JSON 字符串
const json = notificationHistoryService.exportToJSON({
  type: 'event_alert'  // 可选：只导出特定类型
});

// 导出为 CSV 字符串
const csv = notificationHistoryService.exportToCSV();

// 直接下载 JSON 文件
notificationHistoryService.downloadJSON();

// 直接下载 CSV 文件
notificationHistoryService.downloadCSV();
```

### 在控制台使用

打开浏览器控制台，执行：

```javascript
// 引入服务
import { notificationHistoryService } from './services/notificationHistoryService.js';

// 查看所有历史
console.table(notificationHistoryService.getHistory().records);

// 搜索
const results = notificationHistoryService.searchHistory('央行');
console.table(results);

// 查看统计
console.table(notificationHistoryService.getStats());

// 导出并下载
notificationHistoryService.downloadJSON();
```

### 数据结构

每条历史记录包含：

```javascript
{
  id: 'notif_123',           // 通知 ID
  notification: {            // 完整通知对象
    type: 'event_alert',
    priority: 'urgent',
    title: '...',
    content: '...',
    ...
  },
  receivedAt: 1737459600000, // 接收时间戳
  readAt: 1737459650000,     // 已读时间戳（null 表示未读）
  clickedAt: null,           // 已点击时间戳（null 表示未点击）
}
```

### 存储限制

- **最大数量**: 500 条（超过后自动删除最旧的）
- **存储位置**: localStorage
- **容量估算**: 约 2-5MB（取决于通知内容长度）

---

## 🔧 技术细节

### 文件结构

```
src/
├── services/
│   ├── browserNotificationService.js   [已存在] 浏览器通知服务
│   ├── notificationMetricsService.js   [新建] 性能监控服务
│   └── notificationHistoryService.js   [新建] 历史记录服务
├── contexts/
│   └── NotificationContext.js           [修改] 集成所有功能
└── components/
    └── NotificationContainer/
        └── index.js                      [修改] 添加点击追踪
```

### 修改清单

| 文件 | 修改内容 | 状态 |
|------|---------|------|
| `NotificationContext.js` | 添加智能权限请求、监控埋点、历史保存 | ✅ 已完成 |
| `NotificationContainer/index.js` | 添加点击追踪 | ✅ 已完成 |
| `notificationMetricsService.js` | 性能监控服务 | ✅ 已创建 |
| `notificationHistoryService.js` | 历史记录服务 | ✅ 已创建 |

### 数据流

```
用户收到通知
    ↓
NotificationContext.addWebNotification()
    ├─ notificationMetricsService.trackReceived()      [监控埋点]
    ├─ notificationHistoryService.saveNotification()   [历史保存]
    ├─ 首次重要通知 → requestBrowserPermission()       [智能权限]
    └─ 显示网页通知或桌面通知

用户点击通知
    ↓
NotificationContainer.handleClick()
    ├─ notificationMetricsService.trackClicked()       [监控埋点]
    ├─ notificationHistoryService.markAsClicked()      [历史标记]
    └─ 跳转到目标页面

用户关闭通知
    ↓
NotificationContext.removeNotification()
    └─ notificationMetricsService.trackDismissed()     [监控埋点]
```

---

## 🧪 测试步骤

### 1. 测试智能桌面通知

```bash
# 1. 清除已保存的权限状态
localStorage.removeItem('browser_notification_requested');

# 2. 刷新页面

# 3. 等待或触发一个重要/紧急通知

# 4. 观察浏览器弹出权限请求

# 5. 授权后验证桌面通知功能
```

### 2. 测试性能监控

```javascript
// 在控制台执行
import { notificationMetricsService } from './services/notificationMetricsService.js';

// 查看实时统计
console.table(notificationMetricsService.getSummary());

// 模拟推送几条通知，再次查看
console.table(notificationMetricsService.getAllMetrics());

// 导出数据
console.log(notificationMetricsService.exportToJSON());
```

### 3. 测试历史记录

```javascript
// 在控制台执行
import { notificationHistoryService } from './services/notificationHistoryService.js';

// 查看历史
console.table(notificationHistoryService.getHistory().records);

// 搜索
console.table(notificationHistoryService.searchHistory('降准'));

// 查看统计
console.table(notificationHistoryService.getStats());

// 导出
notificationHistoryService.downloadJSON();
```

---

## 📈 数据导出示例

### 导出性能监控数据

```javascript
import { notificationMetricsService } from 'services/notificationMetricsService';

// 导出 JSON
const json = notificationMetricsService.exportToJSON();
// 复制到剪贴板或保存

// 导出 CSV
const csv = notificationMetricsService.exportToCSV();
// 可以在 Excel 中打开
```

### 导出历史记录

```javascript
import { notificationHistoryService } from 'services/notificationHistoryService';

// 导出最近 7 天的事件动向通知
const json = notificationHistoryService.exportToJSON({
  type: 'event_alert',
  startDate: Date.now() - 7 * 24 * 60 * 60 * 1000
});

// 直接下载为文件
notificationHistoryService.downloadJSON({
  type: 'event_alert'
});
```

---

## ⚠️ 注意事项

### 1. localStorage 容量限制

- 大多数浏览器限制为 5-10MB
- 建议定期清理历史记录和监控数据
- 使用导出功能备份数据

### 2. 浏览器兼容性

- **桌面通知**: 需要 HTTPS 或 localhost
- **localStorage**: 所有现代浏览器支持
- **权限请求**: 需要用户交互（不能自动授权）

### 3. 隐私和数据安全

- 所有数据存储在本地（localStorage）
- 不会上传到服务器
- 用户可以随时清空数据

### 4. 性能影响

- 监控埋点非常轻量，几乎无性能影响
- 历史记录保存异步进行，不阻塞 UI
- 数据查询在客户端完成，不增加服务器负担

---

## 🎉 总结

### 已实现的功能

✅ **智能桌面通知**
- 首次重要通知时自动请求权限
- 智能分发策略（前台/后台）
- localStorage 持久化权限状态

✅ **性能监控**
- 到达率、点击率、响应时间追踪
- 按类型、优先级、时段统计
- 数据导出（JSON/CSV）

✅ **历史记录**
- 持久化存储（最多 500 条）
- 筛选、搜索、分页
- 已读/已点击标记
- 数据导出（JSON/CSV）

### 未实现的功能（备份，待上线）

⏸️ 历史记录页面 UI（代码已备份，随时可上线）
⏸️ 监控仪表板 UI（可选，暂未实现）

### 下一步建议

1. **用户设置页面**: 允许用户自定义通知偏好
2. **声音提示**: 为紧急通知添加音效
3. **数据同步**: 将历史和监控数据同步到服务器
4. **高级筛选**: 添加更多筛选维度（如关键词、股票代码等）

---

**文档版本**: v1.0
**最后更新**: 2025-01-21
**维护者**: Claude Code