Implementation Plan: 声明式埋点上报系统

Branch: 005-declarative-tracking | Date: 2025-12-05 | Spec: spec.md Input: Feature specification from /specs/005-declarative-tracking/spec.md

Note: This template is filled in by the /speckit.plan command. See .specify/templates/commands/plan.md for the execution workflow.

Summary

实现一个声明式埋点上报系统,允许开发者通过 HTML 属性(如 track="event_name")为元素添加埋点,系统自动捕获用户交互并上报到 Umami 分析服务。支持事件批量上报、失败重试、自动埋点模式,以及扩展的元数据(项目版本号、页面地址)。技术方案基于插件架构(withTracking),使用事件委托和 MutationObserver 监听动态元素,集成现有 Umami SDK 并扩展参数上报能力。

Technical Context

Language/Version: TypeScript 5.x (strict mode) Primary Dependencies:

React 18+
Umami Analytics SDK (现有集成)
RxJS (状态管理,参考现有 services 模式)
localforage (事件缓存) Storage: IndexedDB (via localforage) - 用于缓存失败的上报事件(最多 100 个,保留 1 小时) Testing: Jest + React Testing Library (单元/组件测试), Playwright (E2E 测试) Target Platform: Modern browsers (支持 MutationObserver, navigator.sendBeacon, IndexedDB) Project Type: Monorepo (Nx) - 代码放置在 packages/drawnix/src/plugins/ 和 packages/drawnix/src/services/ Performance Goals:
事件上报延迟 <100ms (批量上报前)
防抖 500ms
批量上报减少网络请求 60%+
性能开销 <2% 页面加载时间 Constraints:
单文件 <500 行(宪章硬性约束)
缓存上限 100 个事件, 1 小时 TTL
批量上报:10 个事件或 5 秒
排除导航/工具栏/页脚区域的自动埋点 Scale/Scope:
支持 1000+ 可点击元素的页面
自动埋点覆盖率 95%+
适配现有 Drawnix 组件生态

Constitution Check

GATE: Must pass before Phase 0 research. Re-check after Phase 1 design.

✅ I. 插件优先架构

合规: 实现为 withTracking 插件,遵循现有 withFreehand, withMind 等模式
自包含: 埋点逻辑独立,不侵入其他插件
可组合: 与其他插件无冲突,通过配置启用/禁用
框架无关: 核心逻辑(事件监听、批量上报、缓存)可独立于 React 使用

✅ II. 文件大小约束

合规策略:
- 插件入口: withTracking.ts (<200 行,仅组合逻辑)
- 服务层: tracking-service.ts (<500 行,核心上报逻辑)
- 工具类: tracking-utils.ts (<300 行,事件名生成、选择器匹配)
- 配置: tracking-config.types.ts (<150 行,类型定义)
- 存储: tracking-storage-service.ts (<250 行,缓存管理,复用 localforage 模式)
- 批处理: tracking-batch-service.ts (<300 行,批量上报逻辑)
验证: 每个文件独立功能,可独立测试,总共 6 个文件,均 <500 行

✅ III. 类型安全优先

合规:
- 所有配置使用 interface TrackConfig
- 事件对象使用 interface TrackEvent
- 严格类型化的事件参数(JSON 解析后验证)
- 避免 any,使用泛型和联合类型

✅ IV. 设计系统一致性

N/A: 本功能无 UI 组件,纯逻辑层服务
日志输出: 开发环境使用 console.warn,生产环境使用错误日志服务

✅ V. 性能与优化

合规:
- 使用防抖(500ms)避免重复上报
- 事件委托减少监听器数量
- MutationObserver 仅监听必要的 DOM 变更
- 批量上报减少网络开销
- 使用 WeakMap 存储元素引用,避免内存泄漏

✅ VI. 安全与验证

合规:
- 验证 track-params JSON 格式,捕获解析错误
- 过滤敏感信息(密码输入框的值不上报)
- API 密钥从配置读取,不硬编码
- navigator.sendBeacon 确保页面卸载时的安全上报

✅ VII. Monorepo 结构

合规:
- 插件代码: packages/drawnix/src/plugins/tracking/
- 服务代码: packages/drawnix/src/services/tracking/
- 类型定义: packages/drawnix/src/types/tracking.types.ts
- 测试: packages/drawnix/src/plugins/tracking/__tests__/

⚠️ VIII. 测试要求

计划:
- 单元测试: 事件捕获、批量逻辑、缓存管理
- 组件测试: 插件集成测试(模拟 DOM 交互)
- 集成测试: 与 Umami SDK 的集成
- E2E 测试: 完整用户交互流程(点击 → 批量上报 → 验证上报数据)
目标覆盖率: >80%

Project Structure

Documentation (this feature)

specs/005-declarative-tracking/
├── spec.md              # 功能规范
├── plan.md              # 本文件(实现计划)
├── research.md          # Phase 0: 技术调研(Umami API、事件监听模式)
├── data-model.md        # Phase 1: 数据模型(TrackEvent、TrackConfig、缓存结构)
├── quickstart.md        # Phase 1: 快速开始指南
├── contracts/           # Phase 1: Umami API 集成契约
│   └── umami-api.md     # Umami 事件上报接口定义
├── checklists/          # 质量检查清单
│   └── requirements.md  # 需求完整性检查
└── tasks.md             # Phase 2: 任务分解(待生成)

Source Code (repository root)

packages/drawnix/src/
├── plugins/
│   └── tracking/
│       ├── index.ts                    # 插件导出
│       ├── withTracking.ts             # 主插件入口(<200 行)
│       ├── hooks/
│       │   └── useTracking.ts          # React Hook 封装(<150 行)
│       └── __tests__/
│           ├── withTracking.test.ts
│           └── useTracking.test.ts
│
├── services/
│   └── tracking/
│       ├── tracking-service.ts         # 核心上报服务(<500 行)
│       ├── tracking-batch-service.ts   # 批量上报逻辑(<300 行)
│       ├── tracking-storage-service.ts # 缓存管理(<250 行)
│       ├── tracking-utils.ts           # 工具函数(<300 行)
│       └── __tests__/
│           ├── tracking-service.test.ts
│           ├── tracking-batch-service.test.ts
│           ├── tracking-storage-service.test.ts
│           └── tracking-utils.test.ts
│
├── types/
│   └── tracking.types.ts               # 类型定义(<150 行)
│
└── drawnix.tsx                         # 集成 withTracking 插件

apps/web/src/
└── (可选)配置文件,用于初始化埋点系统配置

tests/e2e/
└── tracking/
    ├── declarative-tracking.spec.ts    # 声明式埋点 E2E 测试
    └── auto-tracking.spec.ts           # 自动埋点 E2E 测试

Structure Decision: 采用 Monorepo (Option 3 变体),遵循现有 Drawnix 架构。核心逻辑在 packages/drawnix/src/services/tracking/,插件接口在 packages/drawnix/src/plugins/tracking/,类型定义在 packages/drawnix/src/types/。这种结构与现有的 generation-api-service.ts、video-api-service.ts、chat-service.ts 等服务保持一致,易于维护和测试。

Complexity Tracking

Fill ONLY if Constitution Check has violations that must be justified

本功能无宪章违规,所有设计符合项目约束。

7.2 KiB Raw Blame History