Initial TrueGrowth source import

specs/005-declarative-tracking/INTEGRATION.md

@@ -0,0 +1,291 @@
+# 集成说明：声明式埋点与现有 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` 工具：
+- ✅ 避免了代码重复
+- ✅ 保持了架构一致性
+- ✅ 两种埋点方式可以共存
+- ✅ 自动受益于现有工具的改进
+- ✅ 为未来统一埋点系统铺平道路