# AutoClip 埋点体系

> 工具：**PostHog**（US 区，`https://us.i.posthog.com`）
> 原则（见 `ROADMAP.md` Phase 0）：**匿名 · 可关 · 本地缓冲**。不采集 PII、视频内容、字幕文本、API key 明文。

## 1. 指标框架

| 层级 | 指标 | 数据来源 |
|------|------|---------|
| 🌟 北极星 | 周成功出片用户数 | `clips_exported` |
| 获取 | 下载数 / 安装数 | 下载页 / `app_installed` |
| 激活 | 导入→出片转化率、首次出片耗时 | 漏斗事件 |
| 留存 | D1/D7/D30、周活 | `app_opened`（PostHog 自动算） |
| 参与 | 人均出片数、功能渗透率 | 各功能事件 |
| 变现就绪 | 模型分布、配 key 率、失败率 | `api_key_configured` / `processing_failed` |

## 2. 核心漏斗

```
下载 .dmg → app_installed → video_imported → clips_exported(★激活) → 回访(留存)
```

## 3. 事件字典

命名规范：`对象_动作`，snake_case。代码统一走 `src/analytics/events.ts`，未配置 key 或用户关闭时自动 no-op。

### 生命周期（`src/analytics/lifecycle.ts`）
| 事件 | 触发 | 属性 |
|------|------|------|
| `app_installed` | 设备首次启动 | `version, os, arch` |
| `app_opened` | 每次启动 | `version, session_number` |
| `app_updated` | 版本号变化 | `from_version, to_version` |

### 激活漏斗
| 事件 | 触发位置 | 属性 |
|------|---------|------|
| `video_imported` | `api.ts` `uploadFiles` / `createDownloadTask` / `createYouTubeDownloadTask` | `source(upload/url), fileType, sizeBytes` |
| `clips_exported` ★ | `api.ts` `downloadVideo` | `clipCount, exportType(clip/collection/project)` |

### 配置
| 事件 | 触发位置 | 属性 |
|------|---------|------|
| `api_key_configured` | `SettingsPage` 保存成功后 | `provider, hasKey`（**不传明文**） |

### 错误
| 事件 | 触发位置 | 属性 |
|------|---------|------|
| `processing_failed` | `api.ts` 导入/导出 catch | `stage(import/export/...), code, message` |

> 崩溃/异常栈交给 **Sentry**（Phase 0 另接），PostHog 只记业务失败。

## 4. 全局属性（Super Properties）

每条事件自动携带，在 `lifecycle.ts` 的 `trackLaunch()` 里注册：
`app_version`（Tauri `getVersion()`）· `os` · `arch` · `app_locale`。

## 5. 身份模型

- 现在：匿名设备 ID（PostHog 自动，`localStorage` 持久化）。
- Phase 1 账号上线后：登录 `identifyUser(userId)`、登出 `resetUser()`（`src/analytics/posthog.ts` 已备好）。

## 6. 下载量（App 外）

App 内用 `app_installed` 当装机量。若有官网，加 PostHog 网页 snippet 埋 `download_clicked`，串成"落地页→下载→安装"全漏斗。

## 7. 隐私 / 合规

- 设置页 → 应用设置 → **隐私与数据** 开关（`setAnalyticsEnabled`），状态持久化，重启生效。
- 默认关录屏、不采 PII、key 只记 `hasKey`。
- 上线前需配套**隐私政策**（《个人信息保护法》要求）。

## 8. 配置

环境变量（`frontend/.env.local`，已 gitignore）：
```
VITE_PUBLIC_POSTHOG_KEY=phc_xxx
VITE_PUBLIC_POSTHOG_HOST=https://us.i.posthog.com
```
缺省时埋点全程 no-op。模板见 `frontend/.env.example`。

## 9. 加新事件的步骤

1. 在 `events.ts` 的 `AnalyticsEvent` 加常量 + 类型化封装函数。
2. 在调用点 import 调用（优先放 `services/api.ts` 这类集中层）。
3. 更新本文件的事件字典。