# Technical Research: 声明式埋点上报系统

**Feature**: 005-declarative-tracking
**Date**: 2025-12-05
**Status**: Complete

## Research Questions

本研究解决 Technical Context 中标记的关键技术决策和最佳实践。

---

## 1. Umami Analytics API 集成

### Question
如何集成和扩展 Umami 的事件上报 API,以支持自定义元数据(version, location.href)?

### Research Findings

**Umami 事件上报机制**:
- Umami 使用 `/api/send` 端点接收事件
- 支持自定义事件属性(event data)
- 标准请求格式:
  ```json
  {
    "type": "event",
    "payload": {
      "website": "website-id",
      "name": "event-name",
      "data": {
        // 自定义属性
        "version": "1.0.0",
        "url": "https://example.com/page"
      }
    }
  }
  ```

**现有集成分析**:
- 项目可能已有 Umami tracker 脚本或 SDK
- 需要检查 `apps/web/src/` 中的 Umami 初始化代码
- 常见集成方式:`umami.track('event-name', { custom: 'data' })`

**扩展方案**:
- 方案 A: 直接调用 Umami SDK 的 `track` 方法,传递自定义 data
- 方案 B: 直接调用 Umami API (`/api/send`),完全控制请求格式
- 方案 C: 包装现有 Umami 实例,自动注入 version 和 url

### Decision
**选择方案 A (包装 Umami SDK)**:
- 优点: 复用现有 Umami 配置(website ID, API endpoint)
- 优点: 自动处理会话、用户标识
- 优点: 利用 Umami 的内置重试和错误处理
- 实现: 创建 `UmamiTrackingAdapter` 类,封装 `umami.track()` 调用

**扩展元数据注入**:
```typescript
interface UmamiTrackingAdapter {
  track(eventName: string, params?: Record<string, any>): void {
    const enrichedData = {
      ...params,
      version: this.getVersion(),     // 从 package.json 读取
      url: window.location.href,       // 实时获取
      timestamp: Date.now()
    };
    umami.track(eventName, enrichedData);
  }
}
```

### Alternatives Considered
- **方案 B (直接 API)**: 需要重新实现会话管理、用户标识,维护成本高
- **方案 C (修改全局 Umami)**: 侵入性强,可能影响其他埋点代码

---

## 2. 事件委托 vs MutationObserver

### Question
对于动态添加的元素,应该使用事件委托还是 MutationObserver?

### Research Findings

**事件委托 (Event Delegation)**:
- 原理: 在父容器上监听事件,通过 `event.target` 判断目标元素
- 优点: 性能高,不需要为每个元素添加监听器
- 优点: 自动处理动态元素,无需额外逻辑
- 缺点: 只能监听冒泡事件(click、input 等),无法监听非冒泡事件(focus、blur 需 capture 模式)

**MutationObserver**:
- 原理: 监听 DOM 树变更,检测新增元素并为其添加监听器
- 优点: 可以精确控制每个元素的行为
- 优点: 支持非冒泡事件
- 缺点: 性能开销较大(每次 DOM 变更都会触发回调)
- 缺点: 需要手动管理监听器的添加和移除

**混合方案**:
- 冒泡事件(click): 使用事件委托
- 非冒泡事件(focus, hover): 使用 MutationObserver + 事件捕获

### Decision
**选择混合方案**:
- 核心功能(click 事件): **使用事件委托**
  - 在 `document.body` 或应用根节点添加一个 click 监听器
  - 通过 `event.target.closest('[track]')` 查找带埋点属性的元素
  - 性能最优,代码简洁
- 扩展功能(hover, focus): **使用 MutationObserver**
  - 仅在启用 `track-hover` 或 `track-focus` 时才激活 MutationObserver
  - 监听新增元素,为其添加对应的事件监听器
  - 使用 WeakMap 存储已添加监听器的元素,避免重复添加

**实现示例**:
```typescript
// 事件委托 (click)
document.body.addEventListener('click', (event) => {
  const target = event.target.closest('[track]');
  if (target && !isExcluded(target)) {
    const eventName = target.getAttribute('track');
    trackingService.track(eventName, getParams(target));
    event.stopPropagation(); // 阻止冒泡到父元素
  }
}, { capture: false });

// MutationObserver (hover/focus)
const observer = new MutationObserver((mutations) => {
  for (const mutation of mutations) {
    for (const node of mutation.addedNodes) {
      if (node.nodeType === Node.ELEMENT_NODE) {
        attachEventListeners(node as Element);
      }
    }
  }
});
observer.observe(document.body, { childList: true, subtree: true });
```

### Rationale
- 事件委托覆盖 90% 的使用场景(click 是最常见的交互)
- MutationObserver 仅在需要时启用,避免不必要的性能开销
- 符合渐进增强原则

---

## 3. 批量上报策略

### Question
如何实现高效的批量上报机制(10 个事件或 5 秒)?

### Research Findings

