docs: 将所有文档迁移到 docs/ 目录

- 移动42个文档文件到 docs/ 目录 - 更新 .gitignore 允许 docs/ 下的 .md 文件 - 删除根目录下的重复文档文件 📁 文档分类： - StockDetailPanel 重构文档（3个） - PostHog 集成文档（6个） - 系统架构和API文档（33个） 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <noreply@anthropic.com>
2025-10-30 14:51:22 +08:00
parent 3a5c1b9d9c
commit 09db05c448
43 changed files with 23850 additions and 0 deletions
--- a/docs/TRACKING_VALIDATION_CHECKLIST.md
+++ b/docs/TRACKING_VALIDATION_CHECKLIST.md
@@ -0,0 +1,484 @@
+# PostHog 事件追踪验证清单
+
+## 📋 验证目的
+
+本清单用于验证所有PostHog事件追踪是否正常工作。建议在以下场景使用：
+- ✅ 开发环境集成后的验证
+- ✅ 上线前的最终检查
+- ✅ 定期追踪健康度检查
+- ✅ 新功能上线后的验证
+
+---
+
+## 🔧 验证准备
+
+### 1. 环境检查
+- [ ] PostHog已正确配置（检查.env文件）
+- [ ] PostHog控制台可以访问
+- [ ] 开发者工具Network面板可以看到PostHog请求
+- [ ] 浏览器Console没有PostHog相关错误
+
+### 2. 验证工具
+- [ ] 打开浏览器开发者工具（F12）
+- [ ] 切换到Network标签
+- [ ] 过滤器设置为：`posthog` 或 `api/events`
+- [ ] 打开Console标签查看logger.debug输出
+
+### 3. PostHog控制台
+- [ ] 登录 https://app.posthog.com
+- [ ] 进入项目
+- [ ] 打开 "Live events" 视图
+- [ ] 准备监控实时事件
+
+---
+
+## ✅ 功能模块验证
+
+### 🔐 认证模块（useAuthEvents）
+
+#### 注册流程
+- [ ] 打开注册页面
+- [ ] 填写手机号和密码
+- [ ] 点击注册按钮
+- [ ] **验证事件**: `USER_SIGNED_UP`
+  - 检查属性：`signup_method`, `user_id`
+
+#### 登录流程
+- [ ] 打开登录页面
+- [ ] 使用密码登录
+- [ ] **验证事件**: `USER_LOGGED_IN`
+  - 检查属性：`login_method: 'password'`
+- [ ] 退出登录
+- [ ] 使用微信登录
+- [ ] **验证事件**: `USER_LOGGED_IN`
+  - 检查属性：`login_method: 'wechat'`
+
+#### 登出
+- [ ] 点击退出登录
+- [ ] **验证事件**: `USER_LOGGED_OUT`
+
+---
+
+### 🏠 社区模块（useCommunityEvents）
+
+#### 页面浏览
+- [ ] 访问社区页面 `/community`
+- [ ] **验证事件**: `Community Page Viewed`
+- [ ] **验证事件**: `News List Viewed`
+  - 检查属性：`total_count`, `sort_by`, `importance_filter`
+
+#### 新闻点击
+- [ ] 点击任一新闻事件
+- [ ] **验证事件**: `NEWS_ARTICLE_CLICKED`
+  - 检查属性：`event_id`, `event_title`, `importance`
+
+#### 搜索功能
+- [ ] 在搜索框输入关键词
+- [ ] 点击搜索
+- [ ] **验证事件**: `SEARCH_QUERY_SUBMITTED`
+  - 检查属性：`query`, `result_count`, `context: 'community'`
+
+#### 筛选功能
+- [ ] 切换重要性筛选
+- [ ] **验证事件**: `SEARCH_FILTER_APPLIED`
+  - 检查属性：`filter_type: 'importance'`
+- [ ] 切换排序方式
+- [ ] **验证事件**: `SEARCH_FILTER_APPLIED`
+  - 检查属性：`filter_type: 'sort'`
+
+---
+
+### 📰 事件详情模块（useEventDetailEvents）
+
+#### 页面浏览
+- [ ] 点击任一事件进入详情页
+- [ ] **验证事件**: `EVENT_DETAIL_VIEWED`
+  - 检查属性：`event_id`, `event_title`, `importance`
+
+#### 分析查看
+- [ ] 页面加载完成后
+- [ ] **验证事件**: `EVENT_ANALYSIS_VIEWED`
+  - 检查属性：`analysis_type`, `related_stock_count`
+
+#### 标签切换
+- [ ] 点击"相关股票"标签
+- [ ] **验证事件**: `NEWS_TAB_CLICKED`
+  - 检查属性：`tab_name: 'related_stocks'`
+
+#### 相关股票点击
+- [ ] 点击任一相关股票
+- [ ] **验证事件**: `STOCK_CLICKED`
+  - 检查属性：`stock_code`, `source: 'event_detail_related_stocks'`
+
+#### 社交互动
+- [ ] 点击评论点赞按钮
+- [ ] **验证事件**: `Comment Liked` 或 `Comment Unliked`
+  - 检查属性：`comment_id`, `event_id`, `action`
+- [ ] 输入评论内容
+- [ ] 点击发表评论
+- [ ] **验证事件**: `Comment Added`
+  - 检查属性：`comment_id`, `event_id`, `content_length`
+- [ ] 删除自己的评论（如果有）
+- [ ] **验证事件**: `Comment Deleted`
+  - 检查属性：`comment_id`
+
+---
+
+### 📊 仪表板模块（useDashboardEvents）
+
+#### 页面浏览
+- [ ] 访问个人中心 `/dashboard/center`
+- [ ] **验证事件**: `DASHBOARD_CENTER_VIEWED`
+  - 检查属性：`page_type: 'center'`
+
+#### 自选股
+- [ ] 查看自选股列表
+- [ ] **验证事件**: `Watchlist Viewed`
+  - 检查属性：`stock_count`, `has_stocks`
+
+#### 关注的事件
+- [ ] 查看关注的事件列表
+- [ ] **验证事件**: `Following Events Viewed`
+  - 检查属性：`event_count`
+
+#### 评论管理
+- [ ] 查看我的评论
+- [ ] **验证事件**: `Comments Viewed`
+  - 检查属性：`comment_count`
+
+---
+
+### 💹 模拟盘模块（useTradingSimulationEvents）
+
+#### 进入模拟盘
+- [ ] 访问模拟盘页面 `/trading-simulation`
+- [ ] **验证事件**: `TRADING_SIMULATION_ENTERED`
+  - 检查属性：`total_value`, `available_cash`, `holdings_count`
+
+#### 搜索股票
+- [ ] 在搜索框输入股票代码/名称
+- [ ] **验证事件**: `Simulation Stock Searched`
+  - 检查属性：`query`
+
+#### 下单操作
+- [ ] 选择一只股票
+- [ ] 输入数量和价格
+- [ ] 点击买入/卖出
+- [ ] **验证事件**: `Simulation Order Placed`
+  - 检查属性：`stock_code`, `order_type`, `quantity`, `price`
+
+#### 持仓查看
+- [ ] 切换到持仓标签
+- [ ] **验证事件**: `Simulation Holdings Viewed`
+  - 检查属性：`holdings_count`, `total_value`
+
+---
+
+### 🔍 搜索模块（useSearchEvents）
+
+#### 搜索发起
+- [ ] 点击搜索框获得焦点
+- [ ] **验证事件**: `SEARCH_INITIATED`
+  - 检查属性：`context: 'community'`
+
+#### 搜索提交
+- [ ] 输入搜索词
+- [ ] 按回车或点击搜索
+- [ ] **验证事件**: `SEARCH_QUERY_SUBMITTED`
+  - 检查属性：`query`, `result_count`, `has_results`
+
+#### 无结果追踪
+- [ ] 搜索一个不存在的词
+- [ ] **验证事件**: `SEARCH_NO_RESULTS`
+  - 检查属性：`query`, `context`
+
+---
+
+### 🧭 导航模块（useNavigationEvents）
+
+#### Logo点击
+- [ ] 点击页面左上角Logo
+- [ ] **验证事件**: `Logo Clicked`
+  - 检查属性：`component: 'main_navbar'`
+
+#### 主题切换
+- [ ] 点击主题切换按钮
+- [ ] **验证事件**: `Theme Changed`
+  - 检查属性：`from_theme`, `to_theme`
+
+#### 顶部导航
+- [ ] 点击"高频跟踪"下拉菜单
+- [ ] 点击"事件中心"
+- [ ] **验证事件**: `MENU_ITEM_CLICKED`
+  - 检查属性：`item_name: '事件中心'`, `menu_type: 'dropdown'`
+
+#### 二级导航
+- [ ] 在二级导航栏点击任一菜单
+- [ ] **验证事件**: `SIDEBAR_MENU_CLICKED`
+  - 检查属性：`item_name`, `path`, `level: 2`
+
+---
+
+### 👤 个人资料模块（useProfileEvents）
+
+#### 个人资料页面
+- [ ] 访问个人资料页 `/profile`
+- [ ] 点击编辑按钮
+- [ ] **验证事件**: `Profile Field Edit Started`
+
+#### 更新资料
+- [ ] 修改昵称或其他信息
+- [ ] 点击保存
+- [ ] **验证事件**: `PROFILE_UPDATED`
+  - 检查属性：`updated_fields`, `field_count`
+
+#### 上传头像
+- [ ] 点击头像上传
+- [ ] 选择图片
+- [ ] **验证事件**: `Avatar Uploaded`
+  - 检查属性：`upload_method`, `file_size`
+
+#### 设置页面
+- [ ] 访问设置页 `/settings`
+- [ ] 点击修改密码
+- [ ] 输入当前密码和新密码
+- [ ] 提交
+- [ ] **验证事件**: `Password Changed`
+  - 检查属性：`success: true`
+
+#### 通知设置
+- [ ] 切换通知开关
+- [ ] 点击保存
+- [ ] **验证事件**: `Notification Preferences Changed`
+  - 检查属性：`email_enabled`, `push_enabled`, `sms_enabled`
+
+#### 账号绑定
+- [ ] 输入邮箱地址
+- [ ] 获取验证码
+- [ ] 输入验证码绑定
+- [ ] **验证事件**: `Account Bound`
+  - 检查属性：`account_type: 'email'`, `success: true`
+
+---
+
+### 💳 订阅支付模块（useSubscriptionEvents）
+
+#### 订阅页面查看
+- [ ] 打开订阅管理页面
+- [ ] **验证事件**: `SUBSCRIPTION_PAGE_VIEWED`
+  - 检查属性：`current_plan`, `subscription_status`
+
+#### 定价方案查看
+- [ ] 浏览不同的定价方案
+- [ ] **验证事件**: `Pricing Plan Viewed`
+  - 检查属性：`plan_name`, `price`
+
+#### 选择方案
+- [ ] 选择月付/年付
+- [ ] 点击"立即订阅"
+- [ ] **验证事件**: `Pricing Plan Selected`
+  - 检查属性：`plan_name`, `billing_cycle`, `price`
+
+#### 查看支付页面
+- [ ] 进入支付页面
+- [ ] **验证事件**: `PAYMENT_PAGE_VIEWED`
+  - 检查属性：`plan_name`, `amount`
+
+#### 支付流程
+- [ ] 选择支付方式（微信支付）
+- [ ] **验证事件**: `PAYMENT_METHOD_SELECTED`
+  - 检查属性：`payment_method: 'wechat_pay'`
+- [ ] 点击创建订单
+- [ ] **验证事件**: `PAYMENT_INITIATED`
+  - 检查属性：`plan_name`, `amount`, `payment_method`
+
+#### 支付成功（需要完成支付）
+- [ ] 完成微信支付
+- [ ] **验证事件**: `PAYMENT_SUCCESSFUL`
+  - 检查属性：`order_id`, `transaction_id`
+- [ ] **验证事件**: `SUBSCRIPTION_CREATED`
+  - 检查属性：`plan`, `billing_cycle`, `start_date`
+
+---
+
+## 🎯 关键漏斗验证
+
+### 注册激活漏斗
+1. [ ] `PAGE_VIEWED` (注册页)
+2. [ ] `USER_SIGNED_UP`
+3. [ ] `USER_LOGGED_IN`
+4. [ ] `PROFILE_UPDATED` (完善资料)
+
+### 内容消费漏斗
+1. [ ] `Community Page Viewed`
+2. [ ] `News List Viewed`
+3. [ ] `NEWS_ARTICLE_CLICKED`
+4. [ ] `EVENT_DETAIL_VIEWED`
+5. [ ] `Comment Added` (深度互动)
+
+### 付费转化漏斗
+1. [ ] `PAYWALL_SHOWN` (触发付费墙)
+2. [ ] `SUBSCRIPTION_PAGE_VIEWED`
+3. [ ] `Pricing Plan Selected`
+4. [ ] `PAYMENT_INITIATED`
+5. [ ] `PAYMENT_SUCCESSFUL`
+6. [ ] `SUBSCRIPTION_CREATED`
+
+### 模拟盘转化漏斗
+1. [ ] `TRADING_SIMULATION_ENTERED`
+2. [ ] `Simulation Stock Searched`
+3. [ ] `Simulation Order Placed`
+4. [ ] `Simulation Holdings Viewed`
+
+---
+
+## 🐛 错误场景验证
+
+### 失败追踪验证
+- [ ] 密码修改失败
+  - **验证事件**: `Password Changed` (success: false)
+- [ ] 支付失败
+  - **验证事件**: `PAYMENT_FAILED`
+  - 检查属性：`error_reason`
+- [ ] 个人资料更新失败
+  - **验证事件**: `Profile Update Failed`
+  - 检查属性：`attempted_fields`, `error_message`
+
+---
+
+## 📊 PostHog控制台验证
+
+### 实时事件检查
+- [ ] 登录PostHog控制台
+- [ ] 进入 "Live events" 页面
+- [ ] 执行上述操作
+- [ ] 确认每个操作都有对应事件出现
+- [ ] 检查事件属性完整性
+
+### 用户属性检查
+- [ ] 进入 "Persons" 页面
+- [ ] 找到测试用户
+- [ ] 验证用户属性：
+  - [ ] `user_id`
+  - [ ] `email` (如果有)
+  - [ ] `subscription_tier`
+  - [ ] `role`
+
+### 事件属性检查
+对于每个验证的事件，确认以下属性存在：
+- [ ] `timestamp` - 时间戳
+- [ ] 事件特定属性（如 event_id, stock_code 等）
+- [ ] 上下文属性（如 context, page_type 等）
+
+---
+
+## 🔍 开发者工具验证
+
+### Network 面板
+- [ ] 找到 PostHog API 请求
+- [ ] 检查请求URL: `https://app.posthog.com/e/`
+- [ ] 检查请求Method: POST
+- [ ] 检查Response Status: 200
+- [ ] 检查Request Payload包含事件数据
+
+### Console 面板
+- [ ] 查找 logger.debug 输出
+- [ ] 格式如：`[useFeatureEvents] 📊 Action Tracked`
+- [ ] 验证输出的事件名称和参数正确
+
+---
+
+## ✅ 验证通过标准
+
+### 单个事件验证通过
+- ✅ Network面板能看到PostHog请求
+- ✅ Console能看到logger.debug输出
+- ✅ PostHog Live events能看到事件
+- ✅ 事件名称正确
+- ✅ 事件属性完整且准确
+
+### 整体验证通过
+- ✅ 所有核心功能模块至少验证了主要流程
+- ✅ 关键漏斗的每一步都能追踪到
+- ✅ 成功和失败场景都有追踪
+- ✅ 没有JavaScript错误
+- ✅ 所有事件在PostHog控制台可见
+
+---
+
+## 📝 验证记录
+
+### 验证信息
+- **验证日期**: _______________
+- **验证人员**: _______________
+- **验证环境**: [ ] 开发环境 [ ] 测试环境 [ ] 生产环境
+- **PostHog项目**: _______________
+
+### 验证结果
+- **总验证项**: _____
+- **通过项**: _____
+- **失败项**: _____
+- **通过率**: _____%
+
+### 发现的问题
+| 问题描述 | 严重程度 | 状态 | 备注 |
+|---------|---------|------|------|
+| | | | |
+| | | | |
+
+### 验证结论
+- [ ] ✅ 全部通过，可以上线
+- [ ] ⚠️ 有轻微问题，可以上线但需修复
+- [ ] ❌ 有严重问题，需要修复后重新验证
+
+---
+
+## 🔧 常见问题排查
+
+### 问题1: 看不到PostHog请求
+**可能原因**:
+- PostHog未正确初始化
+- API Key配置错误
+- 网络被拦截
+
+**排查步骤**:
+1. 检查 `.env` 文件中的 `REACT_APP_POSTHOG_KEY`
+2. 检查浏览器Console是否有错误
+3. 检查网络代理设置
+
+### 问题2: 事件属性缺失
+**可能原因**:
+- 传参时属性名拼写错误
+- 某些数据为undefined
+- Hook未正确初始化
+
+**排查步骤**:
+1. 查看Console的logger.debug输出
+2. 检查Hook初始化时传入的参数
+3. 检查调用追踪方法时的参数
+
+### 问题3: 事件未在PostHog显示
+**可能原因**:
+- 数据同步延迟（通常<1分钟）
+- PostHog项目选择错误
+- 事件被过滤
+
+**排查步骤**:
+1. 等待1-2分钟后刷新
+2. 确认选择了正确的项目
+3. 检查PostHog的事件过滤器设置
+
+---
+
+## 📚 相关资源
+
+- [PostHog 官方文档](https://posthog.com/docs)
+- [POSTHOG_TRACKING_GUIDE.md](./POSTHOG_TRACKING_GUIDE.md) - 开发者指南
+- [POSTHOG_INTEGRATION.md](./POSTHOG_INTEGRATION.md) - 集成说明
+- [constants.js](./src/lib/constants.js) - 事件常量定义
+
+---
+
+**文档版本**: v1.0
+**最后更新**: 2025-10-29
+**维护者**: 开发团队