TrueGrowth/specs/005-declarative-tracking/spec.md

Feature Specification: 声明式埋点上报系统

Feature Branch: 005-declarative-tracking Created: 2025-12-05 Status: Draft Input: User description: "设计一种声明式埋点上报的方案,比如在元素上加属性track="xxx",点击时就会自动上报xxx事件,并给所有可点击元素加上埋点。"

Clarifications

Session 2025-12-05

• Q: 当元素嵌套且都有 track 属性时的事件冒泡策略? → A: 仅上报最内层(最具体的)元素的 track 事件,阻止向外冒泡
• Q: 缓存失败事件的保留策略(数量和时间限制)? → A: 缓存最多 100 个失败事件,保留时间不超过 1 小时,超过后自动丢弃最旧的事件
• Q: 生产环境的可观测性和日志级别要求? → A: 生产环境输出错误级别日志(上报失败、缓存溢出等),支持通过配置启用调试模式
• Q: 事件批量上报策略(减少网络开销)? → A: 批量上报:累积最多 10 个事件或等待 5 秒后统一上报,以先到达的条件为准
• Q: 自动埋点的元素选择范围(避免数据噪音)? → A: 追踪原生交互元素 + 具有 onClick 事件处理器的元素 + 具有 role="button/link" 的元素,但排除导航、工具栏、页脚等特定区域

补充需求: 在现有的 Umami 上报基础上增加项目版本号(version)以及当前页面地址(location.href)的参数

User Scenarios & Testing (mandatory)

User Story 1 - 开发者快速添加点击埋点 (Priority: P1)

开发者在开发新功能时,希望通过简单的声明式属性(如 track="button_click_save")给可点击元素添加埋点,当用户点击该元素时,系统自动上报 button_click_save 事件,无需编写额外的事件处理代码。

Why this priority: 这是核心功能,提供最基本的声明式埋点能力,可立即为现有和新增的可点击元素提供埋点支持,降低埋点接入成本。

Independent Test: 开发者在任意可点击元素(如 button、div 等)上添加 track 属性后,点击该元素即可在控制台或上报服务中看到对应事件被记录。

Acceptance Scenarios:

1. Given 开发者在 button 元素上添加 track="save_button" 属性, When 用户点击该按钮, Then 系统自动上报 save_button 事件
2. Given 开发者在 div 元素上添加 track="card_click" 属性, When 用户点击该 div, Then 系统自动上报 card_click 事件
3. Given 元素上未添加 track 属性, When 用户点击该元素, Then 系统不上报任何事件

---

User Story 2 - 上报事件时携带额外参数 (Priority: P2)

开发者希望在上报事件时携带额外的上下文信息(如元素ID、状态、用户操作等),通过额外的属性(如 track-params='{"id": "123", "type": "save"}')将参数传递给上报系统。

Why this priority: 增强埋点数据的丰富度,帮助数据分析团队更好地理解用户行为,是基础埋点功能的有效补充。

Independent Test: 开发者在元素上同时添加 track 和 track-params 属性后,点击元素时上报的事件数据中包含指定的参数信息。

Acceptance Scenarios:

1. Given 元素上有 track="item_click" 和 track-params='{"item_id": "123"}' 属性, When 用户点击元素, Then 上报事件包含 event: "item_click" 和 params: {item_id: "123"}
2. Given 元素上有 track="button_click" 但无 track-params 属性, When 用户点击元素, Then 上报事件仅包含事件名,无额外参数
3. Given track-params 包含无效 JSON 格式, When 用户点击元素, Then 系统上报事件但忽略无效参数,并在开发环境下输出警告

---

User Story 3 - 批量为可点击元素自动添加埋点 (Priority: P3)

开发者或产品经理希望系统能够自动识别所有可点击元素(如 button、a、具有 onClick 的元素等),并自动为它们添加默认埋点(如基于元素文本内容、ID 或 class 生成事件名),减少手动添加 track 属性的工作量。

Why this priority: 提升埋点覆盖率,确保关键交互都被记录,但需要在基础功能稳定后再实现,避免过度自动化导致数据噪音。

Independent Test: 开发者启用"自动埋点"配置后,页面上所有未手动添加 track 属性的可点击元素在被点击时自动上报事件(事件名基于元素特征生成)。

Acceptance Scenarios:

1. Given 自动埋点功能已启用且 button 元素未添加 track 属性, When 用户点击该 button, Then 系统基于 button 文本或 ID 自动生成事件名并上报(如 auto_click_保存按钮)
2. Given 元素已手动添加 track 属性, When 用户点击该元素, Then 系统使用手动指定的事件名,不使用自动生成的事件名
3. Given 自动埋点功能已禁用, When 用户点击未添加 track 属性的元素, Then 系统不上报任何事件
4. Given 自动埋点功能已启用且元素位于导航栏(nav)或页脚(footer)内, When 用户点击该元素, Then 系统不自动上报事件(除非元素有手动 track 属性)
5. Given 元素具有 data-track-ignore 属性, When 用户点击该元素, Then 系统不自动上报事件(即使符合自动埋点条件)

---

User Story 4 - 支持多种交互事件类型的埋点 (Priority: P3)

开发者希望除了点击事件外,还能对其他交互事件(如 hover、focus、input 等)进行声明式埋点,使用类似 track-hover="hover_item" 或 track-focus="focus_input" 的属性。

Why this priority: 扩展埋点能力,支持更丰富的用户行为分析,但非核心功能,可在基础点击埋点稳定后扩展。

Independent Test: 开发者在元素上添加 track-hover 或 track-focus 属性后,对应的 hover 或 focus 事件触发时系统自动上报事件。

Acceptance Scenarios:

1. Given 元素上有 track-hover="card_hover" 属性, When 用户鼠标悬停在元素上, Then 系统上报 card_hover 事件
2. Given input 元素上有 track-focus="input_focus" 属性, When 用户聚焦到该 input, Then 系统上报 input_focus 事件
3. Given 元素同时有 track 和 track-hover 属性, When 用户点击和悬停, Then 系统分别上报对应的点击和悬停事件

---

Edge Cases

• 当元素动态添加或删除时: 系统需要支持动态元素的埋点监听,使用 MutationObserver 或事件委托机制确保新增元素的埋点生效
• 当快速连续点击同一元素时: 系统需要防抖或节流机制,避免短时间内重复上报相同事件
• 当自动埋点遇到排除区域内的元素时: 系统必须检查元素是否位于 nav、header、footer 等排除区域内,或是否具有 data-track-ignore 属性,并跳过自动埋点
• 当上报服务不可用时: 系统缓存最多 100 个失败事件,保留时间不超过 1 小时,超过限制后自动丢弃最旧的事件
• 当 track 属性值为空或无效时: 系统忽略该元素的埋点,不上报事件,开发环境下输出警告
• 当元素嵌套且都有 track 属性时: 系统仅上报最内层(最具体的)元素的 track 事件,阻止事件向外层父元素冒泡,避免重复上报
• 当页面卸载时: 系统需要使用 navigator.sendBeacon 或类似机制确保页面关闭前的事件能够成功上报

Requirements (mandatory)

Functional Requirements

• FR-001: 系统必须支持通过 HTML 属性 track="event_name" 声明式地为元素添加点击埋点
• FR-002: 系统必须在元素被点击时自动上报 track 属性指定的事件名
• FR-003: 当嵌套元素都有 track 属性时,系统必须仅上报最内层元素的事件,并阻止事件向外层冒泡
• FR-004: 系统必须支持通过 track-params 属性为上报事件携带额外的 JSON 格式参数
• FR-005: 系统必须能够识别并监听所有可点击元素类型(button、a、div、span 等具有 onClick 或 cursor:pointer 的元素)
• FR-006: 系统必须支持自动埋点模式,为符合条件的可点击元素自动生成并上报事件
• FR-006a: 自动埋点必须追踪:原生交互元素(button、a、input、select)、具有 onClick 事件处理器的元素、具有 role="button" 或 role="link" 的元素
• FR-006b: 自动埋点必须排除特定区域的元素:导航栏(nav、header)、工具栏、页脚(footer)、以及标记为 data-track-ignore 的元素
• FR-007: 系统必须提供配置选项,允许启用/禁用自动埋点功能
• FR-008: 系统必须支持动态添加的元素的埋点监听(通过事件委托或 MutationObserver)
• FR-009: 系统必须在 track-params 格式无效时忽略参数,在开发环境下输出警告,在生产环境下记录错误日志
• FR-009a: 系统必须在生产环境输出错误级别日志,包括上报失败、缓存溢出、API 错误等关键问题
• FR-009b: 系统必须支持通过配置启用调试模式,在调试模式下输出详细日志(事件触发、参数解析、防抖等)
• FR-010: 系统必须提供防抖机制,避免短时间内(如 500ms)重复上报相同元素的相同事件
• FR-011: 系统必须支持批量上报事件,累积最多 10 个事件或等待 5 秒后统一上报,以先到达的条件为准
• FR-011a: 系统必须在页面卸载时立即上报当前批次中的所有待上报事件(不等待批量阈值)
• FR-012: 系统必须在上报失败时进行重试,重试次数和间隔可配置
• FR-013: 系统必须缓存失败的上报事件,最多保存 100 个事件,保留时间不超过 1 小时
• FR-014: 系统必须在缓存超过数量或时间限制时,自动丢弃最旧的失败事件
• FR-015: 系统必须支持自定义上报 API 端点,通过配置指定上报地址
• FR-016: 系统必须在页面卸载时使用 navigator.sendBeacon 确保事件成功上报
• FR-017: 系统必须在每个上报事件中包含以下元数据:时间戳(timestamp)、当前页面地址(location.href)、项目版本号(version)、用户会话ID(session_id)
• FR-017a: 项目版本号(version)必须从应用配置或 package.json 中读取,确保版本信息准确
• FR-017b: 页面地址(location.href)必须在事件触发时实时获取,确保 SPA 应用中页面切换后的地址正确
• FR-018: 系统必须支持扩展其他事件类型(hover、focus 等)的声明式埋点(通过 track-hover、track-focus 等属性)
• FR-019: 系统必须在自动埋点模式下基于元素特征(文本内容、ID、aria-label 等)生成有意义的事件名