**批量上报模式**:
1. **时间窗口模式**: 固定时间间隔(如 5 秒)上报一次
   - 简单但可能延迟较大
2. **数量触发模式**: 累积到固定数量(如 10 个)立即上报
   - 响应快但可能频繁上报
3. **混合模式**: 先到达的条件触发(数量 OR 时间)
   - 平衡延迟和网络开销

**实现方案**:
- 使用队列(数组)缓存待上报事件
- 使用 `setTimeout` 实现时间窗口
- 使用数组长度判断数量阈值

### Decision
**选择混合模式**:
```typescript
class TrackingBatchService {
  private queue: TrackEvent[] = [];
  private timer: NodeJS.Timeout | null = null;
  private readonly BATCH_SIZE = 10;
  private readonly BATCH_TIMEOUT = 5000; // 5 秒

  enqueue(event: TrackEvent): void {
    this.queue.push(event);

    // 启动定时器(如果未启动)
    if (!this.timer) {
      this.timer = setTimeout(() => this.flush(), this.BATCH_TIMEOUT);
    }

    // 达到数量阈值,立即上报
    if (this.queue.length >= this.BATCH_SIZE) {
      this.flush();
    }
  }

  private async flush(): Promise<void> {
    if (this.queue.length === 0) return;

    const batch = [...this.queue];
    this.queue = [];

    if (this.timer) {
      clearTimeout(this.timer);
      this.timer = null;
    }

    await this.sendBatch(batch);
  }

  // 页面卸载时立即上报
  onBeforeUnload(): void {
    if (this.queue.length > 0) {
      navigator.sendBeacon(API_ENDPOINT, JSON.stringify(this.queue));
    }
  }
}
```

**关键设计点**:
- 清空队列时使用 `[...this.queue]` 避免并发问题
- 页面卸载时使用 `navigator.sendBeacon`,确保数据不丢失
- 定时器在 flush 后清除,避免重复上报

---

## 4. 防抖实现

### Question
如何实现 500ms 防抖,避免同一元素的重复上报?

### Research Findings

**防抖策略**:
1. **全局防抖**: 任意事件触发后 500ms 内不上报任何事件
   - 简单但可能误杀正常事件
2. **元素级防抖**: 每个元素单独计时,500ms 内同一元素的同一事件只上报一次
   - 精确但需要存储状态
3. **事件级防抖**: 同一事件名防抖(不区分元素)
   - 折中方案

### Decision
**选择元素级防抖**:
```typescript
class TrackingDebouncer {
  private debounceMap = new WeakMap<Element, Map<string, number>>();
  private readonly DEBOUNCE_TIME = 500;

  shouldTrack(element: Element, eventName: string): boolean {
    if (!this.debounceMap.has(element)) {
      this.debounceMap.set(element, new Map());
    }

    const eventTimestamps = this.debounceMap.get(element)!;
    const lastTimestamp = eventTimestamps.get(eventName) || 0;
    const now = Date.now();

    if (now - lastTimestamp < this.DEBOUNCE_TIME) {
      return false; // 防抖中,不上报
    }

    eventTimestamps.set(eventName, now);
    return true; // 可以上报
  }
}
```

**优势**:
- WeakMap 自动清理已删除元素的引用,避免内存泄漏
- 支持不同事件名的独立防抖(click 和 hover 互不影响)
- 精确控制每个元素的上报频率

---

## 5. 自动埋点选择器

### Question
如何高效识别应该自动埋点的元素(原生交互元素 + onClick + role)?

### Research Findings

**选择器策略**:
1. **CSS 选择器**: `button, a, input, select, [onclick], [role="button"]`
   - 简单但不够精确(onclick 可能是字符串属性)
2. **DOM 属性检查**: 遍历元素,检查 `onclick` 是否为函数
   - 精确但性能较差
3. **混合方案**: CSS 选择器 + 属性验证

### Decision
**选择混合方案**:
```typescript
const AUTO_TRACK_SELECTOR = `
  button:not([data-track-ignore]),
  a:not([data-track-ignore]),
  input[type="button"]:not([data-track-ignore]),
  input[type="submit"]:not([data-track-ignore]),
  select:not([data-track-ignore]),
  [role="button"]:not([data-track-ignore]),
  [role="link"]:not([data-track-ignore])
`.trim();

function shouldAutoTrack(element: Element): boolean {
  // 1. 检查是否在排除区域
  if (element.closest('nav, header, footer, [data-track-ignore]')) {
    return false;
  }

  // 2. 检查是否匹配选择器
  if (element.matches(AUTO_TRACK_SELECTOR)) {
    return true;
  }

  // 3. 检查是否有 onClick 事件处理器(React/Vue 绑定)
  if (element.hasAttribute('onclick') || hasEventListener(element, 'click')) {
    return true;
  }

  return false;
}

// 辅助:检查元素是否有事件监听器(仅限 React Fiber)
function hasEventListener(element: Element, eventType: string): boolean {
  // React Fiber 内部属性
  const fiberKey = Object.keys(element).find(key =>
    key.startsWith('__reactFiber') || key.startsWith('__reactProps')
  );
  if (fiberKey) {
    const props = (element as any)[fiberKey]?.memoizedProps;
    return props && typeof props[`on${capitalize(eventType)}`] === 'function';
  }
  return false;
}
```

