vf_react/docs/POSTHOG_TESTING_GUIDE.md

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 文件，找到以下行：

REACT_APP_POSTHOG_KEY=

将您刚才复制的 API Key 粘贴进去：

REACT_APP_POSTHOG_KEY=phc_your_actual_key_here

完整示例：

# PostHog 配置（本地开发）
REACT_APP_POSTHOG_KEY=phc_abcdefghijklmnopqrstuvwxyz1234567890
REACT_APP_POSTHOG_HOST=https://app.posthog.com
REACT_APP_ENABLE_SESSION_RECORDING=false

⚠️ 重要：保存文件后必须重启应用才能生效！

---

🚀 启动应用

步骤 3：重启开发服务器

如果应用正在运行，先停止它：

# 方式 1：使用命令
npm run kill-port

# 方式 2：在终端按 Ctrl+C

然后重新启动：

npm start

步骤 4：验证初始化

应用启动后，打开浏览器：

http://localhost:3000

立即按 F12 打开浏览器控制台，您应该看到以下日志：

✅ PostHog initialized successfully
📊 PostHog Analytics initialized
👤 User identified: user_xxx (如果已登录)

✅ 如果看到以上日志，说明 PostHog 初始化成功！

---

🧪 测试事件追踪

测试 1：页面浏览事件

操作步骤：

1. 访问首页：http://localhost:3000
2. 导航到社区页面：点击导航栏 "社区"
3. 导航到个股中心：点击导航栏 "个股中心"
4. 导航到概念中心：点击导航栏 "概念中心"
5. 导航到涨停分析：点击导航栏 "涨停分析"

期待结果：

控制台输出：

[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. 内容交互

   • 点击任意帖子卡片
   • 点击用户头像

期待结果：

控制台输出：

📍 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. 热力图交互

   • 点击热力图中的股票方块
   • 查看股票详情

期待结果：

控制台输出：

📍 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
   • 展开某个日期
   • 点击新闻/报告

期待结果：

控制台输出：

📍 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. 股票交互

   • 点击涨停股票
   • 查看详情

期待结果：

控制台输出：

📍 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 官方文档
• ENVIRONMENT_SETUP.md
• POSTHOG_INTEGRATION.md