# 集成说明：声明式埋点与现有 Umami 工具

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

## 概述

声明式埋点系统通过复用现有的 `UmamiAnalytics` 工具来避免代码重复，保持架构一致性。

## 架构设计

### 现有工具

**位置**: `packages/drawnix/src/utils/umami-analytics.ts`

现有的 `UmamiAnalytics` 类提供：
- 基础事件追踪 `analytics.track(eventName, eventData)`
- AI 生成事件专用方法（图片、视频、聊天生成）
- 用户交互事件追踪
- 特性使用追踪
- 统一的日志输出 `[Analytics]`

```typescript
// 现有用法示例
import { analytics, AIGenerationEvent } from '../../utils/umami-analytics';

analytics.trackAIGeneration(AIGenerationEvent.IMAGE_GENERATION_START, {
  taskId: 'task-123',
  model: 'gemini-pro',
  promptLength: 150,
});
```

### 声明式埋点适配器

**位置**: `packages/drawnix/src/services/tracking/umami-adapter.ts`

`UmamiTrackingAdapter` 作为适配器层：
- 调用 `analytics.track()` 而不是直接使用 `window.umami`
- 注入声明式埋点专属元数据（version, url, sessionId, viewport, eventType）
- 提供批量上报支持
- 统一的日志输出 `[Tracking]`

```typescript
// 适配器实现（简化）
import { analytics } from '../../utils/umami-analytics';

export class UmamiTrackingAdapter {
  async track(event: TrackEvent): Promise<void> {
    const enrichedData = {
      ...event.params,
      version: event.metadata.version,
      url: event.metadata.url,
      timestamp: event.metadata.timestamp,
      sessionId: event.metadata.sessionId,
      eventType: event.metadata.eventType,
    };

    // 复用现有工具
    analytics.track(event.eventName, enrichedData);
  }
}
```

## 两种埋点方式的对比

### 1. 手动埋点（现有方式）

**适用场景**: AI 生成、API 调用、特定业务逻辑

```typescript
// 在代码中显式调用
analytics.trackAIGeneration(AIGenerationEvent.IMAGE_GENERATION_START, {
  taskId: task.id,
  model: 'gemini-pro',
  duration: 2500,
});
```

**优点**:
- 精确控制埋点时机
- 丰富的业务上下文
- 类型安全的事件枚举

### 2. 声明式埋点（新方式）

**适用场景**: UI 交互、按钮点击、页面浏览

```html
<!-- 在 JSX 中声明 -->
<button track="button_click_save">保存</button>
<button track="button_click_export" track-params='{"format": "png"}'>导出</button>
<div track-hover="card_hover_features">特性卡片</div>
```

**优点**:
- 无需修改业务代码
- 自动批量上报减少网络请求
- 失败自动重试
- 防抖避免重复上报

## 数据流对比

### 手动埋点数据流

```
业务代码
  ↓
analytics.trackXXX()
  ↓
window.umami.track()
  ↓
Umami 服务器
```

### 声明式埋点数据流

```
用户交互 (点击/悬停)
  ↓
TrackingService (事件捕获)
  ↓
防抖检查
  ↓
元数据注入 (version, url, sessionId)
  ↓
批量队列 (10 events OR 5s)
  ↓
UmamiAdapter
  ↓
analytics.track() (复用现有工具)
  ↓
window.umami.track()
  ↓
Umami 服务器
```

## 元数据对比

### 手动埋点元数据

```json
{
  "category": "ai_generation",
  "taskId": "task-123",
  "model": "gemini-pro",
  "duration": 2500,
  "timestamp": 1701849600000
}
```

### 声明式埋点元数据

```json
{
  "version": "0.2.1",
  "url": "https://opentu.ai/editor",
  "timestamp": 1701849600000,
  "sessionId": "session-abc123",
  "eventType": "click",
  "viewport": "1920x1080",
  "buttonId": "save-btn"
}
```

## 统一的日志输出

两种方式的日志输出可以通过前缀区分：

```
[Analytics] Event tracked: image_generation_start
[Tracking] Event tracked: button_click_save
[Tracking] Batching event (3/10)
[Tracking] Batch uploading (10 events)
```

## 避免重复代码的措施

### ✅ 已采取的措施

1. **复用 window.umami 接口定义** - 使用 `umami-analytics.ts` 中的全局声明
2. **复用 analytics 单例** - UmamiAdapter 调用 `analytics.track()`
3. **统一错误处理** - 两种方式使用相同的 try-catch 模式
4. **统一日志格式** - 都使用 `console.debug/error` 输出

### ❌ 避免的重复

1. ~~不再重复定义 `window.umami` 接口~~ ✓
2. ~~不再重复实现 `track()` 方法~~ ✓
3. ~~不再重复 SDK 可用性检查逻辑~~ ✓

## 使用建议

### 何时使用手动埋点

- AI 生成事件（图片、视频、聊天）
- API 调用追踪
- 后台任务状态变更
- 需要丰富业务上下文的场景

```typescript
analytics.trackModelSuccess({
  taskId: task.id,
  taskType: 'image',
  model: 'gemini-pro',
  duration: 2500,
});
```

### 何时使用声明式埋点

- UI 按钮点击
- 链接点击
- 卡片悬停
- 表单聚焦
- 需要批量上报的高频交互

```html
<button track="button_click_save">保存</button>
```

### 可以混合使用

在同一个组件中，可以同时使用两种方式：

```tsx
function MyComponent() {
  const handleComplexAction = async () => {
    // 手动埋点：追踪业务逻辑
    analytics.trackFeatureUsage(FeatureUsageEvent.IMAGE_UPLOAD, {
      feature: 'crop',
      value: cropSettings.aspectRatio,
    });

    // 执行业务逻辑
    await uploadImage();
  };

  return (
    <>
      {/* 声明式埋点：追踪简单点击 */}
      <button track="button_click_cancel">取消</button>

      {/* 手动埋点：追踪复杂业务逻辑 */}
      <button onClick={handleComplexAction}>上传</button>
    </>
  );
}
```

## 测试验证

### 验证现有埋点未受影响

```typescript
// 确认现有 AI 生成埋点正常工作
analytics.trackAIGeneration(AIGenerationEvent.IMAGE_GENERATION_START, {...});
// 应在 Umami 面板看到 image_generation_start 事件
```

### 验证声明式埋点正常工作

```html
<button track="test_button_click">测试按钮</button>
<!-- 点击后应在 Umami 面板看到 test_button_click 事件 -->
<!-- 事件数据包含 version, url, sessionId 等元数据 -->
```

### 验证批量上报

```typescript
// 连续点击 10 次或等待 5 秒
// 控制台应看到：[Tracking] Batch uploading (10 events)
// 网络面板应看到单个批量请求而不是 10 个独立请求
```

## 未来改进方向

1. **统一元数据注入** - 考虑在 `UmamiAnalytics` 中也注入 version, sessionId
2. **统一批量上报** - 考虑为手动埋点也提供批量上报能力
3. **IndexedDB 离线缓存** - 实现持久化缓存，将失败事件缓存到 IndexedDB（最多 100 个，保留 1 小时）
4. **统一配置管理** - 统一管理两种埋点的配置（日志级别、重试策略等）

## 总结

通过适配器模式复用现有的 `UmamiAnalytics` 工具：
- ✅ 避免了代码重复
- ✅ 保持了架构一致性
- ✅ 两种埋点方式可以共存
- ✅ 自动受益于现有工具的改进
- ✅ 为未来统一埋点系统铺平道路