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>
This commit is contained in:
zdl
476
docs/POSTHOG_TESTING_GUIDE.md
Normal file
476
docs/POSTHOG_TESTING_GUIDE.md
Normal file
@@ -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)
|
||||
Reference in New Issue
Block a user