`selectedDateEvents` 更新
`isOpen = true` | 打开事件详情 Modal，显示当天所有事件 | - | +| **点击"添加计划"** | `isAddOpen = true`
`selectedDate` 设置 | 打开添加计划 Modal，表单为空 | - | +| **保存计划成功** | `isAddOpen = false` | 关闭 Modal，显示 Toast 提示，日历刷新显示新事件 | API 7 | +| **删除日历事件** | 确认对话框 → `events` 更新 | 二次确认，Toast 提示，日历移除该事件标记 | API 8 | +| **切换到"我的复盘" Tab** | Tab `index` 变化 | 显示复盘列表内容，隐藏计划列表 | - | +| **点击"新建复盘"** | `isOpen = true`
`editingItem = null`
`formData.type = 'review'` | 打开编辑 Modal，标题为"新建复盘记录" | - | +| **保存复盘成功** | `isOpen = false` | 关闭 Modal，Toast 提示，列表新增卡片 | API 10 | +| **点击"编辑"按钮** | `isOpen = true`
`editingItem` 更新
`formData` 预填充 | 打开编辑 Modal，表单显示现有数据 | - | +| **更新成功** | `isOpen = false` | 关闭 Modal，Toast 提示，卡片内容更新 | API 11 | +| **点击"删除"按钮** | 确认对话框 → `plans/reviews` 更新 | 二次确认，Toast 提示，列表移除该卡片 | API 12 | +| **页面从后台切回** | `visibilitychange` 事件 | 自动调用 `loadData()`，全部数据静默刷新 | API 1-4 | +| **自选股数量变化** | `watchlist.length` 变化 | 定时器重新创建 (有股票时启动，无股票时停止) | - | +| **添加股票标签** | `formData.stocks` 数组新增 | 表单中新增蓝色 Tag，带关闭按钮 | - | +| **添加自定义标签** | `formData.tags` 数组新增 | 表单中新增紫色 Tag，带关闭按钮 | - | + +--- + +## 八、关键设计亮点 + +### 1. 性能优化 + +#### 1.1 并行请求 +```javascript +// 使用 Promise.all() 并行加载 4 个 API，减少总等待时间 +const [w, e, c, s] = await Promise.all([ + fetch('/api/account/watchlist'), + fetch('/api/account/events/following'), + fetch('/api/account/events/comments'), + fetch('/api/subscription/current'), +]); +``` +**优势**: +- 串行请求总耗时: ~3.2秒 (800ms × 4) +- 并行请求总耗时: ~800ms (仅等待最慢的一个) +- **性能提升 75%** + +#### 1.2 缓存控制 +```javascript +// 添加时间戳和缓存控制头，确保获取最新数据 +fetch(`/api/account/watchlist?_=${Date.now()}`, { + cache: 'no-store', + headers: { 'Cache-Control': 'no-cache' } +}); +``` +**作用**: 防止浏览器缓存旧数据，确保数据新鲜度 + +#### 1.3 条件加载 +```javascript +// 只有在有自选股时才加载实时行情 +if (jw.data && jw.data.length > 0) { + loadRealtimeQuotes(); +} +``` +**优势**: 避免不必要的 API 请求，节省服务器资源 + +#### 1.4 定时刷新优化 +```javascript +// 仅在有自选股时启动定时器 +if (watchlist.length > 0) { + const interval = setInterval(() => { + loadRealtimeQuotes(); // 60秒刷新一次 + }, 60000); + return () => clearInterval(interval); +} +``` +**优势**: +- 自选股为空时不启动定时器 +- 组件卸载时自动清理，防止内存泄漏 + +#### 1.5 页面可见性检测 +```javascript +// 页面从后台切回前台时自动刷新数据 +document.addEventListener('visibilitychange', () => { + if (document.visibilityState === 'visible') { + loadData(); + } +}); +``` +**用户体验**: +- 用户切回标签页时看到最新数据 +- 无需手动刷新 + +--- + +### 2. 用户体验优化 + +#### 2.1 多层次加载状态 +```javascript +const [loading, setLoading] = useState(true); // 初次加载 +const [refreshing, setRefreshing] = useState(false); // 手动刷新 +const [quotesLoading, setQuotesLoading] = useState(false); // 行情刷新 +``` +**好处**: +- 用户清楚知道哪个部分正在加载 +- 不同操作有不同的视觉反馈 + +#### 2.2 响应式布局 +```javascript +
+
+ );
+}
+```
+
+### 通知分发策略
+
+| 优先级 | 页面在前台 | 页面在后台 |
+|-------|----------|----------|
+| 紧急 | 桌面通知 + 网页通知 | 桌面通知 + 网页通知 |
+| 重要 | 网页通知 | 桌面通知 |
+| 普通 | 网页通知 | 网页通知 |
+
+### 测试步骤
+
+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 (
+ 当前状态: {browserPermission}
+ +
+ {/* 汇总卡片 */}
+ ({
+ name: type,
+ value: data.received
+ }))} />
+
+ {/* 每日趋势折线图 */}
+
+ );
+}
+```
+
+---
+
+## 📜 功能 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
diff --git a/docs/ENVIRONMENT_SETUP.md b/docs/ENVIRONMENT_SETUP.md
new file mode 100644
index 00000000..818229f9
--- /dev/null
+++ b/docs/ENVIRONMENT_SETUP.md
@@ -0,0 +1,376 @@
+# 环境配置指南
+
+本文档详细说明项目的环境配置和启动方式。
+
+## 📊 环境模式总览
+
+| 模式 | 命令 | Mock | 后端位置 | PostHog | 适用场景 |
+|------|------|------|---------|---------|---------|
+| **本地混合** | `npm start` | ✅ 智能穿透 | 远程 | 可选双模式 | 日常前端开发（推荐） |
+| **本地全栈** | `npm run start:test` | ❌ | 本地 | 可选双模式 | 后端调试、性能测试 |
+| **远程开发** | `npm run start:dev` | ❌ | 远程 | 可选双模式 | 联调真实后端 |
+| **纯 Mock** | `npm run start:mock` | ✅ 完全拦截 | 无 | 可选双模式 | 前端完全独立开发 |
+| **生产构建** | `npm run build` | ❌ | 生产服务器 | ✅ 仅上报 | 部署上线 |
+
+---
+
+## 1️⃣ 本地混合模式（推荐）
+
+### 启动命令
+```bash
+npm start
+# 或
+npm run start:local
+```
+
+### 配置文件
+`.env.local`
+
+### 特点
+- 🎯 **MSW 智能拦截**：
+ - 已定义 Mock 的接口 → 返回 Mock 数据
+ - 未定义 Mock 的接口 → 自动转发到远程后端
+- 💡 **最佳效率**：前端独立开发，部分依赖真实数据
+- 🚀 **快速迭代**：无需等待后端，无需本地运行后端
+- 🔄 **自动端口清理**：启动前自动清理 3000 端口
+
+### 适用场景
+- ✅ 日常前端 UI 开发
+- ✅ 页面布局调整
+- ✅ 组件开发测试
+- ✅ 样式优化
+
+### 工作流程
+```bash
+# 1. 启动项目
+npm start
+
+# 2. 观察控制台
+# ✅ MSW 启动成功
+# ✅ PostHog 初始化
+# ✅ 拦截日志显示
+
+# 3. 开发测试
+# - Mock 接口：立即返回假数据
+# - 真实接口：请求远程后端
+```
+
+### PostHog 配置
+编辑 `.env.local`：
+```env
+# 仅控制台 debug（初期开发）
+REACT_APP_POSTHOG_KEY=
+
+# 控制台 + PostHog Cloud（完整测试）
+REACT_APP_POSTHOG_KEY=phc_your_test_key_here
+```
+
+---
+
+## 2️⃣ 本地全栈模式
+
+### 启动命令
+```bash
+npm run start:test
+```
+
+### 配置文件
+`.env.test`
+
+### 特点
+- 🖥️ **前后端都在本地**：
+ - 前端：localhost:3000
+ - 后端：localhost:5001
+- 🗄️ **本地数据库**：数据隔离，不影响团队
+- 🔍 **完整调试**：可以打断点调试后端代码
+- 📊 **性能分析**：测试数据库查询、接口性能
+
+### 适用场景
+- ✅ 调试后端 Python 代码
+- ✅ 测试数据库查询优化
+- ✅ 性能测试和压力测试
+- ✅ 离线开发（无网络）
+- ✅ 数据迁移脚本测试
+
+### 工作流程
+```bash
+# 1. 启动全栈（自动启动前后端）
+npm run start:test
+
+# 观察日志：
+# [backend] Flask 服务器启动在 5001 端口
+# [frontend] React 启动在 3000 端口
+
+# 2. 或手动分别启动
+# 终端 1
+python app_2.py
+
+# 终端 2
+npm run frontend:test
+```
+
+### 注意事项
+- ⚠️ 确保本地安装了 Python 环境
+- ⚠️ 确保安装了 requirements.txt 中的依赖
+- ⚠️ 确保本地数据库已配置
+
+---
+
+## 3️⃣ 远程开发模式
+
+### 启动命令
+```bash
+npm run start:dev
+```
+
+### 配置文件
+`.env.development`
+
+### 特点
+- 🌐 **连接远程后端**：http://49.232.185.254:5001
+- 📡 **真实数据**：远程开发数据库
+- 🤝 **团队协作**：与后端团队联调
+- ⚡ **无需本地后端**：专注前端开发
+
+### 适用场景
+- ✅ 联调后端最新代码
+- ✅ 测试真实数据表现
+- ✅ 验证接口文档
+- ✅ 跨服务功能测试
+
+### 工作流程
+```bash
+# 1. 启动前端（连接远程后端）
+npm run start:dev
+
+# 2. 观察控制台
+# ✅ 所有请求发送到远程服务器
+# ✅ 无 MSW 拦截
+
+# 3. 联调测试
+# - 测试最新后端接口
+# - 反馈问题给后端团队
+```
+
+---
+
+## 4️⃣ 纯 Mock 模式
+
+### 启动命令
+```bash
+npm run start:mock
+```
+
+### 配置文件
+`.env.mock`
+
+### 特点
+- 📦 **完全 Mock**：所有请求都被 MSW 拦截
+- ⚡ **完全离线**：无需任何后端服务
+- 🎨 **纯前端**：专注 UI/UX 开发
+
+### 适用场景
+- ✅ 后端接口未开发完成
+- ✅ 完全独立的前端开发
+- ✅ UI 原型展示
+
+---
+
+## 🔧 PostHog 配置说明
+
+### 双模式运行
+
+PostHog 支持两种模式：
+
+#### 模式 1：仅控制台 Debug（推荐初期）
+```env
+REACT_APP_POSTHOG_KEY= # 留空
+```
+
+**效果：**
+- ✅ 控制台打印所有事件日志
+- ✅ 验证事件触发逻辑
+- ✅ 检查事件属性
+- ❌ 不实际发送到 PostHog 服务器
+
+**控制台输出示例：**
+```javascript
+✅ PostHog initialized successfully
+📊 PostHog Analytics initialized
+📍 Event tracked: community_page_viewed { ... }
+```
+
+#### 模式 2：控制台 + PostHog Cloud（完整测试）
+```env
+REACT_APP_POSTHOG_KEY=phc_your_test_key_here
+```
+
+**效果：**
+- ✅ 控制台打印所有事件日志
+- ✅ 同时发送到 PostHog Cloud
+- ✅ 在 PostHog Dashboard 查看 Live Events
+- ✅ 测试完整的分析功能
+
+### 获取 PostHog API Key
+
+1. 登录 PostHog：https://app.posthog.com
+2. 创建项目（建议创建独立的测试项目）
+3. 进入项目设置 → Project API Key
+4. 复制 API Key（格式：`phc_xxxxxxxxxxxxxx`）
+5. 填入对应环境的 `.env` 文件
+
+### 推荐配置
+
+```bash
+# 本地开发（.env.local）
+REACT_APP_POSTHOG_KEY= # 留空，仅控制台
+
+# 测试环境（.env.test）
+REACT_APP_POSTHOG_KEY=phc_test_key # 测试项目 Key
+
+# 开发环境（.env.development）
+REACT_APP_POSTHOG_KEY=phc_dev_key # 开发项目 Key
+
+# 生产环境（.env）
+REACT_APP_POSTHOG_KEY=phc_prod_key # 生产项目 Key
+```
+
+---
+
+## 🛠️ 端口管理
+
+### 自动清理 3000 端口
+
+所有 `npm start` 命令会自动执行 `prestart` 钩子，清理 3000 端口：
+
+```bash
+# 自动执行
+npm start
+# → 先执行 kill-port 3000
+# → 再执行 craco start
+```
+
+### 手动清理端口
+
+```bash
+npm run kill-port
+```
+
+---
+
+## 📁 环境变量文件说明
+
+| 文件 | 提交Git | 用途 | 优先级 |
+|------|--------|------|--------|
+| `.env` | ✅ | 生产环境 | 低 |
+| `.env.local` | ✅ | 本地混合模式 | 高 |
+| `.env.test` | ✅ | 本地测试环境 | 高 |
+| `.env.development` | ✅ | 远程开发环境 | 中 |
+| `.env.mock` | ✅ | 纯 Mock 模式 | 中 |
+
+---
+
+## 🐛 常见问题
+
+### Q1: 端口 3000 被占用
+
+**解决方案：**
+```bash
+# 方案 1：自动清理（推荐）
+npm start # 会自动清理
+
+# 方案 2：手动清理
+npm run kill-port
+```
+
+### Q2: PostHog 事件没有上报
+
+**检查清单：**
+1. 检查 `REACT_APP_POSTHOG_KEY` 是否填写
+2. 打开浏览器控制台，查看是否有初始化日志
+3. 检查网络面板，是否有请求发送到 PostHog
+4. 登录 PostHog Dashboard → Live Events 查看
+
+### Q3: Mock 数据没有生效
+
+**检查清单：**
+1. 确认 `REACT_APP_ENABLE_MOCK=true`
+2. 检查控制台是否显示 "MSW enabled"
+3. 检查 `src/mocks/handlers/` 中是否定义了对应接口
+4. 查看浏览器控制台的 MSW 拦截日志
+
+### Q4: 本地全栈模式启动失败
+
+**可能原因：**
+1. Python 环境未安装
+2. 后端依赖未安装：`pip install -r requirements.txt`
+3. 数据库未配置
+4. 端口 5001 被占用：`lsof -ti:5001 | xargs kill -9`
+
+### Q5: 环境变量不生效
+
+**解决方案：**
+1. 重启开发服务器（React 不会热更新环境变量）
+2. 检查环境变量名称是否以 `REACT_APP_` 开头
+3. 确认使用了正确的 `.env` 文件
+
+---
+
+## 🚀 快速开始
+
+### 新成员入职
+
+```bash
+# 1. 克隆项目
+git clone 
+2. 点击"登录" | 弹窗正常打开，显示登录表单 | ⬜ | +| **注册弹窗打开** | 1. 点击导航栏"登录/注册"下拉菜单
2. 点击"注册" | 弹窗正常打开，显示注册表单 | ⬜ | +| **登录弹窗关闭** | 1. 打开登录弹窗
2. 点击关闭按钮 | 弹窗正常关闭，返回原页面 | ⬜ | +| **注册弹窗关闭** | 1. 打开注册弹窗
2. 点击关闭按钮 | 弹窗正常关闭，返回原页面 | ⬜ | +| **从登录切换到注册** | 1. 打开登录弹窗
2. 点击"去注册" | 弹窗切换到注册表单，无页面刷新 | ⬜ | +| **从注册切换到登录** | 1. 打开注册弹窗
2. 点击"去登录" | 弹窗切换到登录表单，无页面刷新 | ⬜ | +| **手机号+密码登录** | 1. 打开登录弹窗
2. 输入手机号和密码
3. 点击登录 | 登录成功，弹窗关闭，显示成功提示 | ⬜ | +| **验证码登录** | 1. 打开登录弹窗
2. 切换到验证码登录
3. 发送并输入验证码
4. 点击登录 | 登录成功，弹窗关闭 | ⬜ | +| **微信登录** | 1. 打开登录弹窗
2. 点击微信登录
3. 扫码授权 | 登录成功，弹窗关闭 | ⬜ | +| **手机号+密码注册** | 1. 打开注册弹窗
2. 填写手机号、密码等信息
3. 点击注册 | 注册成功，弹窗关闭，自动登录 | ⬜ | +| **验证码注册** | 1. 打开注册弹窗
2. 切换到验证码注册
3. 发送并输入验证码
4. 点击注册 | 注册成功，弹窗关闭，自动登录 | ⬜ | +| **微信注册** | 1. 打开注册弹窗
2. 点击微信注册
3. 扫码授权 | 注册成功，弹窗关闭，自动登录 | ⬜ | + +### 5.2 受保护路由测试 + +| 测试项 | 测试步骤 | 预期结果 | 状态 | +|-------|---------|---------|-----| +| **未登录访问概念中心** | 1. 未登录状态
2. 访问 `/concepts` | 自动弹出登录弹窗 | ⬜ | +| **登录后继续访问** | 1. 在上述弹窗中登录
2. 查看页面状态 | 弹窗关闭，概念中心页面正常显示 | ⬜ | +| **未登录访问社区** | 1. 未登录状态
2. 访问 `/community` | 自动弹出登录弹窗 | ⬜ | +| **未登录访问个股中心** | 1. 未登录状态
2. 访问 `/stocks` | 自动弹出登录弹窗 | ⬜ | +| **未登录访问模拟盘** | 1. 未登录状态
2. 访问 `/trading-simulation` | 自动弹出登录弹窗 | ⬜ | +| **未登录访问管理后台** | 1. 未登录状态
2. 访问 `/admin/*` | 自动弹出登录弹窗 | ⬜ | + +### 5.3 登出测试 + +| 测试项 | 测试步骤 | 预期结果 | 状态 | +|-------|---------|---------|-----| +| **从导航栏登出** | 1. 已登录状态
2. 点击用户菜单"退出登录" | 登出成功，留在当前页面，显示未登录状态 | ⬜ | +| **登出后访问受保护页面** | 1. 登出后
2. 尝试访问 `/concepts` | 自动弹出登录弹窗 | ⬜ | + +### 5.4 边界情况测试 + +| 测试项 | 测试步骤 | 预期结果 | 状态 | +|-------|---------|---------|-----| +| **登录失败** | 1. 输入错误的手机号或密码
2. 点击登录 | 显示错误提示，弹窗保持打开 | ⬜ | +| **网络断开** | 1. 断开网络
2. 尝试登录 | 显示网络错误提示 | ⬜ | +| **倒计时中关闭弹窗** | 1. 发送验证码（60秒倒计时）
2. 关闭弹窗
3. 重新打开 | 倒计时正确清理，无内存泄漏 | ⬜ | +| **重复打开弹窗** | 1. 快速连续点击登录按钮多次 | 只显示一个弹窗，无重复 | ⬜ | +| **响应式布局** | 1. 在手机端打开登录弹窗 | 弹窗全屏显示，UI适配良好 | ⬜ | + +### 5.5 兼容性测试 + +| 测试项 | 测试步骤 | 预期结果 | 状态 | +|-------|---------|---------|-----| +| **直接访问登录页面** | 1. 访问 `/auth/sign-in` | 页面正常显示（保持路由兼容） | ⬜ | +| **直接访问注册页面** | 1. 访问 `/auth/sign-up` | 页面正常显示（保持路由兼容） | ⬜ | +| **SEO爬虫访问** | 1. 模拟搜索引擎爬虫访问 | 页面可访问，无JavaScript错误 | ⬜ | + +--- + +## 6. 兼容性处理 + +### 6.1 保留现有路由 + +为了兼容性和SEO，保留现有的登录/注册页面路由： + +```javascript +// src/layouts/Auth.js +// 保持不变，继续支持 /auth/sign-in 和 /auth/sign-up 路由 +
2. 访问 `/home/center` | 页面正常加载，显示所有板块 | ⬜ | +| **统计卡片显示** | 查看顶部4个统计卡片 | 显示：自选股(5)、关注事件(5)、我的评论(5)、订阅状态(Pro版) | ⬜ | +| **自选股列表** | 查看自选股板块 | 显示5只股票，包含股票代码、名称、价格、涨跌幅 | ⬜ | +| **实时行情** | 等待实时行情加载 | 股票价格显示，涨跌幅有颜色标识（红涨绿跌） | ⬜ | +| **关注事件列表** | 查看关注事件板块 | 显示5个事件，包含标题、标签、统计数据、热度分数 | ⬜ | +| **我的评论列表** | 查看我的评论板块 | 显示5条评论，包含内容、时间、关联事件 | ⬜ | +| **订阅信息卡片** | 查看订阅管理板块 | 显示Pro版，剩余90天，状态正常 | ⬜ | + +#### 自选股功能 + +| 测试项 | 测试步骤 | 预期结果 | 状态 | +|-------|---------|---------|-----| +| **查看自选股详情** | 点击任一自选股 | 跳转到个股详情页 | ⬜ | +| **刷新实时行情** | 点击刷新按钮 | 显示Loading，刷新完成后更新价格数据 | ⬜ | +| **自动刷新行情** | 等待60秒 | 自动刷新实时行情（每分钟一次） | ⬜ | + +#### 投资计划功能 + +| 测试项 | 测试步骤 | 预期结果 | 状态 | +|-------|---------|---------|-----| +| **查看投资计划** | 滚动到投资计划板块 | 显示4条记录（2个计划 + 2个复盘） | ⬜ | +| **创建计划** | 1. 点击"新增计划"
2. 填写表单
3. 提交 | 计划创建成功，列表刷新 | ⬜ | +| **编辑计划** | 1. 点击编辑按钮
2. 修改内容
3. 保存 | 计划更新成功，显示更新后的内容 | ⬜ | +| **删除计划** | 1. 点击删除按钮
2. 确认删除 | 计划删除成功，列表刷新 | ⬜ | +| **计划状态切换** | 切换计划状态（待进行/进行中/已完成） | 状态更新成功，显示对应标识 | ⬜ | + +#### 投资日历功能 + +| 测试项 | 测试步骤 | 预期结果 | 状态 | +|-------|---------|---------|-----| +| **查看日历** | 查看投资日历板块 | 显示月视图，标记有事件的日期 | ⬜ | +| **查看事件** | 点击有事件的日期 | 显示当天的事件列表（支持多个事件） | ⬜ | +| **创建事件** | 1. 选择日期
2. 点击"添加事件"
3. 填写表单
4. 提交 | 事件创建成功，日历更新 | ⬜ | +| **编辑事件** | 1. 点击事件
2. 修改信息
3. 保存 | 事件更新成功 | ⬜ | +| **删除事件** | 1. 点击事件
2. 点击删除
3. 确认 | 事件删除成功，日历更新 | ⬜ | +| **重复事件** | 创建一个重复事件（如每月20日） | 日历上多个日期显示该事件 | ⬜ | + +#### 订阅管理功能 + +| 测试项 | 测试步骤 | 预期结果 | 状态 | +|-------|---------|---------|-----| +| **查看订阅详情** | 点击订阅卡片 | 跳转到订阅管理页面 | ⬜ | +| **订阅权限检查** | 访问需要权限的功能 | Pro用户可访问，Free用户提示升级 | ⬜ | + +### 5.2 数据一致性测试 + +| 测试项 | 验证方法 | 预期结果 | 状态 | +|-------|---------|---------|-----| +| **自选股与行情匹配** | 对比自选股列表和实时行情 | 每只自选股都有对应的行情数据 | ⬜ | +| **评论与事件关联** | 点击评论中的事件链接 | 能正确跳转到对应事件 | ⬜ | +| **日历事件与股票关联** | 查看带股票代码的日历事件 | 点击能跳转到对应股票详情 | ⬜ | +| **订阅类型一致性** | 对比多处显示的订阅类型 | 统计卡片、订阅管理、权限检查一致 | ⬜ | + +### 5.3 边界情况测试 + +| 测试项 | 测试步骤 | 预期结果 | 状态 | +|-------|---------|---------|-----| +| **空数据状态** | 1. 清空所有自选股
2. 刷新页面 | 显示"暂无自选股"提示，引导添加 | ⬜ | +| **网络延迟** | 模拟慢速网络 | 显示Loading状态，300ms后加载完成 | ⬜ | +| **未登录状态** | 未登录访问个人中心 | 返回401错误（被ProtectedRoute拦截） | ⬜ | +| **大数据量** | 添加10+只自选股 | 前端只显示前10只，其他可查看全部 | ⬜ | +| **日期范围查询** | 查询特定月份的日历事件 | 只返回该月份的事件 | ⬜ | + +--- + +## 6. 附录 + +### 6.1 API 请求示例 + +#### 获取自选股列表 +```javascript +// 请求 +GET /api/account/watchlist + +// 响应 +{ + "success": true, + "data": [ + { + "id": 1, + "user_id": 1, + "stock_code": "600519.SH", + "stock_name": "贵州茅台", + "industry": "白酒", + "current_price": 1650.50, + "change_percent": 2.5, + "added_at": "2025-01-10T10:30:00Z" + }, + ... + ] +} +``` + +#### 创建投资计划 +```javascript +// 请求 +POST /api/account/investment-plans +Content-Type: application/json + +{ + "type": "plan", + "title": "2025年Q1 新能源板块布局计划", + "content": "计划在Q1分批建仓新能源板块...", + "target_date": "2025-03-31", + "status": "pending", + "tags": ["新能源", "布局计划"] +} + +// 响应 +{ + "success": true, + "message": "创建成功", + "data": { + "id": 305, + "user_id": 1, + "type": "plan", + "title": "2025年Q1 新能源板块布局计划", + "content": "计划在Q1分批建仓新能源板块...", + "target_date": "2025-03-31", + "status": "pending", + "tags": ["新能源", "布局计划"], + "created_at": "2025-01-19T10:00:00Z", + "updated_at": "2025-01-19T10:00:00Z" + } +} +``` + +#### 获取日历事件（日期范围） +```javascript +// 请求 +GET /api/account/calendar/events?start_date=2025-01-01&end_date=2025-01-31 + +// 响应 +{ + "success": true, + "data": [ + { + "id": 403, + "user_id": 1, + "title": "央行货币政策委员会例会", + "date": "2025-01-25", + "type": "policy", + "category": "macro_policy", + "importance": "medium", + "created_at": "2025-01-08T09:00:00Z" + }, + ... + ] +} +``` + +### 6.2 数据模型 ER 图 + +``` +User (用户) + ├─ 1:N → Watchlist (自选股) + ├─ 1:N → FollowingEvents (关注事件) + ├─ 1:N → EventComments (评论) + ├─ 1:N → InvestmentPlans (投资计划) + ├─ 1:N → CalendarEvents (日历事件) + └─ 1:1 → Subscription (订阅信息) + +Event (事件) + ├─ 1:N → EventComments (评论) + └─ N:N → Users (关注用户) + +Stock (股票) + ├─ 1:N → Watchlist (自选股) + ├─ 1:1 → RealtimeQuote (实时行情) + └─ 1:N → CalendarEvents (日历事件) +``` + +### 6.3 Mock 数据统计 + +| 数据类型 | 数量 | 字段数 | 总大小（估算） | +|---------|-----|--------|--------------| +| 自选股 | 5 | 8 | 约 0.5KB | +| 实时行情 | 5 | 11 | 约 0.8KB | +| 关注事件 | 5 | 10 | 约 2KB | +| 评论 | 5 | 8 | 约 1.5KB | +| 投资计划 | 4 | 10 | 约 3KB | +| 日历事件 | 7 | 12 | 约 1.5KB | +| **总计** | **31** | **59** | **约 9.3KB** | + +### 6.4 前端组件映射 + +| 前端组件 | 使用的 API | Mock 数据来源 | +|---------|-----------|-------------| +| `Center.js` (主组件) | 4个并行API | `mockWatchlist`, `mockFollowingEvents`, `mockEventComments`, `mockSubscriptionCurrent` | +| 自选股卡片 | `/api/account/watchlist` | `mockWatchlist` | +| 实时行情刷新 | `/api/account/watchlist/realtime` | `mockRealtimeQuotes` | +| 关注事件列表 | `/api/account/events/following` | `mockFollowingEvents` | +| 我的评论列表 | `/api/account/events/comments` | `mockEventComments` | +| 订阅信息卡片 | `/api/subscription/current` | `mockSubscriptionCurrent` | +| `InvestmentCalendarChakra.js` | `/api/account/calendar/events` | `mockCalendarEvents` | +| `InvestmentPlansAndReviews.js` | `/api/account/investment-plans` | `mockInvestmentPlans` | + +### 6.5 常见问题 (FAQ) + +**Q1: Mock 数据会持久化吗？** +A: 不会。Mock 数据存储在内存中，刷新页面后会重置。如果需要持久化，可以考虑使用 localStorage。 + +**Q2: 如何切换到真实 API？** +A: 在 `.env` 文件中设置 `REACT_APP_ENABLE_MOCK=false` 即可切换到真实 API。 + +**Q3: Mock 数据支持多用户吗？** +A: 目前的 Mock 数据基于当前登录用户（`getCurrentUser()`），支持基本的多用户场景。 + +**Q4: 实时行情数据是真的实时吗？** +A: Mock 模式下不是真实的实时数据，只是静态数据。真实环境下需要对接WebSocket或轮询API。 + +**Q5: 如何添加更多 Mock 数据？** +A: 编辑 `src/mocks/data/account.js`，在对应的数组中添加新的数据对象即可。 + +### 6.6 后续优化建议 + +#### 短期优化（1周内） +- [ ] 添加更多股票到自选股池（目前5只 → 10只） +- [ ] 丰富事件类型和标签 +- [ ] 完善投资计划的标签系统 +- [ ] 添加日历事件的提醒功能Mock + +#### 中期优化（1月内） +- [ ] 实现 Mock 数据的 localStorage 持久化 +- [ ] 添加数据导入/导出功能 +- [ ] 模拟网络波动和错误场景 +- [ ] 添加更多的边界测试用例 + +#### 长期优化（3月内） +- [ ] 实现完整的 Mock 数据生成器 +- [ ] 支持批量生成测试数据 +- [ ] 添加数据一致性校验工具 +- [ ] 完善 Mock 数据文档和最佳实践 + +--- + +## ✅ 总结 + +### 完成内容 +- ✅ 创建完整的 Mock 数据文件 (`src/mocks/data/account.js`) +- ✅ 重写并扩展 Mock Handler (`src/mocks/handlers/account.js`) +- ✅ 实现 20 个 API 接口的 Mock +- ✅ 提供 31 条 Mock 数据记录 +- ✅ 验证 handlers/index.js 配置正确 + +### 覆盖功能 +- ✅ 自选股管理（查看、添加、删除、实时行情） +- ✅ 事件关注（关注列表、我的评论） +- ✅ 投资计划（增删改查、计划与复盘） +- ✅ 投资日历（增删改查、日期范围查询） +- ✅ 订阅信息（订阅详情、权限管理） +- ✅ 用户资料（资料完整度、更新资料） + +### 数据质量 +- ✅ 数据真实性：使用真实股票和合理价格 +- ✅ 数据关联性：评论关联事件、日历关联股票 +- ✅ 数据可扩展性：预留字段、支持动态操作 +- ✅ 数据完整性：包含所有必需字段 + +### 测试准备 +- ✅ 提供完整的测试用例清单 +- ✅ 覆盖功能、数据一致性、边界测试 +- ✅ 包含42个测试项 +- ✅ 提供测试步骤和预期结果 + +--- + +**文档版本**: 1.0 +**生成日期**: 2025-01-19 +**维护者**: Development Team +**相关文档**: +- `CONSOLE_LOG_REFACTOR_REPORT.md` - Console Log 重构文档 +- `LOGIN_MODAL_REFACTOR_PLAN.md` - 登录弹窗改造计划 + diff --git a/docs/MOCK_GUIDE.md b/docs/MOCK_GUIDE.md new file mode 100644 index 00000000..8b0960cd --- /dev/null +++ b/docs/MOCK_GUIDE.md @@ -0,0 +1,405 @@ +# Mock Service Worker 使用指南 + +本项目已集成 **Mock Service Worker (MSW)**，提供本地 Mock API 能力，无需依赖后端即可进行前端开发和测试。 + +## 📖 目录 + +1. [快速开始](#快速开始) +2. [启动方式](#启动方式) +3. [环境配置](#环境配置) +4. [Mock 数据说明](#mock-数据说明) +5. [如何添加新的 Mock API](#如何添加新的-mock-api) +6. [调试技巧](#调试技巧) +7. [常见问题](#常见问题) + +--- + +## 🚀 快速开始 + +### 方式一：启动 Mock 环境（使用本地 Mock 数据） + +```bash +npm run start:mock +``` + +启动后，浏览器控制台会显示： +``` +[MSW] Mock Service Worker 已启动 🎭 +提示: 所有 API 请求将使用本地 Mock 数据 +要禁用 Mock，请设置 REACT_APP_ENABLE_MOCK=false +``` + +### 方式二：启动开发环境（连接真实后端） + +```bash +npm run start:dev +# 或者直接使用 +npm start +``` + +--- + +## 📝 启动方式 + +| 命令 | 环境文件 | Mock 状态 | 用途 | +|------|---------|----------|------| +| `npm run start:mock` | `.env.mock` | ✅ 启用 | 本地开发，使用 Mock 数据 | +| `npm run start:dev` | `.env.development` | ❌ 禁用 | 连接真实后端 API | +| `npm start` | `.env` | ❌ 禁用 | 默认启动（连接后端） | + +--- + +## ⚙️ 环境配置 + +### `.env.mock` - Mock 测试环境 + +```env +# 启用 Mock 数据 +REACT_APP_ENABLE_MOCK=true + +# Mock 模式下不需要真实的后端地址 +REACT_APP_API_URL=http://localhost:3000 + +# Mock 环境标识 +REACT_APP_ENV=mock +``` + +### `.env.development` - 开发环境 + +```env +# 禁用 Mock 数据 +REACT_APP_ENABLE_MOCK=false + +# 真实的后端 API 地址 +REACT_APP_API_URL=http://49.232.185.254:5001 + +# 开发环境标识 +REACT_APP_ENV=development +``` + +### 如何切换环境？ + +只需修改 `.env` 文件中的 `REACT_APP_ENABLE_MOCK` 参数： + +```env +# 启用 Mock +REACT_APP_ENABLE_MOCK=true + +# 禁用 Mock，使用真实 API +REACT_APP_ENABLE_MOCK=false +``` + +--- + +## 📦 Mock 数据说明 + +### 已实现的 Mock API + +#### 1. **认证相关 API** + +| API | 方法 | Mock 说明 | +|-----|------|----------| +| `/api/auth/send-verification-code` | POST | 发送验证码（控制台会打印验证码） | +| `/api/auth/login-with-code` | POST | 验证码登录（自动设置当前登录用户） | +| `/api/auth/wechat/qrcode` | GET | 获取微信二维码（10秒后自动模拟扫码） | +| `/api/auth/wechat/check-status` | POST | 检查微信扫码状态 | +| `/api/auth/wechat/login` | POST | 微信登录确认（自动设置当前登录用户） | +| `/api/auth/wechat/h5-auth-url` | POST | 获取微信 H5 授权链接 | +| `/api/auth/session` | GET | 检查 Session 状态（返回当前登录用户） | +| `/api/auth/check-session` | GET | 检查 Session 状态（旧端点，保留兼容） | +| `/api/auth/logout` | POST | 退出登录（清除当前登录用户） | + +**登录状态管理**： +- Mock 系统会跟踪当前登录的用户 +- 登录成功后，用户信息会保存到 Mock 状态中 +- `/api/auth/session` 会返回当前登录用户的真实信息 +- 退出登录会清除登录状态，下次检查 Session 返回未登录 + +#### 2. **账户管理 API** + +| API | 方法 | Mock 说明 | +|-----|------|----------| +| `/api/account/profile-completeness` | GET | 获取用户资料完整度（需要登录） | +| `/api/account/profile` | GET | 获取用户资料（需要登录） | +| `/api/account/profile` | PUT | 更新用户资料（需要登录） | +| `/api/subscription/info` | GET | 获取订阅信息（会员类型、状态、到期时间） | +| `/api/subscription/permissions` | GET | 获取订阅权限（各功能的访问权限） | + +**资料完整度说明**： +- 返回用户资料的完整度百分比（0-100%） +- 包含缺失项列表（密码、手机号、邮箱） +- 对微信登录用户，如果资料不完整会提示需要完善 +- Mock 模式会根据当前登录用户的真实信息计算完整度 + +**订阅信息说明**： +- 返回当前用户的会员类型（free/pro/max） +- 包含订阅状态（active/expired） +- 返回到期时间和剩余天数 +- 未登录用户默认返回 free 类型 + +### 测试账号 + +**手机号登录测试账号**： + +| 手机号 | 验证码 | 用户昵称 | 会员类型 | 状态 | 到期时间 | 剩余天数 | 功能权限 | +|--------|--------|---------|---------|------|---------|---------|----------| +| `13800138000` | 控制台查看 | 测试用户 | **Free**（免费） | ✅ 激活 | - | - | 基础功能 | +| `13900139000` | 控制台查看 | Pro会员 | **Pro** | ✅ 激活 | 2025-12-31 | 90天 | 高级功能（除传导链外） | +| `13700137000` | 控制台查看 | Max会员 | **Max** | ✅ 激活 | 2026-12-31 | 365天 | 🎉 全部功能 | +| `13600136000` | 控制台查看 | 过期会员 | Pro（已过期） | ❌ 过期 | 2024-01-01 | -300天 | 基础功能 | + +**会员权限对比**： + +| 功能 | Free | Pro | Max | +|------|------|-----|-----| +| 相关标的 | ❌ | ✅ | ✅ | +| 相关概念 | ❌ | ✅ | ✅ | +| 事件传导链 | ❌ | ❌ | ✅ | +| 历史事件对比 | 🔒 限制版 | ✅ 完整版 | ✅ 完整版 | +| 概念详情 | ❌ | ✅ | ✅ | +| 概念统计中心 | ❌ | ✅ | ✅ | +| 概念相关股票 | ❌ | ✅ | ✅ | +| 概念历史时间轴 | ❌ | ❌ | ✅ | +| 热门个股 | ❌ | ✅ | ✅ | + +**验证码说明**： +- 发送验证码后，控制台会打印验证码 +- 示例：`[Mock] 验证码已生成: 13800138000 -> 123456` +- 验证码有效期：5分钟 +- 所有测试账号都可以使用相同的验证码登录 + +**微信登录测试**： +1. 点击"获取二维码" +2. 等待 10 秒，自动模拟用户扫码 +3. 再等待 5 秒，自动模拟用户确认 +4. 登录成功 + +--- + +## 🛠️ 如何添加新的 Mock API + +### 步骤 1：创建新的 Handler 文件 + +在 `src/mocks/handlers/` 目录下创建新文件，例如 `user.js`： + +```javascript +// src/mocks/handlers/user.js +import { http, HttpResponse, delay } from 'msw'; + +const NETWORK_DELAY = 500; + +export const userHandlers = [ + // 获取用户信息 + http.get('/api/user/profile', async () => { + await delay(NETWORK_DELAY); + + return HttpResponse.json({ + success: true, + data: { + id: 1, + nickname: '测试用户', + email: 'test@example.com', + avatar_url: 'https://i.pravatar.cc/150?img=1' + } + }); + }), + + // 更新用户信息 + http.put('/api/user/profile', async ({ request }) => { + await delay(NETWORK_DELAY); + + const body = await request.json(); + + return HttpResponse.json({ + success: true, + message: '更新成功', + data: body + }); + }) +]; +``` + +### 步骤 2：注册 Handler + +在 `src/mocks/handlers/index.js` 中导入并注册： + +```javascript +// src/mocks/handlers/index.js +import { authHandlers } from './auth'; +import { userHandlers } from './user'; // 导入新的 handler + +export const handlers = [ + ...authHandlers, + ...userHandlers, // 注册新的 handler +]; +``` + +### 步骤 3：重启应用 + +```bash +# 停止当前服务（Ctrl+C） +# 重新启动 +npm run start:mock +``` + +--- + +## 🐛 调试技巧 + +### 1. 查看 Mock 日志 + +所有 Mock API 请求都会在浏览器控制台打印日志： + +``` +[Mock] 发送验证码: {credential: "13800138000", type: "phone", purpose: "login"} +[Mock] 验证码已生成: 13800138000 -> 654321 +[Mock] 登录成功: {id: 1, phone: "13800138000", nickname: "测试用户", ...} +``` + +### 2. 检查 MSW 是否启动 + +打开浏览器控制台，查找以下消息： + +``` +[MSW] Mock Service Worker 已启动 🎭 +``` + +如果没有看到此消息，检查： +1. `.env.mock` 文件中 `REACT_APP_ENABLE_MOCK=true` +2. 是否使用 `npm run start:mock` 启动 + +### 3. 网络面板调试 + +打开浏览器开发者工具 → Network 标签页： +- Mock 的请求会显示 `(from ServiceWorker)` 标签 +- 可以查看请求和响应的详细信息 + +### 4. 模拟网络延迟 + +在 `src/mocks/handlers/*.js` 文件中修改延迟时间： + +```javascript +const NETWORK_DELAY = 2000; // 改为 2 秒 +``` + +### 5. 模拟错误响应 + +```javascript +http.post('/api/some-endpoint', async () => { + await delay(NETWORK_DELAY); + + // 返回 400 错误 + return HttpResponse.json({ + success: false, + error: '参数错误' + }, { status: 400 }); +}); +``` + +--- + +## ❓ 常见问题 + +### Q1: Mock 没有生效，请求仍然发送到真实服务器 + +**解决方案**： +1. 检查 `.env.mock` 文件中 `REACT_APP_ENABLE_MOCK=true` +2. 确保使用 `npm run start:mock` 启动 +3. 清除浏览器缓存并刷新页面 +4. 检查控制台是否有 MSW 启动消息 + +### Q2: 控制台显示 `[MSW] 启动失败` + +**解决方案**： +1. 确保 `public/mockServiceWorker.js` 文件存在 +2. 重新初始化 MSW： + ```bash + npx msw init public/ --save + ``` +3. 重启开发服务器 + +### Q3: 如何禁用某个特定 API 的 Mock？ + +在 `src/mocks/handlers/index.js` 中注释掉相应的 handler： + +```javascript +export const handlers = [ + ...authHandlers, + // ...userHandlers, // 禁用 user 相关的 Mock +]; +``` + +### Q4: 验证码是什么？ + +发送验证码后，控制台会打印验证码： + +``` +[Mock] 验证码已生成: 13800138000 -> 123456 +``` + +复制 `123456` 并填入验证码输入框即可。 + +### Q5: 微信登录如何测试？ + +1. 点击"获取二维码" +2. 等待 10 秒（自动模拟扫码） +3. 再等待 5 秒（自动模拟确认） +4. 自动完成登录 + +或者在控制台查看 Mock 日志： +``` +[Mock] 生成微信二维码: {sessionId: "wx_abc123", ...} +[Mock] 模拟用户扫码: wx_abc123 +[Mock] 模拟用户确认登录: wx_abc123 +``` + +### Q6: 生产环境会使用 Mock 数据吗？ + +**不会**。Mock 只在以下情况启用： +1. `NODE_ENV === 'development'`（开发环境） +2. `REACT_APP_ENABLE_MOCK === 'true'` + +生产环境 (`npm run build`) 会自动排除 MSW 代码。 + +--- + +## 📁 项目结构 + +``` +src/ +├── mocks/ +│ ├── handlers/ +│ │ ├── auth.js # 认证相关 Mock +│ │ ├── index.js # Handler 总入口 +│ │ └── ... # 其他 Handler 文件 +│ ├── data/ +│ │ └── users.js # Mock 用户数据 +│ └── browser.js # MSW 浏览器 Worker +├── index.js # 应用入口（集成 MSW） +└── ... + +public/ +└── mockServiceWorker.js # MSW Service Worker 文件 +``` + +--- + +## 📚 相关资源 + +- [MSW 官方文档](https://mswjs.io/) +- [MSW 快速开始](https://mswjs.io/docs/getting-started) +- [MSW API 参考](https://mswjs.io/docs/api) + +--- + +## 🎯 最佳实践 + +1. **使用真实的响应结构**：Mock 数据应与真实 API 返回的数据结构一致 +2. **添加网络延迟**：模拟真实的网络请求延迟，测试加载状态 +3. **测试边界情况**：创建错误响应的 Mock，测试错误处理逻辑 +4. **保持 Mock 数据更新**：当真实 API 变化时，及时更新 Mock handlers +5. **团队协作**：将 Mock 配置提交到 Git，团队成员共享 + +--- + +**提示**：如有任何问题或建议，请联系开发团队。Happy Mocking! 🎭 diff --git a/docs/NOTIFICATION_OPTIMIZATION_SUMMARY.md b/docs/NOTIFICATION_OPTIMIZATION_SUMMARY.md new file mode 100644 index 00000000..2317a8a3 --- /dev/null +++ b/docs/NOTIFICATION_OPTIMIZATION_SUMMARY.md @@ -0,0 +1,280 @@ +# 消息推送系统优化总结 + +## 优化目标 +1. 简化通知信息密度，通过视觉层次（边框+背景色）表达优先级 +2. 增强紧急通知的视觉冲击力（红色脉冲边框动画） +3. 采用智能显示策略，降低普通通知的视觉干扰 + +## 实施内容 + +### 1. 优先级配置更新 (src/constants/notificationTypes.js) + +#### 新增配置项 +- `borderWidth`: 边框宽度 + - 紧急 (urgent): 6px + - 重要 (important): 4px + - 普通 (normal): 2px + +- `bgOpacity`: 背景色透明度（亮色模式） + - 紧急: 0.25 (深色背景) + - 重要: 0.15 (中色背景) + - 普通: 0.08 (浅色背景) + +- `darkBgOpacity`: 背景色透明度（暗色模式） + - 紧急: 0.30 + - 重要: 0.20 + - 普通: 0.12 + +#### 新增辅助函数 +- `getPriorityBgOpacity(priority, isDark)`: 获取优先级对应的背景色透明度 +- `getPriorityBorderWidth(priority)`: 获取优先级对应的边框宽度 + +### 2. 紧急通知脉冲动画 (src/components/NotificationContainer/index.js) + +#### 动画效果 +- 使用 `@emotion/react` 的 `keyframes` 创建脉冲动画 +- 仅紧急通知 (urgent) 应用动画效果 +- 动画特性： + - 边框颜色脉冲效果 + - 阴影扩散效果（0 → 12px） + - 持续时间：2秒 + - 缓动函数：ease-in-out + - 无限循环 + +```javascript +const pulseAnimation = keyframes` + 0%, 100% { + border-left-color: currentColor; + box-shadow: 0 0 0 0 currentColor; + } + 50% { + border-left-color: currentColor; + box-shadow: -4px 0 12px 0 currentColor; + } +`; +``` + +### 3. 背景色优先级优化 + +#### 亮色模式 +- **紧急通知**：`${colorScheme}.200` - 深色背景 + 脉冲动画 +- **重要通知**：`${colorScheme}.100` - 中色背景 +- **普通通知**：`white` - 极淡背景（降低视觉干扰） + +#### 暗色模式 +- **紧急通知**：`${colorScheme}.800` 或 typeConfig.darkBg +- **重要通知**：`${colorScheme}.800` 或 typeConfig.darkBg +- **普通通知**：`gray.800` - 暗灰背景（降低视觉干扰） + +### 4. 可点击性视觉提示 + +#### 问题 +- 用户需要 hover 才能知道通知是否可点击 +- cursor: pointer 不够直观 + +#### 解决方案 +- **可点击的通知**： + - 添加完整边框（四周 1px solid） + - 保持左侧优先级边框宽度 + - 使用更明显的阴影（md 级别） + - 产生微妙的悬浮感 + +- **不可点击的通知**： + - 仅左侧边框 + - 使用较淡的阴影（sm 级别） + +```javascript +// 可点击的通知添加完整边框 +{...(isActuallyClickable && { + border: '1px solid', + borderLeftWidth: priorityBorderWidth, // 保持优先级 +})} + +// 可点击的通知使用更明显的阴影 +boxShadow={isActuallyClickable + ? (isNewest ? '2xl' : 'md') + : (isNewest ? 'xl' : 'sm')} +``` + +### 5. 通知组件简化 (src/components/NotificationContainer/index.js) + +#### 显示元素分级 + +**LV1 - 必需元素（始终显示）** +- ✅ 标题 (title) +- ✅ 内容 (content, 最多3行) +- ✅ 时间 (publishTime/pushTime) +- ✅ 查看详情 (仅当 clickable=true 时) +- ✅ 关闭按钮 + +**LV2 - 可选元素（数据存在时显示）** +- ✅ 图标：仅在紧急/重要通知时显示 +- ❌ 优先级标签：已移除，改用边框+背景色表示 +- ✅ 状态提示：仅当 `extra?.statusHint` 存在时显示 + +**LV3 - 可选元素（数据存在时显示）** +- ✅ AI 标识：仅当 `isAIGenerated = true` 时显示 +- ✅ 预测标识：仅当 `isPrediction = true` 时显示 + +**其他** +- ✅ 作者信息：移除屏幕尺寸限制，仅当 `author` 存在时显示 + +#### 优先级视觉样式 +- ✅ 边框宽度：根据优先级动态调整 (2px/4px/6px) +- ✅ 背景色深度：根据优先级使用不同深度的颜色 + - 亮色模式: .50 (普通) / .100 (重要) / .200 (紧急) + - 暗色模式: 使用 typeConfig 的 darkBg 配置 + +#### 布局优化 +- ✅ 内容和元数据区域的左侧填充根据图标显示状态自适应 +- ✅ 无图标时不添加额外的左侧间距 + +## 预期效果 + +### 视觉改进 +- **清晰度提升**：移除冗余的优先级标签，视觉更整洁 +- **优先级强化**： + - 紧急通知：6px 粗边框 + 深色背景 + **红色脉冲动画** → 视觉冲击力极强 + - 重要通知：4px 中等边框 + 中色背景 + 图标 → 醒目但不打扰 + - 普通通知：2px 细边框 + 白色/极淡背景 → 低视觉干扰 +- **可点击性一目了然**： + - 可点击：完整边框 + 明显阴影 → 卡片悬浮感 + - 不可点击：仅左侧边框 + 淡阴影 → 平面感 +- **信息密度降低**：减少不必要的视觉元素，关键信息更突出 + +### 用户体验 +- **紧急通知引起注意**：脉冲动画确保用户不会错过紧急信息 +- **快速识别优先级**： + - 动画 = 紧急（需要立即关注） + - 图标 + 粗边框 = 重要（需要关注） + - 细边框 + 淡背景 = 普通（可稍后查看） +- **可点击性无需 hover**： + - 完整边框 + 悬浮感 = 可以点击查看详情 + - 仅左侧边框 = 信息已完整，无需跳转 +- **智能显示**：可选信息只在数据存在时显示，避免空白占位 +- **响应式优化**：所有设备上保持一致的显示逻辑 + +### 向后兼容 +- ✅ 完全兼容现有通知数据结构 +- ✅ 可选字段不存在时自动隐藏 +- ✅ 不影响现有功能（点击、关闭、自动消失等） + +## 测试建议 + +### 1. 功能测试 +```bash +# 启动开发服务器 +npm start + +# 观察不同优先级通知的显示效果 +# - 紧急通知：粗边框 (6px) + 深色背景 + 红色脉冲动画 + 图标 + 不自动关闭 +# - 重要通知：中等边框 (4px) + 中色背景 + 图标 + 30秒后关闭 +# - 普通通知：细边框 (2px) + 白色背景 + 无图标 + 15秒后关闭 +``` + +### 1.1 动画测试 +- [ ] 紧急通知的脉冲动画流畅无卡顿 +- [ ] 动画周期为 2 秒 +- [ ] 动画在紧急通知显示期间持续循环 +- [ ] 阴影扩散效果清晰可见 + +### 2. 边界测试 +- [ ] 仅必需字段的通知（无作者、无 AI 标识、无预测标识） +- [ ] 包含所有可选字段的通知 +- [ ] 不同类型的通知（公告、股票、事件、分析报告） +- [ ] 不同优先级的通知（紧急、重要、普通） + +### 3. 响应式测试 +- [ ] 移动设备 (< 480px) +- [ ] 平板设备 (480px - 768px) +- [ ] 桌面设备 (> 768px) + +### 4. 暗色模式测试 +- [ ] 切换到暗色模式，确认背景色对比度合适 + +## 技术细节 + +### 关键代码变更 + +#### 1. 脉冲动画实现 +```javascript +// 导入 keyframes +import { keyframes } from '@emotion/react'; + +// 定义脉冲动画 +const pulseAnimation = keyframes` + 0%, 100% { + border-left-color: currentColor; + box-shadow: 0 0 0 0 currentColor; + } + 50% { + border-left-color: currentColor; + box-shadow: -4px 0 12px 0 currentColor; + } +`; + +// 应用到紧急通知 +
+
+ );
+}
+```
+
+### 消息格式（v2.0.0）
+
+```javascript
+{
+ // 必填字段
+ type: 'announcement' | 'stock_alert' | 'event_alert' | 'analysis_report',
+ priority: 'urgent' | 'important' | 'normal',
+ title: '通知标题',
+ content: '详细消息内容',
+
+ // 时间字段
+ publishTime: 1711611000000, // 发布时间（毫秒时间戳）
+ pushTime: Date.now(), // 推送时间（毫秒时间戳）
+
+ // 元数据
+ isAIGenerated: false, // 是否 AI 生成（显示 AI 徽章）
+ clickable: true, // 是否可点击
+ link: '/event-detail/ann001', // 点击跳转链接
+
+ // 作者信息（仅 analysis_report 需要）
+ author: {
+ name: '李明',
+ organization: '中信证券',
+ },
+
+ // 额外信息（自定义，根据类型不同）
+ extra: {
+ // announcement
+ announcementType: '财报',
+ companyCode: '600519',
+
+ // stock_alert
+ stockCode: '300750',
+ priceChange: '+5.2%', // 💡 重要：涨跌判断依据
+ currentPrice: '245.50',
+
+ // event_alert
+ eventId: 'evt001',
+ relatedStocks: 12,
+ impactLevel: '重大利好',
+
+ // analysis_report
+ reportType: '行业研报',
+ industry: '医药',
+ rating: '强烈推荐',
+
+ // 🆕 预测通知专用字段
+ isPrediction: true, // 是否为预测通知（显示"预测"徽章）
+ statusHint: '详细报告生成中...', // 状态提示文字（可选）
+ relatedPredictionId: 'pred_001', // 关联预测ID（用于追溯，可选）
+ },
+
+ // 自动关闭
+ autoClose: 10000, // 毫秒，0 或 false 表示不自动关闭
+
+ // 自动生成字段（无需手动设置）
+ id: 'unique_id', // 自动生成
+ timestamp: Date.now(), // 自动生成
+}
+```
+
+---
+
+## 🔧 配置说明
+
+### Mock 服务配置
+
+在 `src/services/mockSocketService.js` 中可以配置：
+
+```javascript
+// 修改模拟数据（14 条金融资讯）
+const mockFinancialNews = [
+ // 3 条公告通知
+ {
+ type: NOTIFICATION_TYPES.ANNOUNCEMENT,
+ priority: PRIORITY_LEVELS.IMPORTANT,
+ title: '贵州茅台发布2024年度财报公告',
+ content: '2024年度营收同比增长15.2%，净利润创历史新高...',
+ // ...
+ },
+
+ // 3 条股票动向
+ {
+ type: NOTIFICATION_TYPES.STOCK_ALERT,
+ priority: PRIORITY_LEVELS.URGENT,
+ title: '您关注的股票触发预警',
+ content: '宁德时代(300750) 当前价格 ¥245.50，涨幅 +5.2%...',
+ extra: {
+ priceChange: '+5.2%', // 红色（涨）
+ },
+ // ...
+ },
+
+ // 3 条事件动向
+ {
+ type: NOTIFICATION_TYPES.EVENT_ALERT,
+ priority: PRIORITY_LEVELS.IMPORTANT,
+ title: '央行宣布降准0.5个百分点',
+ // ...
+ },
+
+ // 4 条分析报告（2 条人工 + 2 条 AI）
+ {
+ type: NOTIFICATION_TYPES.ANALYSIS_REPORT,
+ priority: PRIORITY_LEVELS.IMPORTANT,
+ author: {
+ name: '李明',
+ organization: '中信证券',
+ },
+ isAIGenerated: false,
+ // ...
+ },
+ {
+ type: NOTIFICATION_TYPES.ANALYSIS_REPORT,
+ author: {
+ name: 'AI分析师',
+ organization: '价值前沿',
+ },
+ isAIGenerated: true, // AI 徽章
+ // ...
+ },
+];
+
+// 调整推送频率
+socket.startMockPush(15000, 1); // 每15秒推送1条
+```
+
+### 通知类型常量配置
+
+在 `src/constants/notificationTypes.js` 中可以修改：
+
+```javascript
+// 修改类型配色
+export const NOTIFICATION_TYPE_CONFIGS = {
+ [NOTIFICATION_TYPES.ANNOUNCEMENT]: {
+ name: '公告通知',
+ icon: MdCampaign,
+ colorScheme: 'blue', // 修改颜色主题
+ bg: 'blue.50',
+ borderColor: 'blue.400',
+ iconColor: 'blue.500',
+ hoverBg: 'blue.100',
+ },
+ // ...
+};
+
+// 修改优先级标签
+export const PRIORITY_CONFIGS = {
+ [PRIORITY_LEVELS.URGENT]: {
+ label: '紧急',
+ colorScheme: 'red',
+ show: true,
+ },
+ // ...
+};
+```
+
+### NotificationContext 配置
+
+在 `src/contexts/NotificationContext.js` 中：
+
+```javascript
+// 修改最大消息数量（默认 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` 中：
+
+```javascript
+// 调整通知宽度（默认 400px）
+连接状态: {isConnected ? '已连接' : '未连接'}
+ + + + + + +{article.title}
;
+}
+```
+
+### 2. 用户识别（登录时）
+
+在 `AuthContext` 或登录成功回调中：
+
+```jsx
+import { usePostHogRedux } from 'hooks/usePostHogRedux';
+
+function AuthContext() {
+ const { identify, reset } = usePostHogRedux();
+
+ const handleLoginSuccess = (user) => {
+ // 识别用户
+ identify(user.id, {
+ email: user.email,
+ username: user.username,
+ subscription_tier: user.subscription_type || 'free',
+ registration_date: user.created_at,
+ });
+ };
+
+ const handleLogout = () => {
+ // 重置用户会话
+ reset();
+ };
+
+ return { handleLoginSuccess, handleLogout };
+}
+```
+
+### 3. Feature Flags（A/B 测试）
+
+```jsx
+import { usePostHogFlags } from 'hooks/usePostHogRedux';
+
+function Dashboard() {
+ const { isEnabled } = usePostHogFlags();
+
+ if (isEnabled('new_dashboard_design')) {
+ return {JSON.stringify(posthog, null, 2)}
+ );
+}
+```
+
+### 3. 控制台日志
+
+开发环境下会自动输出日志：
+
+```
+[PostHog Middleware] 自动追踪事件: User Logged In { user_id: 123 }
+[PostHog] 📍 Event tracked: News Article Clicked
+```
+
+---
+
+## 📊 State 结构
+
+```javascript
+{
+ posthog: {
+ // 初始化状态
+ isInitialized: true,
+ initError: null,
+
+ // 用户信息
+ user: {
+ userId: "123",
+ email: "user@example.com",
+ subscription_tier: "pro"
+ },
+
+ // 事件队列（离线缓存）
+ eventQueue: [
+ { eventName: "...", properties: {...}, timestamp: "..." }
+ ],
+
+ // Feature Flags
+ featureFlags: {
+ new_dashboard_design: true,
+ beta_feature: false
+ },
+
+ // 配置
+ config: {
+ apiKey: "phc_...",
+ apiHost: "https://app.posthog.com",
+ sessionRecording: false
+ },
+
+ // 统计
+ stats: {
+ totalEvents: 150,
+ lastEventTime: "2025-10-28T12:00:00Z"
+ }
+ }
+}
+```
+
+---
+
+## 🚀 高级功能
+
+### 1. 手动触发页面浏览
+
+```jsx
+import { trackModalView, trackTabChange } from 'store/middleware/posthogMiddleware';
+
+// Modal 打开时
+dispatch(trackModalView('User Settings Modal', { source: 'nav_bar' }));
+
+// Tab 切换时
+dispatch(trackTabChange('Related Stocks', { from_tab: 'Overview' }));
+```
+
+### 2. 刷新离线事件
+
+```jsx
+import { flushCachedEvents } from 'store/slices/posthogSlice';
+
+// 网络恢复时自动触发，也可以手动触发
+dispatch(flushCachedEvents());
+```
+
+### 3. 性能追踪
+
+给 action 添加时间戳：
+
+```jsx
+import { withTiming } from 'store/middleware/posthogMiddleware';
+
+// 追踪耗时操作
+dispatch(withTiming(fetchBigData()));
+// → 如果超过 1 秒，会自动追踪性能事件
+```
+
+---
+
+## ⚠️ 注意事项
+
+### 1. **环境变量**
+
+确保 `.env` 文件中配置了 PostHog API Key：
+
+```bash
+REACT_APP_POSTHOG_KEY=phc_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
+REACT_APP_POSTHOG_HOST=https://app.posthog.com
+REACT_APP_ENABLE_SESSION_RECORDING=false
+```
+
+### 2. **Redux Middleware 顺序**
+
+PostHog Middleware 应该在其他 middleware 之后：
+
+```javascript
+.concat(otherMiddleware)
+.concat(posthogMiddleware) // ✅ 最后添加
+```
+
+### 3. **避免循环依赖**
+
+不要在 Middleware 中 dispatch 会触发 Middleware 的 action。
+
+### 4. **序列化检查**
+
+已经在 store 配置中忽略了 PostHog actions 的序列化检查。
+
+---
+
+## 🔄 从旧版本迁移
+
+如果你的代码中使用了旧的 `usePostHog` Hook：
+
+```jsx
+// 旧代码
+import { usePostHog } from 'hooks/usePostHog';
+const { track } = usePostHog();
+
+// 新代码（推荐）
+import { usePostHogRedux } from 'hooks/usePostHogRedux';
+const { track } = usePostHogRedux();
+```
+
+**兼容性**: 旧的 `usePostHog` Hook 仍然可用，但推荐迁移到 Redux 版本。
+
+---
+
+## 📚 参考资料
+
+- [PostHog 官方文档](https://posthog.com/docs)
+- [Redux Toolkit 文档](https://redux-toolkit.js.org/)
+- [Redux Middleware 文档](https://redux.js.org/tutorials/fundamentals/part-4-store#middleware)
+- [AARRR 框架](https://www.productplan.com/glossary/aarrr-framework/)
+
+---
+
+## 🎉 总结
+
+PostHog 已成功集成到 Redux！主要优势：
+
+1. ✅ **自动追踪**: Middleware 自动拦截 actions
+2. ✅ **集中管理**: 统一的 Redux 状态管理
+3. ✅ **调试友好**: Redux DevTools 支持
+4. ✅ **离线支持**: 自动缓存和刷新事件
+5. ✅ **性能优化**: 提供多个轻量级 Hooks
+
+现在你可以：
+1. 启动应用：`npm start`
+2. 打开 Redux DevTools 查看 PostHog 状态
+3. 执行操作（登录、浏览页面、点击按钮）
+4. 观察自动追踪的事件
+
+Have fun tracking! 🚀
diff --git a/docs/POSTHOG_TESTING_GUIDE.md b/docs/POSTHOG_TESTING_GUIDE.md
new file mode 100644
index 00000000..500e2cb1
--- /dev/null
+++ b/docs/POSTHOG_TESTING_GUIDE.md
@@ -0,0 +1,476 @@
+# PostHog 本地上报能力测试指南
+
+本文档指导您完成 PostHog 事件追踪功能的完整测试。
+
+---
+
+## 📋 准备工作
+
+### 步骤 1：获取 PostHog API Key
+
+#### 1.1 登录 PostHog
+
+打开浏览器，访问：
+```
+https://app.posthog.com
+```
+
+使用您的账号登录。
+
+#### 1.2 创建测试项目（如果还没有）
+
+1. 点击页面左上角的项目切换器
+2. 点击 "+ Create Project"
+3. 填写项目信息：
+ - **Project name**: `vf_react_dev`（推荐）或自定义名称
+ - **Organization**: 选择您的组织
+4. 点击 "Create Project"
+
+#### 1.3 获取 API Key
+
+1. 进入项目设置：
+ - 点击左侧边栏底部的 **"Settings"** ⚙️
+ - 选择 **"Project"** 标签
+
+2. 找到 "Project API Key" 部分
+ - 您会看到一个以 `phc_` 开头的长字符串
+ - 例如：`phc_abcdefghijklmnopqrstuvwxyz1234567890`
+
+3. 复制 API Key
+ - 点击 API Key 右侧的复制按钮 📋
+ - 或手动选中并复制
+
+---
+
+## 🔧 配置本地环境
+
+### 步骤 2：配置 .env.local
+
+打开项目根目录的 `.env.local` 文件，找到以下行：
+
+```env
+REACT_APP_POSTHOG_KEY=
+```
+
+将您刚才复制的 API Key 粘贴进去：
+
+```env
+REACT_APP_POSTHOG_KEY=phc_your_actual_key_here
+```
+
+**完整示例：**
+```env
+# PostHog 配置（本地开发）
+REACT_APP_POSTHOG_KEY=phc_abcdefghijklmnopqrstuvwxyz1234567890
+REACT_APP_POSTHOG_HOST=https://app.posthog.com
+REACT_APP_ENABLE_SESSION_RECORDING=false
+```
+
+⚠️ **重要**：保存文件后必须重启应用才能生效！
+
+---
+
+## 🚀 启动应用
+
+### 步骤 3：重启开发服务器
+
+如果应用正在运行，先停止它：
+
+```bash
+# 方式 1：使用命令
+npm run kill-port
+
+# 方式 2：在终端按 Ctrl+C
+```
+
+然后重新启动：
+
+```bash
+npm start
+```
+
+### 步骤 4：验证初始化
+
+应用启动后，打开浏览器：
+
+```
+http://localhost:3000
+```
+
+**立即按 F12 打开浏览器控制台**，您应该看到以下日志：
+
+```javascript
+✅ PostHog initialized successfully
+📊 PostHog Analytics initialized
+👤 User identified: user_xxx (如果已登录)
+```
+
+✅ **如果看到以上日志，说明 PostHog 初始化成功！**
+
+---
+
+## 🧪 测试事件追踪
+
+### 测试 1：页面浏览事件
+
+#### 操作步骤：
+1. 访问首页：http://localhost:3000
+2. 导航到社区页面：点击导航栏 "社区"
+3. 导航到个股中心：点击导航栏 "个股中心"
+4. 导航到概念中心：点击导航栏 "概念中心"
+5. 导航到涨停分析：点击导航栏 "涨停分析"
+
+#### 期待结果：
+
+**控制台输出：**
+```javascript
+[PostHog] Event: $pageview
+ Properties: {
+ $current_url: "http://localhost:3000/community",
+ page_path: "/community",
+ page_type: "feature",
+ feature_name: "community"
+ }
+```
+
+**验证方法：**
+1. 打开 PostHog Dashboard
+2. 进入 **"Activity" → "Live Events"**
+3. 观察实时事件流（延迟 1-2 秒）
+4. 应该看到 `$pageview` 事件，每次页面切换一个
+
+---
+
+### 测试 2：社区页面交互事件
+
+#### 操作步骤：
+
+1. **搜索功能**
+ - 点击搜索框
+ - 输入 "科技"
+ - 按回车搜索
+
+2. **筛选功能**
+ - 点击 "筛选" 按钮
+ - 选择某个筛选条件
+ - 应用筛选
+
+3. **内容交互**
+ - 点击任意帖子卡片
+ - 点击用户头像
+
+#### 期待结果：
+
+**控制台输出：**
+```javascript
+📍 Event tracked: search_initiated
+ context: "community"
+
+📍 Event tracked: search_query_submitted
+ query: "科技"
+ category: "community"
+
+📍 Event tracked: filter_applied
+ filter_type: "category"
+ filter_value: "tech"
+
+📍 Event tracked: post_clicked
+ post_id: "123"
+ post_title: "标题"
+```
+
+**PostHog Live Events：**
+```
+🔴 search_initiated
+🔴 search_query_submitted
+🔴 filter_applied
+🔴 post_clicked
+```
+
+---
+
+### 测试 3：个股中心交互事件
+
+#### 操作步骤：
+
+1. **搜索股票**
+ - 进入个股中心页面
+ - 点击搜索框
+ - 输入股票名称或代码
+
+2. **概念交互**
+ - 点击某个概念板块
+ - 点击概念下的股票
+
+3. **热力图交互**
+ - 点击热力图中的股票方块
+ - 查看股票详情
+
+#### 期待结果：
+
+**控制台输出：**
+```javascript
+📍 Event tracked: stock_overview_page_viewed
+
+📍 Event tracked: stock_searched
+ query: "科技股"
+
+📍 Event tracked: concept_clicked
+ concept_name: "人工智能"
+
+📍 Event tracked: concept_stock_clicked
+ stock_code: "000001"
+ stock_name: "平安银行"
+```
+
+---
+
+### 测试 4：概念中心交互事件
+
+#### 操作步骤：
+
+1. **列表浏览**
+ - 进入概念中心
+ - 切换排序方式
+
+2. **时间线查看**
+ - 点击某个概念卡片
+ - 打开时间线 Modal
+ - 展开某个日期
+ - 点击新闻/报告
+
+#### 期待结果：
+
+**控制台输出：**
+```javascript
+📍 Event tracked: concept_list_viewed
+ sort_by: "change_percent_desc"
+
+📍 Event tracked: concept_clicked
+ concept_name: "芯片"
+
+📍 Event tracked: concept_detail_viewed
+ concept_name: "芯片"
+ view_type: "timeline_modal"
+
+📍 Event tracked: timeline_date_toggled
+ date: "2025-01-15"
+ action: "expand"
+```
+
+---
+
+### 测试 5：涨停分析交互事件
+
+#### 操作步骤：
+
+1. **日期选择**
+ - 进入涨停分析页面
+ - 选择不同日期
+
+2. **板块交互**
+ - 展开某个板块
+ - 点击板块名称
+
+3. **股票交互**
+ - 点击涨停股票
+ - 查看详情
+
+#### 期待结果：
+
+**控制台输出：**
+```javascript
+📍 Event tracked: limit_analyse_page_viewed
+
+📍 Event tracked: date_selected
+ date: "20250115"
+
+📍 Event tracked: sector_toggled
+ sector_name: "科技"
+ action: "expand"
+
+📍 Event tracked: limit_stock_clicked
+ stock_code: "000001"
+ stock_name: "平安银行"
+```
+
+---
+
+## 📊 验证上报结果
+
+### 在 PostHog Dashboard 验证
+
+#### 步骤 1：打开 Live Events
+
+1. 登录 PostHog Dashboard
+2. 选择您的测试项目
+3. 点击左侧菜单 **"Activity"**
+4. 选择 **"Live Events"**
+
+#### 步骤 2：观察实时事件流
+
+您应该看到实时的事件流，格式类似：
+
+```
+🔴 LIVE $pageview 1s ago
+ page_path: /community
+ user_id: anonymous_abc123
+
+🔴 LIVE search_initiated 2s ago
+ context: community
+
+🔴 LIVE search_query_submitted 3s ago
+ query: "科技"
+ category: "community"
+```
+
+#### 步骤 3：检查事件属性
+
+点击任意事件，展开详情，验证：
+- ✅ 事件名称正确
+- ✅ 所有属性完整
+- ✅ 时间戳准确
+- ✅ 用户信息正确
+
+---
+
+## 📋 测试清单
+
+使用以下清单记录测试结果：
+
+### 页面浏览事件（5项）
+
+- [ ] 首页浏览 - `$pageview`
+- [ ] 社区页面浏览 - `community_page_viewed`
+- [ ] 个股中心浏览 - `stock_overview_page_viewed`
+- [ ] 概念中心浏览 - `concept_page_viewed`
+- [ ] 涨停分析浏览 - `limit_analyse_page_viewed`
+
+### 社区页面事件（6项）
+
+- [ ] 搜索初始化 - `search_initiated`
+- [ ] 搜索查询提交 - `search_query_submitted`
+- [ ] 筛选器应用 - `filter_applied`
+- [ ] 帖子点击 - `post_clicked`
+- [ ] 评论点击 - `comment_clicked`
+- [ ] 用户资料查看 - `user_profile_viewed`
+
+### 个股中心事件（4项）
+
+- [ ] 股票搜索 - `stock_searched`
+- [ ] 概念点击 - `concept_clicked`
+- [ ] 概念股票点击 - `concept_stock_clicked`
+- [ ] 热力图股票点击 - `heatmap_stock_clicked`
+
+### 概念中心事件（5项）
+
+- [ ] 概念列表查看 - `concept_list_viewed`
+- [ ] 排序更改 - `sort_changed`
+- [ ] 概念点击 - `concept_clicked`
+- [ ] 概念详情查看 - `concept_detail_viewed`
+- [ ] 新闻/报告点击 - `news_clicked` / `report_clicked`
+
+### 涨停分析事件（6项）
+
+- [ ] 页面查看 - `limit_analyse_page_viewed`
+- [ ] 日期选择 - `date_selected`
+- [ ] 每日统计查看 - `daily_stats_viewed`
+- [ ] 板块展开/收起 - `sector_toggled`
+- [ ] 板块点击 - `sector_clicked`
+- [ ] 涨停股票点击 - `limit_stock_clicked`
+
+---
+
+## ⚠️ 常见问题
+
+### 问题 1：控制台没有看到 PostHog 日志
+
+**可能原因：**
+- API Key 配置错误
+- 应用没有重启
+- 浏览器控制台过滤了日志
+
+**解决方案：**
+1. 检查 `.env.local` 中的 API Key 是否正确
+2. 确保重启了应用：`npm run kill-port && npm start`
+3. 打开控制台，清除所有过滤器
+4. 刷新页面
+
+---
+
+### 问题 2：PostHog Live Events 没有数据
+
+**可能原因：**
+- 网络问题
+- API Key 错误
+- 项目选择错误
+
+**解决方案：**
+1. 打开浏览器网络面板（Network）
+2. 筛选 XHR 请求，查找 `posthog.com` 的请求
+3. 检查请求状态码：
+ - `200 OK` → 正常
+ - `401 Unauthorized` → API Key 错误
+ - `404 Not Found` → 项目不存在
+4. 确认 PostHog Dashboard 选择了正确的项目
+
+---
+
+### 问题 3：事件上报了，但属性不完整
+
+**可能原因：**
+- 代码中传递的参数不完整
+- 某些状态未正确初始化
+
+**解决方案：**
+1. 查看控制台的详细日志
+2. 对比 PostHog Live Events 中的数据
+3. 检查对应的事件追踪代码
+4. 提供反馈给开发团队
+
+---
+
+## 📸 测试截图建议
+
+为了完整记录测试结果，建议截图：
+
+1. **PostHog 初始化成功**
+ - 浏览器控制台初始化日志
+
+2. **Live Events 实时流**
+ - PostHog Dashboard Live Events 页面
+
+3. **典型事件详情**
+ - 展开某个事件，显示所有属性
+
+4. **事件统计**
+ - PostHog Insights 或 Trends 页面
+
+---
+
+## ✅ 测试完成后
+
+测试完成后，您可以：
+
+1. **保持配置**
+ - 保留 API Key 在 `.env.local` 中
+ - 继续使用控制台 + PostHog Cloud 双模式
+
+2. **切换回仅控制台模式**
+ - 清空 `.env.local` 中的 `REACT_APP_POSTHOG_KEY`
+ - 重启应用
+ - 仅在控制台查看事件（不上报）
+
+3. **配置生产环境**
+ - 创建生产环境的 PostHog 项目
+ - 将生产 API Key 填入 `.env` 文件
+ - 部署时使用生产配置
+
+---
+
+**祝测试顺利！** 🎉
+
+如有任何问题，请查阅：
+- [PostHog 官方文档](https://posthog.com/docs)
+- [ENVIRONMENT_SETUP.md](./ENVIRONMENT_SETUP.md)
+- [POSTHOG_INTEGRATION.md](./POSTHOG_INTEGRATION.md)
diff --git a/docs/POSTHOG_TRACKING_GUIDE.md b/docs/POSTHOG_TRACKING_GUIDE.md
new file mode 100644
index 00000000..4dfd0d14
--- /dev/null
+++ b/docs/POSTHOG_TRACKING_GUIDE.md
@@ -0,0 +1,561 @@
+# PostHog 事件追踪开发者指南
+
+## 📚 目录
+
+1. [快速开始](#快速开始)
+2. [Hook使用指南](#hook使用指南)
+3. [添加新的追踪Hook](#添加新的追踪hook)
+4. [集成追踪到组件](#集成追踪到组件)
+5. [最佳实践](#最佳实践)
+6. [常见问题](#常见问题)
+
+---
+
+## 🚀 快速开始
+
+### 当前已有的追踪Hooks
+
+| Hook名称 | 用途 | 适用场景 |
+|---------|------|---------|
+| `useAuthEvents` | 认证事件 | 注册、登录、登出、微信授权 |
+| `useStockOverviewEvents` | 个股分析 | 个股页面浏览、图表查看、指标分析 |
+| `useConceptEvents` | 概念追踪 | 概念浏览、搜索、相关股票查看 |
+| `useCompanyEvents` | 公司分析 | 公司详情、财务数据、行业对比 |
+| `useLimitAnalyseEvents` | 涨停分析 | 涨停榜单、筛选、个股详情 |
+| `useCommunityEvents` | 社区事件 | 新闻浏览、事件追踪、评论互动 |
+| `useEventDetailEvents` | 事件详情 | 事件分析、时间线、影响评估 |
+| `useDashboardEvents` | 仪表板 | 自选股、关注事件、评论管理 |
+| `useTradingSimulationEvents` | 模拟盘 | 下单、持仓、收益追踪 |
+| `useSearchEvents` | 搜索行为 | 搜索查询、结果点击、筛选 |
+| `useNavigationEvents` | 导航交互 | 菜单点击、主题切换、Logo点击 |
+| `useProfileEvents` | 个人资料 | 资料更新、密码修改、账号绑定 |
+| `useSubscriptionEvents` | 订阅支付 | 定价选择、支付流程、订阅管理 |
+
+---
+
+## 📖 Hook使用指南
+
+### 1. 基础用法
+
+```javascript
+// 第一步：导入Hook
+import { useSearchEvents } from '../../hooks/useSearchEvents';
+
+// 第二步：在组件中初始化
+function SearchComponent() {
+ const searchEvents = useSearchEvents({ context: 'global' });
+
+ // 第三步：在事件处理函数中调用追踪方法
+ const handleSearch = (query) => {
+ searchEvents.trackSearchQuerySubmitted(query, resultCount);
+ // ... 执行搜索逻辑
+ };
+}
+```
+
+### 2. 带参数的Hook初始化
+
+大多数Hook支持配置参数，用于区分不同的使用场景：
+
+```javascript
+// 搜索Hook - 指定搜索上下文
+const searchEvents = useSearchEvents({
+ context: 'community' // 或 'stock', 'news', 'concept'
+});
+
+// 个人资料Hook - 指定页面类型
+const profileEvents = useProfileEvents({
+ pageType: 'settings' // 或 'profile', 'security'
+});
+
+// 导航Hook - 指定组件位置
+const navEvents = useNavigationEvents({
+ component: 'top_nav' // 或 'sidebar', 'footer'
+});
+
+// 订阅Hook - 传入当前订阅信息
+const subscriptionEvents = useSubscriptionEvents({
+ currentSubscription: {
+ plan: user?.subscription_plan || 'free',
+ status: user?.subscription_status || 'none'
+ }
+});
+```
+
+### 3. 常见追踪模式
+
+#### 模式A：简单事件追踪
+```javascript
+// 点击事件
+
+```
+
+#### 模式B：成功/失败双向追踪
+```javascript
+const handleSave = async () => {
+ try {
+ await saveData();
+ profileEvents.trackProfileUpdated(updatedFields, data);
+ toast({ title: "保存成功" });
+ } catch (error) {
+ profileEvents.trackProfileUpdateFailed(attemptedFields, error.message);
+ toast({ title: "保存失败" });
+ }
+};
+```
+
+#### 模式C：条件追踪
+```javascript
+const handleSearch = (query, resultCount) => {
+ // 只在有查询词时追踪
+ if (query) {
+ searchEvents.trackSearchQuerySubmitted(query, resultCount);
+ }
+
+ // 无结果时自动触发额外追踪
+ if (resultCount === 0) {
+ // Hook内部已自动追踪 SEARCH_NO_RESULTS
+ }
+};
+```
+
+---
+
+## 🔨 添加新的追踪Hook
+
+### 步骤1：创建Hook文件
+
+在 `/src/hooks/` 目录下创建新文件，例如 `useYourFeatureEvents.js`：
+
+```javascript
+// src/hooks/useYourFeatureEvents.js
+import { useCallback } from 'react';
+import { usePostHogTrack } from './usePostHogRedux';
+import { RETENTION_EVENTS } from '../lib/constants';
+import { logger } from '../utils/logger';
+
+/**
+ * 你的功能事件追踪 Hook
+ * @param {Object} options - 配置选项
+ * @param {string} options.context - 使用上下文
+ * @returns {Object} 事件追踪处理函数集合
+ */
+export const useYourFeatureEvents = ({ context = 'default' } = {}) => {
+ const { track } = usePostHogTrack();
+
+ /**
+ * 追踪功能操作
+ * @param {string} actionName - 操作名称
+ * @param {Object} details - 操作详情
+ */
+ const trackFeatureAction = useCallback((actionName, details = {}) => {
+ if (!actionName) {
+ logger.warn('useYourFeatureEvents', 'trackFeatureAction: actionName is required');
+ return;
+ }
+
+ track(RETENTION_EVENTS.FEATURE_USED, {
+ feature_name: 'your_feature',
+ action_name: actionName,
+ context,
+ ...details,
+ timestamp: new Date().toISOString(),
+ });
+
+ logger.debug('useYourFeatureEvents', '📊 Feature Action Tracked', {
+ actionName,
+ context,
+ });
+ }, [track, context]);
+
+ return {
+ trackFeatureAction,
+ // ... 更多追踪方法
+ };
+};
+
+export default useYourFeatureEvents;
+```
+
+### 步骤2：定义事件常量（如需要）
+
+在 `/src/lib/constants.js` 中添加新事件：
+
+```javascript
+export const RETENTION_EVENTS = {
+ // ... 现有事件
+ YOUR_FEATURE_VIEWED: 'Your Feature Viewed',
+ YOUR_FEATURE_ACTION: 'Your Feature Action',
+};
+```
+
+### 步骤3：在组件中集成
+
+```javascript
+import { useYourFeatureEvents } from '../../hooks/useYourFeatureEvents';
+
+function YourComponent() {
+ const featureEvents = useYourFeatureEvents({ context: 'main_page' });
+
+ const handleAction = () => {
+ featureEvents.trackFeatureAction('button_clicked', {
+ button_name: 'submit',
+ user_role: user?.role
+ });
+ };
+
+ return ;
+}
+```
+
+---
+
+## 🎯 集成追踪到组件
+
+### 完整集成示例
+
+```javascript
+// src/views/YourFeature/YourComponent.js
+import React, { useState, useEffect } from 'react';
+import { useYourFeatureEvents } from '../../hooks/useYourFeatureEvents';
+
+export default function YourComponent() {
+ const [data, setData] = useState([]);
+
+ // 🎯 初始化追踪Hook
+ const featureEvents = useYourFeatureEvents({
+ context: 'your_feature'
+ });
+
+ // 🎯 页面加载时自动追踪
+ useEffect(() => {
+ featureEvents.trackPageViewed();
+ }, [featureEvents]);
+
+ // 🎯 用户操作追踪
+ const handleItemClick = (item) => {
+ featureEvents.trackItemClicked(item.id, item.name);
+ // ... 业务逻辑
+ };
+
+ // 🎯 表单提交追踪（成功/失败）
+ const handleSubmit = async (formData) => {
+ try {
+ const result = await submitData(formData);
+ featureEvents.trackSubmitSuccess(formData, result);
+ toast({ title: '提交成功' });
+ } catch (error) {
+ featureEvents.trackSubmitFailed(formData, error.message);
+ toast({ title: '提交失败' });
+ }
+ };
+
+ return (
+
+ {data.map(item => (
+
+ );
+}
+```
+
+---
+
+## ✅ 最佳实践
+
+### 1. 命名规范
+
+#### Hook命名
+- 使用 `use` 前缀：`useFeatureEvents`
+- 描述性名称：`useSubscriptionEvents` 而非 `useSubEvents`
+
+#### 追踪方法命名
+- 使用 `track` 前缀：`trackButtonClicked`
+- 动词+名词结构：`trackSearchSubmitted`, `trackProfileUpdated`
+- 明确动作：`trackPaymentSuccessful` 而非 `trackPayment`
+
+#### 事件常量命名
+- 大写+下划线：`SEARCH_QUERY_SUBMITTED`
+- 名词+动词结构：`PROFILE_UPDATED`, `PAYMENT_INITIATED`
+
+### 2. 参数设计
+
+#### 必填参数前置
+```javascript
+// ✅ 好的设计
+trackSearchSubmitted(query, resultCount, filters)
+
+// ❌ 不好的设计
+trackSearchSubmitted(filters, resultCount, query)
+```
+
+#### 使用对象参数处理复杂数据
+```javascript
+// ✅ 好的设计
+trackPaymentInitiated({
+ planName: 'pro',
+ amount: 99,
+ currency: 'CNY',
+ paymentMethod: 'wechat_pay'
+})
+
+// ❌ 不好的设计
+trackPaymentInitiated(planName, amount, currency, paymentMethod)
+```
+
+#### 提供默认值
+```javascript
+const trackAction = useCallback((name, details = {}) => {
+ track(EVENT_NAME, {
+ action_name: name,
+ context: context || 'default',
+ timestamp: new Date().toISOString(),
+ ...details
+ });
+}, [track, context]);
+```
+
+### 3. 错误处理
+
+#### 参数验证
+```javascript
+const trackFeature = useCallback((featureName) => {
+ if (!featureName) {
+ logger.warn('useFeatureEvents', 'trackFeature: featureName is required');
+ return;
+ }
+
+ track(EVENTS.FEATURE_USED, { feature_name: featureName });
+}, [track]);
+```
+
+#### 避免追踪崩溃影响业务
+```javascript
+const handleAction = async () => {
+ try {
+ // 业务逻辑
+ const result = await doSomething();
+
+ // 追踪放在业务逻辑之后，不影响核心功能
+ try {
+ featureEvents.trackActionSuccess(result);
+ } catch (trackError) {
+ logger.error('Tracking failed', trackError);
+ // 不抛出错误，不影响用户体验
+ }
+ } catch (error) {
+ // 业务逻辑错误处理
+ toast({ title: '操作失败' });
+ }
+};
+```
+
+### 4. 性能优化
+
+#### 使用 useCallback 包装追踪函数
+```javascript
+const trackAction = useCallback((actionName) => {
+ track(EVENTS.ACTION, { action_name: actionName });
+}, [track]);
+```
+
+#### 避免在循环中追踪
+```javascript
+// ❌ 不好的做法
+items.forEach(item => {
+ trackItemViewed(item.id);
+});
+
+// ✅ 好的做法
+trackItemsViewed(items.length, items.map(i => i.id));
+```
+
+#### 批量追踪
+```javascript
+// 一次追踪包含所有信息
+trackBatchAction({
+ action_type: 'bulk_delete',
+ item_count: selectedItems.length,
+ item_ids: selectedItems.map(i => i.id)
+});
+```
+
+### 5. 调试支持
+
+#### 使用 logger.debug
+```javascript
+const trackAction = useCallback((actionName) => {
+ track(EVENTS.ACTION, { action_name: actionName });
+
+ logger.debug('useFeatureEvents', '📊 Action Tracked', {
+ actionName,
+ context,
+ timestamp: new Date().toISOString()
+ });
+}, [track, context]);
+```
+
+#### 在开发环境显示追踪信息
+```javascript
+if (process.env.NODE_ENV === 'development') {
+ console.log('[PostHog Track]', eventName, properties);
+}
+```
+
+---
+
+## 🐛 常见问题
+
+### Q1: Hook 内的 useCallback 依赖项应该包含哪些？
+
+**A:** 只包含函数内部使用的外部变量：
+
+```javascript
+const trackAction = useCallback((name) => {
+ // ✅ track 和 context 被使用，需要在依赖项中
+ track(EVENTS.ACTION, {
+ name,
+ context
+ });
+}, [track, context]); // 正确的依赖项
+```
+
+### Q2: 何时使用自动追踪 vs 手动追踪？
+
+**A:**
+- **自动追踪**：页面浏览、组件挂载时的事件
+ ```javascript
+ useEffect(() => {
+ featureEvents.trackPageViewed();
+ }, [featureEvents]);
+ ```
+
+- **手动追踪**：用户主动操作的事件
+ ```javascript
+
+ );
+ }
+}
+```
+
+---
+
+## 6. 实时监控功能
+
+### 6.1 监控机制
+
+```javascript
+const [isMonitoring, setIsMonitoring] = useState(false);
+const monitoringIntervalRef = useRef(null);
+
+useEffect(() => {
+ // 清理旧定时器
+ if (monitoringIntervalRef.current) {
+ clearInterval(monitoringIntervalRef.current);
+ monitoringIntervalRef.current = null;
+ }
+
+ if (isMonitoring && relatedStocks.length > 0) {
+ // 定义更新函数
+ const updateQuotes = () => {
+ const codes = relatedStocks.map(s => s.stock_code);
+ stockService.getQuotes(codes, event?.created_at)
+ .then(quotes => setStockQuotes(quotes))
+ .catch(error => logger.error('...', error));
+ };
+
+ // 立即执行一次
+ updateQuotes();
+
+ // 设置定时器: 每 5 秒刷新
+ monitoringIntervalRef.current = setInterval(updateQuotes, 5000);
+ }
+
+ // 清理函数
+ return () => {
+ if (monitoringIntervalRef.current) {
+ clearInterval(monitoringIntervalRef.current);
+ monitoringIntervalRef.current = null;
+ }
+ };
+}, [isMonitoring, relatedStocks, event]);
+```
+
+### 6.2 监控控制
+
+```javascript
+const handleMonitoringToggle = () => {
+ setIsMonitoring(prev => !prev);
+};
+```
+
+**UI 表现**:
+```javascript
+
+ handleItemClick(item)}>
+ {item.name}
+
+ ))}
+
+ 每5秒自动更新行情数据
+```
+
+### 6.3 组件卸载清理
+
+```javascript
+useEffect(() => {
+ return () => {
+ // 组件卸载时清理定时器，防止内存泄漏
+ if (monitoringIntervalRef.current) {
+ clearInterval(monitoringIntervalRef.current);
+ }
+ };
+}, []);
+```
+
+---
+
+## 7. 搜索和过滤
+
+### 7.1 搜索状态
+
+```javascript
+const [searchText, setSearchText] = useState('');
+const [filteredStocks, setFilteredStocks] = useState([]);
+```
+
+### 7.2 过滤逻辑
+
+```javascript
+useEffect(() => {
+ if (!searchText.trim()) {
+ setFilteredStocks(relatedStocks); // 无搜索词，显示全部
+ } else {
+ const filtered = relatedStocks.filter(stock =>
+ stock.stock_code.toLowerCase().includes(searchText.toLowerCase()) ||
+ stock.stock_name.toLowerCase().includes(searchText.toLowerCase())
+ );
+ setFilteredStocks(filtered);
+ }
+}, [searchText, relatedStocks]);
+```
+
+**搜索特性**:
+- 不区分大小写
+- 同时匹配股票代码和股票名称
+- 实时过滤（每次输入都触发）
+
+### 7.3 搜索 UI
+
+```javascript
+ setSearchText(e.target.value)}
+ allowClear // 显示清除按钮
+/>
+```
+
+---
+
+## 8. UI 交互逻辑
+
+### 8.1 Tab 切换
+
+```javascript
+const [activeTab, setActiveTab] = useState('stocks');
+
+
+ handleUnfixChart(stock)}
+ stock={stock}
+ eventTime={formattedEventTime}
+ fixed={true}
+ />
+
+))}
+```
+
+**流程图**:
+```
+用户点击"浦发银行"行
+ ↓
+handleRowEvents.onClick 触发
+ ↓
+setFixedCharts((prev) => {
+ 检查是否已存在 600000.SH
+ ├─ 已存在 → 返回 prev（不重复添加）
+ └─ 不存在 → [...prev, {stock: 浦发银行, chartType: 'timeline'}]
+})
+ ↓
+组件重新渲染
+ ↓
+fixedCharts.map 渲染
+ ↓
+显示 StockChartAntdModal 弹窗
+ ├─ 显示股票详情
+ ├─ 显示 K 线图
+ └─ 提供关闭按钮
+```
+
+#### 重构后
+
+```javascript
+// 固定图表状态（相同）
+const [fixedCharts, setFixedCharts] = useState([]);
+
+// 行点击处理
+const handleRowClick = useCallback((stock) => {
+ setFixedCharts((prev) => {
+ if (prev.find(item => item.stock.stock_code === stock.stock_code)) {
+ return prev;
+ }
+ return [...prev, { stock, chartType: 'timeline' }];
+ });
+}, []);
+
+// StockTable 组件（内部处理 onRow）
+
+ handleUnfixChart(stock)}
+ stock={stock}
+ eventTime={formattedEventTime}
+ fixed={true}
+ />
+
+ ));
+}, [fixedCharts, event, handleUnfixChart]);
+```
+
+**流程图**:
+```
+用户点击"浦发银行"行
+ ↓
+StockTable 内部 onRow.onClick
+ ↓
+onRowClick(stock) 回调到父组件
+ ↓
+handleRowClick(浦发银行)
+ ↓
+setFixedCharts((prev) => {
+ 检查是否已存在 600000.SH
+ ├─ 已存在 → 返回 prev
+ └─ 不存在 → [...prev, {stock: 浦发银行, chartType: 'timeline'}]
+})
+ ↓
+组件重新渲染
+ ↓
+renderFixedCharts (useMemo 缓存)
+ ↓
+显示 StockChartAntdModal 弹窗
+```
+
+### 对比总结
+
+| 维度 | 重构前 | 重构后 | 改进 |
+|------|--------|--------|------|
+| **点击逻辑** | handleRowEvents | handleRowClick | ✅ 命名更清晰 |
+| **组件封装** | Table 内联 | StockTable 组件 | ✅ 可复用 |
+| **性能优化** | 无 | useMemo 缓存渲染 | ✅ 避免重复渲染 |
+| **重复检查** | ✅ 有 | ✅ 有 | 相同 |
+| **功能一致性** | ✅ | ✅ | 完全一致 |
+
+---
+
+## 6. 自选股操作流程
+
+### 场景：用户点击"加自选"按钮
+
+#### 重构前
+
+```javascript
+// 自选股状态
+const [watchlistStocks, setWatchlistStocks] = useState(new Set());
+
+// 加载自选股列表
+const loadWatchlist = useCallback(async () => {
+ const apiBase = getApiBase();
+ const response = await fetch(`${apiBase}/api/account/watchlist`, {
+ credentials: 'include'
+ });
+ const data = await response.json();
+ if (data.success) {
+ const watchlistSet = new Set(data.data.map(item => item.stock_code));
+ setWatchlistStocks(watchlistSet);
+ }
+}, []);
+
+// 切换自选股
+const handleWatchlistToggle = async (stockCode, isInWatchlist) => {
+ const apiBase = getApiBase();
+
+ if (isInWatchlist) {
+ // DELETE 请求
+ await fetch(`${apiBase}/api/account/watchlist/${stockCode}`, {
+ method: 'DELETE',
+ credentials: 'include'
+ });
+ } else {
+ // POST 请求
+ const stockInfo = relatedStocks.find(s => s.stock_code === stockCode);
+ await fetch(`${apiBase}/api/account/watchlist`, {
+ method: 'POST',
+ headers: { 'Content-Type': 'application/json' },
+ credentials: 'include',
+ body: JSON.stringify({
+ stock_code: stockCode,
+ stock_name: stockInfo?.stock_name
+ })
+ });
+ }
+
+ // 乐观更新
+ setWatchlistStocks(prev => {
+ const newSet = new Set(prev);
+ isInWatchlist ? newSet.delete(stockCode) : newSet.add(stockCode);
+ return newSet;
+ });
+
+ message.success(isInWatchlist ? '已从自选股移除' : '已加入自选股');
+};
+
+// UI 渲染
+ :
+
+ );
+};
+```
+
+**流程图**:
+```
+免费用户点击"传导链分析" Tab
+ ↓
+setActiveTab('chain')
+ ↓
+渲染 Tab 内容
+ ↓
+hasFeatureAccess('transmission_chain')
+ ↓
+检查用户订阅等级
+ ├─ Free → false
+ ├─ Pro → false
+ └─ Max → true
+ ↓
+返回 false (免费用户)
+ ↓
+渲染 renderLockedContent('transmission_chain', '传导链分析')
+ ↓
+getUpgradeRecommendation('transmission_chain')
+ ↓
+返回 {required: 'max', message: '此功能需要 Max 版订阅'}
+ ↓
+显示锁定 UI:
+ ├─ 👑 图标
+ ├─ "传导链分析功能已锁定"
+ ├─ "此功能需要 Max 版订阅"
+ └─ "升级到 Max版" 按钮
+ ↓
+用户点击"升级到 Max版"
+ ↓
+setUpgradeFeature('max')
+ ↓
+setUpgradeModalOpen(true)
+ ↓
+显示 SubscriptionUpgradeModal
+ ├─ 显示 Max 版特权
+ ├─ 显示价格信息
+ └─ 提供购买入口
+```
+
+#### 重构后
+
+```javascript
+// 权限 Hook (相同)
+const { hasFeatureAccess, getUpgradeRecommendation } = useSubscription();
+
+// 升级点击处理
+const handleUpgradeClick = useCallback((featureName) => {
+ const recommendation = getUpgradeRecommendation(featureName);
+ setUpgradeFeature(recommendation?.required || 'pro');
+ setUpgradeModalOpen(true);
+}, [getUpgradeRecommendation]);
+
+// 渲染锁定内容（提取为回调）
+const renderLockedContent = useCallback((featureName, description) => {
+ const recommendation = getUpgradeRecommendation(featureName);
+ const isProRequired = recommendation?.required === 'pro';
+
+ return (
+
+ {isProRequired ?
+
+
+ );
+};
+```
+
+**流程图**:
+```
+免费用户点击"传导链分析" Tab
+ ↓
+setActiveTab('chain')
+ ↓
+渲染 Tab 内容 (useMemo 缓存)
+ ↓
+hasFeatureAccess('transmission_chain')
+ ↓
+检查用户订阅等级
+ ├─ Free → false
+ ├─ Pro → false
+ └─ Max → true
+ ↓
+返回 false (免费用户)
+ ↓
+renderLockedContent('transmission_chain', '传导链分析')
+ ↓
+getUpgradeRecommendation('transmission_chain')
+ ↓
+返回 {required: 'max', message: '...'}
+ ↓
+渲染 LockedContent 组件
+ ├─ 接收 props: {description, isProRequired, message, onUpgradeClick}
+ ├─ 显示 👑 图标
+ ├─ 显示 Alert 提示
+ └─ 显示"升级到 Max版"按钮
+ ↓
+用户点击"升级到 Max版"
+ ↓
+onUpgradeClick() 回调
+ ↓
+handleUpgradeClick('transmission_chain')
+ ↓
+setUpgradeFeature('max')
+ ↓
+setUpgradeModalOpen(true)
+ ↓
+显示 SubscriptionUpgradeModal
+```
+
+### 对比总结
+
+| 维度 | 重构前 | 重构后 | 改进 |
+|------|--------|--------|------|
+| **权限检查** | hasFeatureAccess | hasFeatureAccess | ✅ 相同 |
+| **锁定 UI** | 内联渲染 | LockedContent 组件 | ✅ 可复用 |
+| **升级推荐** | getUpgradeRecommendation | getUpgradeRecommendation | ✅ 相同 |
+| **性能优化** | 无 | useMemo + useCallback | ✅ 避免重复渲染 |
+| **模态框触发** | ✅ | ✅ | 相同 |
+| **功能一致性** | ✅ | ✅ | 完全一致 |
+
+---
+
+## 9. 升级引导流程
+
+### 场景：用户点击"升级到 Max版"按钮
+
+#### 重构前
+
+```javascript
+// 升级状态
+const [upgradeModalOpen, setUpgradeModalOpen] = useState(false);
+const [upgradeFeature, setUpgradeFeature] = useState('');
+
+// LockedContent 中的升级按钮
+
+
+// 升级模态框
+
+ {isProRequired ?
+ ...
;
+}
+```
+
+---
+
+## 🎨 UI 集成示例
+
+### 1. Toast 通知（Chakra UI）
+
+```jsx
+import { useToast } from '@chakra-ui/react';
+
+const toast = useToast();
+
+// 在 onNewEvent 回调中
+onNewEvent: (event) => {
+ toast({
+ title: '新事件',
+ description: event.title,
+ status: 'info',
+ duration: 5000,
+ isClosable: true,
+ position: 'top-right',
+ });
+}
+```
+
+---
+
+### 2. 顶部通知栏
+
+```jsx
+import { Alert, AlertIcon, CloseButton } from '@chakra-ui/react';
+
+function EventNotificationBanner() {
+ const [showNotification, setShowNotification] = useState(false);
+ const [latestEvent, setLatestEvent] = useState(null);
+
+ useEventNotifications({
+ eventType: 'all',
+ onNewEvent: (event) => {
+ setLatestEvent(event);
+ setShowNotification(true);
+ }
+ });
+
+ if (!showNotification || !latestEvent) return null;
+
+ return (
+ ...
;
+}
+```
+
+---
+
+### 3. 防抖处理（避免通知过多）
+
+```jsx
+import { debounce } from 'lodash';
+
+const debouncedNotify = debounce((event) => {
+ toast({
+ title: '新事件',
+ description: event.title,
+ });
+}, 1000);
+
+useEventNotifications({
+ eventType: 'all',
+ onNewEvent: debouncedNotify
+});
+```
+
+---
+
+## 🧪 测试步骤
+
+1. **启动 Flask 服务**
+ ```bash
+ python app.py
+ ```
+
+2. **启动 React 应用**
+ ```bash
+ npm start
+ ```
+
+3. **创建测试事件**
+ ```bash
+ python test_create_event.py
+ ```
+
+4. **观察结果**
+ - 最多等待 30 秒
+ - 前端页面应该显示通知
+ - 控制台输出日志
+
+---
+
+## 🐛 常见问题
+
+### Q: 没有收到推送？
+**A:** 检查：
+1. Flask 服务是否启动
+2. 浏览器控制台是否有连接错误
+3. 后端日志是否显示 `[轮询] 发现 X 个新事件`
+
+### Q: 连接一直失败？
+**A:** 检查：
+1. API_BASE_URL 配置是否正确
+2. CORS 配置是否包含前端域名
+3. 防火墙/代理设置
+
+### Q: 收到重复通知？
+**A:** 检查是否多次调用了 Hook，确保只在需要的地方订阅一次。
+
+---
+
+## 📚 更多资源
+
+- Socket.IO 文档: https://socket.io/docs/v4/
+- Chakra UI Toast: https://chakra-ui.com/docs/components/toast
+- React Hooks: https://react.dev/reference/react
+
+---
+
+**完成！🎉** 现在你的前端可以实时接收事件推送了！
diff --git a/docs/final_trading_simulation_fixes.md b/docs/final_trading_simulation_fixes.md
new file mode 100644
index 00000000..d6dad2fa
--- /dev/null
+++ b/docs/final_trading_simulation_fixes.md
@@ -0,0 +1,146 @@
+# 模拟盘最终修复总结
+
+## 🎯 修复的问题
+
+### 1. ✅ 编译错误修复
+**问题**：`Card` 组件重复导入
+**解决**：
+- 移除了自定义 Card 组件的重复导入
+- 统一使用 Chakra UI 的 Card 组件
+- 保留必要的图表组件导入
+
+### 2. ✅ 版面布局重新设计
+**改进**：
+- **主要功能放在上面**：交易面板、持仓、历史、融资融券
+- **统计数据放在下面**：账户概览、资产走势等分析图表
+- **现代化标签页**：使用 emoji 图标和圆角设计
+
+### 3. ✅ 真实数据替换Mock数据
+**改进**：
+- **资产走势图**：使用真实的 `getAssetHistory` 数据
+- **空数据处理**：当没有历史数据时显示友好提示
+- **动态显示**：只在有数据时显示图表
+
+### 4. ✅ 价格显示修复
+**问题**：搜索股票时价格显示为 0.00
+**解决**：
+- **后端修复**：`search_stocks` 接口现在返回 `current_price`
+- **前端修复**：正确使用 `stock.current_price` 而不是硬编码0
+- **价格获取优化**：扩大查询范围，多重备选方案
+
+## 🚀 新的页面结构
+
+### 上半部分：主要功能
+```
+┌─────────────────────────────────────────┐
+│ 💹 交易面板 | 📊 我的持仓 | 📋 交易历史 | 💰 融资融券 │
+├─────────────────────────────────────────┤
+│ │
+│ 主要交易功能区域 │
+│ │
+└─────────────────────────────────────────┘
+```
+
+### 下半部分：统计分析
+```
+┌─────────────────────────────────────────┐
+│ 📊 账户统计分析 │
+│ ┌─────────────┐ ┌─────────────────┐ │
+│ │ 资产卡片 │ │ 资产配置图 │ │
+│ └─────────────┘ └─────────────────┘ │
+└─────────────────────────────────────────┘
+┌─────────────────────────────────────────┐
+│ 📈 资产走势分析 │
+│ （有数据时显示图表） │
+│ （无数据时显示友好提示） │
+└─────────────────────────────────────────┘
+```
+
+## 🔧 关键代码修改
+
+### 1. 价格数据修复
+**后端** (`app_2.py`):
+```python
+# search_stocks 接口现在返回价格
+stocks.append({
+ 'stock_code': row.stock_code,
+ 'stock_name': row.stock_name,
+ 'current_price': current_price or 0, # 添加真实价格
+ # ... 其他字段
+})
+```
+
+**前端** (`TradingPanel.js`):
+```javascript
+// 使用真实价格而不是0
+price: stock.current_price || 0, // 使用后端返回的真实价格
+```
+
+### 2. 真实数据处理
+**主页面** (`index.js`):
+```javascript
+// 获取真实资产历史
+const [assetHistory, setAssetHistory] = useState([]);
+const { getAssetHistory } = useTradingAccount();
+
+useEffect(() => {
+ if (account) {
+ getAssetHistory(30).then(data => {
+ setAssetHistory(data || []);
+ });
+ }
+}, [account, getAssetHistory]);
+
+// 只在有数据时显示图表
+{hasAssetData && (
+