Key Entities

• TrackEvent: 上报的埋点事件,包含:
  • event_name: 事件名称(手动指定或自动生成)
  • params: 事件参数(来自 track-params 属性,JSON 格式)
  • metadata: 元数据对象,包含:
    • timestamp: 事件触发时间戳
    • url: 当前页面完整地址(location.href)
    • version: 项目版本号(从配置读取)
    • session_id: 用户会话标识
    • user_agent: 浏览器 User-Agent(可选)
    • viewport: 视口尺寸(可选)
• TrackConfig: 埋点系统配置,包含是否启用自动埋点(auto_track)、上报 API 端点(api_endpoint)、防抖时间(debounce_time)、重试策略(retry_policy)、缓存上限(max_cache_size: 100)、缓存保留时间(cache_ttl: 1小时)、日志级别(log_level: error|debug)、批量上报配置(batch_size: 10, batch_timeout: 5秒)、自动埋点排除区域(excluded_selectors: ['nav', 'header', 'footer', '[data-track-ignore]'])等
• TrackedElement: 被监听的元素,包含元素引用、事件名、事件参数、事件类型(click、hover 等)

Success Criteria (mandatory)

Measurable Outcomes

• SC-001: 开发者为元素添加 track 属性后,点击元素时 100% 的情况下成功触发事件上报
• SC-002: 自动埋点功能启用后,页面上至少 95% 的可点击元素在被点击时自动上报事件
• SC-003: 批量上报机制将网络请求数量减少至少 60%(相比单个事件独立上报)
• SC-004: 埋点系统的性能开销不超过页面总加载时间的 2%,且不影响用户交互响应速度
• SC-005: 在开发环境下,无效的 track-params 格式能够在控制台输出清晰的警告信息,帮助开发者快速定位问题
• SC-006: 埋点数据覆盖率从当前手动埋点的 X% 提升到 90% 以上(通过自动埋点功能)
• SC-007: 开发者反馈埋点接入时间从平均 30 分钟降低到 5 分钟以内(通过声明式属性简化流程)

Assumptions

• 假设项目已经集成了 Umami 分析服务作为埋点上报的后端
• 假设 Umami API 接受 JSON 格式的事件数据,并支持自定义事件属性
• 假设现有的 Umami 上报机制可以扩展,增加 version 和 location.href 参数
• 假设开发环境能够访问 console API 用于输出警告和调试信息
• 假设浏览器支持 MutationObserver、navigator.sendBeacon 等现代 Web API
• 假设自动埋点生成的事件名遵循项目现有的命名规范(如 auto_click_ 前缀 + 元素特征)
• 假设埋点数据不包含敏感用户信息(如密码、个人身份信息等),符合隐私合规要求

Dependencies

• 依赖 Umami 分析服务的上报 API(需要确认具体的事件上报接口、数据格式要求、以及如何扩展自定义参数)
• 依赖现有的 Umami 客户端 SDK 或上报逻辑,需要在此基础上增加 version 和 location.href 参数
• 依赖项目配置或 package.json 文件,用于读取项目版本号(version)
• 依赖浏览器对 MutationObserver、navigator.sendBeacon 的支持(需考虑降级方案)
• 依赖项目的存储服务(如 localforage 或 localStorage)用于缓存未成功上报的事件