vf_react/src/constants/tracking.js

// src/constants/tracking.js
// PostHog 事件追踪优先级配置

/**
 * 事件优先级枚举
 *
 * 用于决定事件的追踪时机，优化性能和用户体验。
 *
 * @enum {string}
 */
export const EVENT_PRIORITY = {
  /**
   * 关键事件 - 立即发送，不可延迟
   * 示例：登录、注册、支付、订阅购买
   */
  CRITICAL: 'critical',

  /**
   * 高优先级事件 - 立即发送
   * 示例：详情打开、搜索提交、关注操作、分享操作
   */
  HIGH: 'high',

  /**
   * 普通优先级事件 - 空闲时发送
   * 示例：列表查看、筛选应用、排序变更
   */
  NORMAL: 'normal',

  /**
   * 低优先级事件 - 空闲时发送，可批量合并
   * 示例：鼠标移动、滚动事件、hover 事件
   */
  LOW: 'low',
};

/**
 * Community 页面（新闻催化分析）事件优先级映射
 *
 * 映射规则：
 * - CRITICAL: 无（Community 页面无关键业务操作）
 * - HIGH: 用户明确的交互操作（点击、打开详情、搜索、跳转）
 * - NORMAL: 被动浏览事件（页面加载、列表查看、筛选、排序）
 * - LOW: 暂未使用
 *
 * @type {Object<string, string>}
 */
export const COMMUNITY_EVENT_PRIORITIES = {
  // ==================== 普通优先级（空闲时追踪）====================

  /**
   * 页面浏览事件 - NORMAL
   * 触发时机：用户进入 Community 页面
   * 延迟原因：页面加载时避免阻塞渲染
   */
  'Community Page Viewed': EVENT_PRIORITY.NORMAL,

  /**
   * 新闻列表查看 - NORMAL
   * 触发时机：新闻列表加载完成
   * 延迟原因：避免阻塞列表渲染
   */
  'News List Viewed': EVENT_PRIORITY.NORMAL,

  /**
   * 新闻筛选应用 - NORMAL
   * 触发时机：用户应用筛选条件（重要性、日期、行业）
   * 延迟原因：筛选操作频繁，避免阻塞 UI 更新
   */
  'News Filter Applied': EVENT_PRIORITY.NORMAL,

  /**
   * 新闻排序变更 - NORMAL
   * 触发时机：用户切换排序方式（最新、最热、收益率）
   * 延迟原因：排序操作频繁，避免阻塞 UI 更新
   */
  'News Sorted': EVENT_PRIORITY.NORMAL,

  /**
   * 新闻标签页点击 - NORMAL
   * 触发时机：用户点击新闻详情中的标签页（相关股票、相关概念、时间线）
   * 延迟原因：标签切换高频，延迟追踪不影响用户体验
   */
  'News Tab Clicked': EVENT_PRIORITY.NORMAL,

  // ==================== 高优先级（立即追踪）====================

  /**
   * 新闻文章点击 - HIGH
   * 触发时机：用户点击新闻卡片
   * 立即追踪原因：关键交互操作，需要准确记录点击位置和时间
   */
  'News Article Clicked': EVENT_PRIORITY.HIGH,

  /**
   * 新闻详情打开 - HIGH
   * 触发时机：打开新闻详情弹窗或页面
   * 立即追踪原因：关键交互操作，需要准确记录查看时间
   */
  'News Detail Opened': EVENT_PRIORITY.HIGH,

  /**
   * 搜索查询提交 - HIGH
   * 触发时机：用户提交搜索关键词
   * 立即追踪原因：用户明确操作，需要准确记录搜索意图
   */
  'Search Query Submitted': EVENT_PRIORITY.HIGH,

  /**
   * 搜索无结果 - HIGH
   * 触发时机：搜索返回 0 个结果
   * 立即追踪原因：重要的用户体验指标，需要及时发现问题
   */
  'Search No Results': EVENT_PRIORITY.HIGH,

  /**
   * 相关股票点击 - HIGH
   * 触发时机：用户从新闻详情点击相关股票
   * 立即追踪原因：重要的跳转行为，需要准确记录导流效果
   */
  'Stock Clicked': EVENT_PRIORITY.HIGH,

  /**
   * 相关概念点击 - HIGH
   * 触发时机：用户从新闻详情点击相关概念
   * 立即追踪原因：重要的跳转行为，需要准确记录导流效果
   */
  'Concept Clicked': EVENT_PRIORITY.HIGH,

  /**
   * 事件关注操作 - HIGH
   * 触发时机：用户点击关注按钮
   * 立即追踪原因：关键业务操作，需要准确记录关注行为
   */
  'Event Followed': EVENT_PRIORITY.HIGH,

  /**
   * 事件取消关注 - HIGH
   * 触发时机：用户取消关注事件
   * 立即追踪原因：关键业务操作，需要准确记录取关原因
   */
  'Event Unfollowed': EVENT_PRIORITY.HIGH,
};

/**
 * requestIdleCallback 配置
 *
 * @type {Object}
 */
export const IDLE_CALLBACK_CONFIG = {
  /**
   * 超时时间（毫秒）
   * 即使浏览器不空闲，也会在此时间后强制执行追踪
   *
   * 设置为 2000ms 的原因：
   * - 足够长：避免在用户快速操作时阻塞主线程
   * - 足够短：确保用户快速关闭页面前也能发送事件
   * - 平衡点：2 秒是用户注意力的典型持续时间
   */
  timeout: 2000,
};

/**
 * 获取事件优先级
 *
 * @param {string} eventName - 事件名称
 * @returns {string} 事件优先级（CRITICAL | HIGH | NORMAL | LOW）
 */
export const getEventPriority = (eventName) => {
  return COMMUNITY_EVENT_PRIORITIES[eventName] || EVENT_PRIORITY.NORMAL;
};

/**
 * 判断事件是否需要立即追踪
 *
 * @param {string} eventName - 事件名称
 * @returns {boolean} 是否立即追踪
 */
export const shouldTrackImmediately = (eventName) => {
  const priority = getEventPriority(eventName);
  return priority === EVENT_PRIORITY.CRITICAL || priority === EVENT_PRIORITY.HIGH;
};

/**
 * 判断事件是否可以延迟追踪
 *
 * @param {string} eventName - 事件名称
 * @returns {boolean} 是否可以延迟追踪
 */
export const canTrackIdle = (eventName) => {
  const priority = getEventPriority(eventName);
  return priority === EVENT_PRIORITY.NORMAL || priority === EVENT_PRIORITY.LOW;
};

// ==================== 默认导出 ====================

export default {
  EVENT_PRIORITY,
  COMMUNITY_EVENT_PRIORITIES,
  IDLE_CALLBACK_CONFIG,
  getEventPriority,
  shouldTrackImmediately,
  canTrackIdle,
};