# 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)