# 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
// 点击事件
<Button onClick={() => {
  navEvents.trackMenuItemClicked('概念中心', 'dropdown', '/concepts');
  navigate('/concepts');
}}>
  概念中心
</Button>
```

#### 模式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 <Button onClick={handleAction}>Submit</Button>;
}
```

---

## 🎯 集成追踪到组件

### 完整集成示例

```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 (
    <div>
      {data.map(item => (
        <div key={item.id} onClick={() => handleItemClick(item)}>
          {item.name}
        </div>
      ))}
      <form onSubmit={handleSubmit}>
        {/* 表单内容 */}
      </form>
    </div>
  );
}
```

---

## ✅ 最佳实践

### 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
  <Button onClick={() => {
    featureEvents.trackButtonClicked();
    handleAction();
  }}>
  ```

### Q3: 如何追踪异步操作的完整流程？

**A:** 分别追踪开始、成功、失败：

```javascript
const handleAsyncAction = async () => {
  // 1. 追踪开始
  featureEvents.trackActionStarted();

  try {
    const result = await doAsyncWork();

    // 2. 追踪成功
    featureEvents.trackActionSuccess(result);
  } catch (error) {
    // 3. 追踪失败
    featureEvents.trackActionFailed(error.message);
  }
};
```

### Q4: 追踪中应该包含哪些用户信息？

**A:**
- ✅ **可以包含**：用户ID、角色、订阅状态、使用偏好
- ❌ **不应包含**：密码、完整邮箱、手机号、支付信息

```javascript
// ✅ 正确
track(EVENT, {
  user_id: user.id,
  user_role: user.role,
  subscription_tier: user.subscription_tier
});

// ❌ 错误
track(EVENT, {
  password: user.password,  // 绝对不要追踪密码
  email: user.email,        // 避免完整邮箱
  credit_card: '****1234'   // 不追踪支付信息
});
```

### Q5: 如何在多个组件间共享追踪逻辑？

**A:** 使用自定义Hook：

```javascript
// hooks/useCommonTracking.js
export const useCommonTracking = () => {
  const { track } = usePostHogTrack();

  const trackError = useCallback((errorMessage, errorCode) => {
    track('Error Occurred', {
      error_message: errorMessage,
      error_code: errorCode,
      timestamp: new Date().toISOString()
    });
  }, [track]);

  return { trackError };
};

// 在多个组件中使用
function ComponentA() {
  const { trackError } = useCommonTracking();
  // ...
}

function ComponentB() {
  const { trackError } = useCommonTracking();
  // ...
}
```

---

## 📊 追踪检查清单

在添加新功能时，确保追踪以下关键点：

- [ ] **页面/组件加载** - 用户到达这个页面
- [ ] **主要操作** - 用户执行的核心功能
- [ ] **成功状态** - 操作成功完成
- [ ] **失败状态** - 操作失败及原因
- [ ] **用户输入** - 搜索、筛选、表单提交（不包含敏感信息）
- [ ] **导航行为** - 点击链接、返回、跳转
- [ ] **关键决策点** - 用户做出选择的时刻
- [ ] **转化漏斗** - 从意向到完成的关键步骤

---

## 🔗 相关资源

- [PostHog 官方文档](https://posthog.com/docs)
- [POSTHOG_INTEGRATION.md](./POSTHOG_INTEGRATION.md) - 集成总体说明
- [constants.js](./src/lib/constants.js) - 所有事件常量定义
- [usePostHogRedux.js](./src/hooks/usePostHogRedux.js) - 核心追踪Hook

---

## 📝 版本历史

- **v1.0** (2025-10-29): 初始版本，包含13个追踪Hook的完整使用指南
- **v1.1** (待定): 计划添加P2功能追踪指南

---

**维护者**: 开发团队
**最后更新**: 2025-10-29