**排除逻辑**:
- 使用 `closest()` 检查父级,避免导航/工具栏/页脚中的元素
- `data-track-ignore` 属性优先级最高,强制排除

---

## 6. 缓存管理

### Question
如何实现失败事件的缓存(100 个事件, 1 小时 TTL)?

### Research Findings

**存储方案**:
1. **localStorage**: 同步 API,5MB 限制,可能阻塞主线程
2. **IndexedDB**: 异步 API,更大容量,但 API 复杂
3. **localforage**: IndexedDB 的简化封装,降级到 localStorage

### Decision
**选择 localforage**:
- 项目已使用 localforage(参考 `media-cache-service.ts`)
- 自动选择最佳存储方案(IndexedDB > WebSQL > localStorage)
- API 简洁,Promise 友好

**缓存结构**:
```typescript
interface CachedEvent {
  event: TrackEvent;
  cachedAt: number;
  retryCount: number;
}

class TrackingStorageService {
  private readonly STORAGE_KEY = 'tracking_cache';
  private readonly MAX_CACHE_SIZE = 100;
  private readonly CACHE_TTL = 60 * 60 * 1000; // 1 小时

  async add(event: TrackEvent): Promise<void> {
    const cached = await this.getAll();

    // 清理过期事件
    const now = Date.now();
    const valid = cached.filter(c =>
      now - c.cachedAt < this.CACHE_TTL
    );

    // 限制数量(FIFO)
    if (valid.length >= this.MAX_CACHE_SIZE) {
      valid.shift(); // 移除最旧的
    }

    valid.push({
      event,
      cachedAt: now,
      retryCount: 0
    });

    await localforage.setItem(this.STORAGE_KEY, valid);
  }

  async getAll(): Promise<CachedEvent[]> {
    return await localforage.getItem(this.STORAGE_KEY) || [];
  }

  async clear(): Promise<void> {
    await localforage.removeItem(this.STORAGE_KEY);
  }
}
```

**重试逻辑**:
- 定期从缓存读取失败事件(每 30 秒)
- 重试成功后从缓存移除
- 重试次数超过 3 次后丢弃

---

## 7. 项目版本号获取

### Question
如何从 package.json 或应用配置读取项目版本号?

### Research Findings

**方案对比**:
1. **直接 import package.json**: 在构建时将 version 注入代码
   ```typescript
   import { version } from '../../../package.json';
   ```
   - Vite/Webpack 支持 JSON import
   - 缺点: 运行时无法动态更新

2. **环境变量**: 构建时注入 `VITE_APP_VERSION`
   ```typescript
   const version = import.meta.env.VITE_APP_VERSION;
   ```
   - 灵活,支持不同环境的不同版本号
   - 需要在 vite.config.ts 中配置

3. **全局配置对象**: 应用启动时从 API 或配置文件读取
   ```typescript
   const version = window.APP_CONFIG?.version || '0.0.0';
   ```
   - 动态,但需要额外的配置加载逻辑

### Decision
**选择方案 2 (环境变量)**:
```typescript
// vite.config.ts
import { defineConfig } from 'vite';
import packageJson from './package.json';

export default defineConfig({
  define: {
    'import.meta.env.VITE_APP_VERSION': JSON.stringify(packageJson.version)
  }
});

// tracking-service.ts
export class TrackingService {
  private getVersion(): string {
    return import.meta.env.VITE_APP_VERSION || 'unknown';
  }
}
```

**优势**:
- 构建时自动读取 package.json 的 version
- 支持不同环境(dev, staging, prod)的版本标识
- 无需手动维护版本号

---

## Summary of Decisions

| Decision | Choice | Rationale |
|----------|--------|-----------|
| Umami 集成 | 包装 Umami SDK | 复用现有配置,自动处理会话 |
| 动态元素监听 | 事件委托 + MutationObserver 混合 | click 用委托(性能),hover/focus 用 Observer |
| 批量上报 | 混合模式(10 事件 OR 5 秒) | 平衡延迟和网络开销 |
| 防抖 | 元素级防抖(WeakMap) | 精确控制,避免内存泄漏 |
| 自动埋点选择 | CSS 选择器 + React Fiber 检查 | 全面覆盖,支持框架绑定 |
| 缓存存储 | localforage (IndexedDB) | 项目标准,自动降级 |
| 版本号获取 | Vite 环境变量 | 构建时注入,无需手动维护 |

---

**Next Steps**: 进入 Phase 1,生成 data-model.md, contracts/, quickstart.md