Jammy/TrueGrowth
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
main
TrueGrowth/specs/005-declarative-tracking/tasks.md

18 KiB
Raw Permalink Blame History

Tasks: 声明式埋点上报系统

Input: Design documents from /specs/005-declarative-tracking/ Prerequisites: plan.md (required), spec.md (required for user stories), research.md, data-model.md, contracts/

Tests: Unit tests and E2E tests included as specified in plan.md (target >80% coverage)

Organization: Tasks are grouped by user story to enable independent implementation and testing of each story.

Format: [ID] [P?] [Story] Description

  • [P]: Can run in parallel (different files, no dependencies)
  • [Story]: Which user story this task belongs to (e.g., US1, US2, US3, US4)
  • Include exact file paths in descriptions

Path Conventions

  • Monorepo: packages/drawnix/src/ for implementation
  • Tests: packages/drawnix/src/services/tracking/__tests__/ for unit tests
  • E2E: tests/e2e/tracking/ for end-to-end tests
  • File size limit: <500 lines per file (constitution requirement)

Phase 1: Setup (Shared Infrastructure)

Purpose: Project initialization and basic structure

  • T001 Create directory structure at packages/drawnix/src/plugins/tracking/ and packages/drawnix/src/services/tracking/
  • T002 [P] Create TypeScript type definitions in packages/drawnix/src/types/tracking.types.ts (<150 lines)
  • T003 [P] Configure Vite environment variable for version injection in vite.config.ts
  • T004 [P] Create tracking configuration defaults in packages/drawnix/src/services/tracking/tracking-config.ts (<150 lines)

Phase 2: Foundational (Blocking Prerequisites)

Purpose: Core infrastructure that MUST be complete before ANY user story can be implemented

⚠️ CRITICAL: No user story work can begin until this phase is complete

  • T005 Implement Umami adapter wrapper in packages/drawnix/src/services/tracking/umami-adapter.ts (<200 lines)
  • T006 [P] Implement batch upload service in packages/drawnix/src/services/tracking/tracking-batch-service.ts (<300 lines)
  • T007 [P] Implement storage/cache service using localforage in packages/drawnix/src/services/tracking/tracking-storage-service.ts (<250 lines)
  • T008 [P] Implement debounce utility using WeakMap in packages/drawnix/src/services/tracking/tracking-utils.ts (debounce logic, <100 lines)
  • T009 [P] Implement element selector utilities in packages/drawnix/src/services/tracking/tracking-utils.ts (selector matching, <100 lines)
  • T010 [P] Implement event name generation utility in packages/drawnix/src/services/tracking/tracking-utils.ts (auto-event naming, <100 lines)
  • T011 Unit test for Umami adapter in packages/drawnix/src/services/tracking/tests/umami-adapter.test.ts
  • T012 [P] Unit test for batch service in packages/drawnix/src/services/tracking/tests/tracking-batch-service.test.ts
  • T013 [P] Unit test for storage service in packages/drawnix/src/services/tracking/tests/tracking-storage-service.test.ts
  • T014 [P] Unit test for utilities in packages/drawnix/src/services/tracking/tests/tracking-utils.test.ts

Checkpoint: Foundation ready - user story implementation can now begin in parallel

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

Goal: 开发者通过 track="event_name" 属性为元素添加点击埋点,系统自动上报事件到 Umami,包含元数据(version, url, timestamp, sessionId)

Independent Test: 在任意可点击元素上添加 track 属性,点击后在控制台或 Umami 面板看到事件上报

Implementation for User Story 1

  • T015 [P] [US1] Implement core tracking service class with RxJS state management in packages/drawnix/src/services/tracking/tracking-service.ts (<500 lines)
  • T016 [P] [US1] Implement event delegation for click events in tracking-service.ts (event listener setup, track attribute parsing)
  • T017 [US1] Implement metadata injection logic in tracking-service.ts (version from env, url from location.href, timestamp, sessionId generation)
  • T018 [US1] Implement event capture and queueing flow in tracking-service.ts (capture → debounce → enqueue to batch)
  • T019 [US1] Implement event bubbling prevention for nested elements in tracking-service.ts (stopPropagation for innermost track element)
  • T020 [US1] Integrate batch service with tracking service in tracking-service.ts (call batchService.enqueue)
  • T021 [US1] Implement beforeunload handler for navigator.sendBeacon in tracking-service.ts
  • T022 [US1] Add logging (console.warn in dev, error logs in prod) in tracking-service.ts
  • T023 [P] [US1] Unit test for track attribute parsing in packages/drawnix/src/services/tracking/tests/tracking-service.test.ts
  • T024 [P] [US1] Unit test for metadata injection in packages/drawnix/src/services/tracking/tests/tracking-service.test.ts
  • T025 [P] [US1] Unit test for event bubbling prevention in packages/drawnix/src/services/tracking/tests/tracking-service.test.ts
  • T026 [P] [US1] Unit test for debounce integration in packages/drawnix/src/services/tracking/tests/tracking-service.test.ts

Checkpoint: At this point, basic click tracking with track attribute should work - test by adding track="test_event" to a button and clicking

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

Goal: 开发者通过 track-params='{"key": "value"}' 属性为事件添加自定义参数,系统解析并包含在上报数据中

Independent Test: 在元素上同时添加 track 和 track-params,点击后验证上报数据包含自定义参数

Implementation for User Story 2

  • T027 [P] [US2] Implement track-params parsing logic in packages/drawnix/src/services/tracking/tracking-service.ts (JSON.parse with try-catch)
  • T028 [P] [US2] Implement JSON validation and error handling in tracking-service.ts (catch parse errors, log warnings)
  • T029 [US2] Integrate track-params with event creation in tracking-service.ts (merge params into TrackEvent.params)
  • T030 [US2] Add dev/prod logging for invalid JSON in tracking-service.ts (console.warn in dev, error log in prod)
  • T031 [P] [US2] Unit test for valid JSON parsing in packages/drawnix/src/services/tracking/tests/tracking-service.test.ts
  • T032 [P] [US2] Unit test for invalid JSON handling in packages/drawnix/src/services/tracking/tests/tracking-service.test.ts
  • T033 [P] [US2] Unit test for params integration with events in packages/drawnix/src/services/tracking/tests/tracking-service.test.ts

Checkpoint: track-params support complete - test with track-params='{"userId": "123"}' and verify in Umami

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

Goal: 启用自动埋点模式后,系统自动识别可点击元素(button, a, role="button", onClick handlers)并生成事件名,但排除nav/header/footer和data-track-ignore元素

Independent Test: 启用 autoTrack 配置,点击未添加 track 属性的 button,验证自动生成事件名并上报

Implementation for User Story 3

  • T034 [P] [US3] Implement shouldAutoTrack selector logic in packages/drawnix/src/services/tracking/tracking-utils.ts (CSS selector + React Fiber check)
  • T035 [P] [US3] Implement element exclusion logic in tracking-utils.ts (check nav/header/footer/data-track-ignore)
  • T036 [P] [US3] Implement auto event name generation in tracking-utils.ts (based on text content, ID, aria-label)
  • T037 [US3] Integrate auto-tracking with event delegation in packages/drawnix/src/services/tracking/tracking-service.ts (check autoTrack config, call shouldAutoTrack)
  • T038 [US3] Add auto-tracking configuration support in tracking-service.ts (autoTrack flag, excludedSelectors)
  • T039 [US3] Prioritize manual track over auto-track in tracking-service.ts (check for track attribute first)
  • T040 [P] [US3] Unit test for shouldAutoTrack logic in packages/drawnix/src/services/tracking/tests/tracking-utils.test.ts
  • T041 [P] [US3] Unit test for exclusion logic in packages/drawnix/src/services/tracking/tests/tracking-utils.test.ts
  • T042 [P] [US3] Unit test for event name generation in packages/drawnix/src/services/tracking/tests/tracking-utils.test.ts
  • T043 [P] [US3] Unit test for auto-track integration in packages/drawnix/src/services/tracking/tests/tracking-service.test.ts

Checkpoint: Auto-tracking complete - test with autoTrack: true config and verify 95%+ clickable elements are tracked

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

Goal: 支持 track-hover, track-focus 等属性,监听 hover/focus 事件并上报

Independent Test: 在元素上添加 track-hover="hover_event",鼠标悬停时验证事件上报

Implementation for User Story 4

  • T044 [P] [US4] Implement MutationObserver setup in packages/drawnix/src/services/tracking/tracking-service.ts (<100 lines, only when track-hover/focus enabled)
  • T045 [P] [US4] Implement track-hover attribute support in tracking-service.ts (parse track-hover, attach mouseenter listener)
  • T046 [P] [US4] Implement track-focus attribute support in tracking-service.ts (parse track-focus, attach focus listener with capture)
  • T047 [US4] Implement event listener attachment logic in tracking-service.ts (WeakMap to track attached listeners, prevent duplicates)
  • T048 [US4] Integrate multi-event types with existing tracking flow in tracking-service.ts (support eventType in TrackEvent.metadata)
  • T049 [P] [US4] Unit test for MutationObserver logic in packages/drawnix/src/services/tracking/tests/tracking-service.test.ts
  • T050 [P] [US4] Unit test for track-hover support in packages/drawnix/src/services/tracking/tests/tracking-service.test.ts
  • T051 [P] [US4] Unit test for track-focus support in packages/drawnix/src/services/tracking/tests/tracking-service.test.ts
  • T052 [P] [US4] Unit test for listener deduplication in packages/drawnix/src/services/tracking/tests/tracking-service.test.ts

Checkpoint: Multi-event support complete - test track-hover and track-focus attributes

Phase 7: Polish & Cross-Cutting Concerns

Purpose: Plugin integration, React hooks, E2E tests, documentation

  • T053 [P] Implement withTracking plugin wrapper in packages/drawnix/src/plugins/tracking/withTracking.ts (<200 lines)
  • T054 [P] Implement useTracking React hook in packages/drawnix/src/plugins/tracking/hooks/useTracking.ts (<150 lines)
  • T055 [P] Create plugin index exports in packages/drawnix/src/plugins/tracking/index.ts
  • T056 Integrate withTracking into Drawnix in packages/drawnix/src/drawnix.tsx (add withTracking to plugin composition)
  • T057 [P] Unit test for withTracking plugin in packages/drawnix/src/plugins/tracking/tests/withTracking.test.ts
  • T058 [P] Unit test for useTracking hook in packages/drawnix/src/plugins/tracking/tests/useTracking.test.ts
  • T059 [P] E2E test for declarative tracking (track attribute) in tests/e2e/tracking/declarative-tracking.spec.ts
  • T060 [P] E2E test for track-params in tests/e2e/tracking/declarative-tracking.spec.ts
  • T061 [P] E2E test for auto-tracking in tests/e2e/tracking/auto-tracking.spec.ts
  • T062 [P] E2E test for multi-event types in tests/e2e/tracking/multi-event-types.spec.ts
  • T063 [P] E2E test for batch upload and caching in tests/e2e/tracking/batch-and-cache.spec.ts
  • T064 [P] Update quickstart.md with final examples and troubleshooting
  • T065 [P] Verify file size compliance (all files <500 lines)
  • T066 Run full test suite and verify >80% coverage
  • T067 Run quickstart.md validation (follow guide end-to-end)

Dependencies & Execution Order

Phase Dependencies

  • Setup (Phase 1): No dependencies - can start immediately
  • Foundational (Phase 2): Depends on Setup completion - BLOCKS all user stories
  • User Stories (Phase 3-6): All depend on Foundational phase completion
    • User stories can then proceed in parallel (if staffed)
    • Or sequentially in priority order (P1 → P2 → P3 → P3)
  • Polish (Phase 7): Depends on all user stories being complete

User Story Dependencies

  • User Story 1 (P1) - Basic Tracking: Can start after Foundational (Phase 2) - No dependencies on other stories
  • User Story 2 (P2) - track-params: Can start after Foundational (Phase 2) - Extends US1 but independently testable
  • User Story 3 (P3) - Auto-tracking: Can start after Foundational (Phase 2) - Uses US1 infrastructure but independently testable
  • User Story 4 (P3) - Multi-events: Can start after Foundational (Phase 2) - Uses US1 infrastructure but independently testable

Within Each User Story

  • Tests can be written in parallel with implementation (TDD approach)
  • Utility functions before service integration
  • Core logic before edge case handling
  • Unit tests before moving to next user story

Parallel Opportunities

  • Phase 1: T002, T003, T004 can run in parallel
  • Phase 2: T006, T007, T008, T009, T010 can run in parallel (after T005 Umami adapter)
  • Phase 2 Tests: T011, T012, T013, T014 can run in parallel
  • US1: T015, T016 can run in parallel; T023, T024, T025, T026 tests can run in parallel
  • US2: T027, T028 can run in parallel; T031, T032, T033 tests can run in parallel
  • US3: T034, T035, T036 can run in parallel; T040, T041, T042, T043 tests can run in parallel
  • US4: T044, T045, T046 can run in parallel; T049, T050, T051, T052 tests can run in parallel
  • Polish: T053, T054, T055, T057, T058, T059, T060, T061, T062, T063, T064, T065 can run in parallel

Parallel Example: User Story 1

# Launch all utility implementations for US1 together:
Task T015: "Implement core tracking service class with RxJS state management"
Task T016: "Implement event delegation for click events"

# Launch all unit tests for US1 together:
Task T023: "Unit test for track attribute parsing"
Task T024: "Unit test for metadata injection"
Task T025: "Unit test for event bubbling prevention"
Task T026: "Unit test for debounce integration"

Parallel Example: Foundational Phase

# Launch all service implementations in parallel:
Task T006: "Implement batch upload service"
Task T007: "Implement storage/cache service using localforage"
Task T008: "Implement debounce utility using WeakMap"
Task T009: "Implement element selector utilities"
Task T010: "Implement event name generation utility"

# Launch all tests in parallel:
Task T011: "Unit test for Umami adapter"
Task T012: "Unit test for batch service"
Task T013: "Unit test for storage service"
Task T014: "Unit test for utilities"

Implementation Strategy

MVP First (User Story 1 Only)

  1. Complete Phase 1: Setup (T001-T004)
  2. Complete Phase 2: Foundational (T005-T014) - CRITICAL
  3. Complete Phase 3: User Story 1 (T015-T026)
  4. STOP and VALIDATE: Test basic click tracking independently
  5. Deploy/demo if ready - developers can use track="event_name" attribute

MVP Deliverable: Basic declarative tracking with track attribute, batch upload, caching, metadata injection

Incremental Delivery

  1. Sprint 1: Setup + Foundational → Foundation ready
  2. Sprint 2: Add User Story 1 → Test independently → Deploy (MVP!)
  3. Sprint 3: Add User Story 2 → Test independently → Deploy (track-params support)
  4. Sprint 4: Add User Story 3 → Test independently → Deploy (auto-tracking)
  5. Sprint 5: Add User Story 4 → Test independently → Deploy (multi-event types)
  6. Sprint 6: Polish → Full E2E tests → Production release

Parallel Team Strategy

With multiple developers:

  1. Team completes Setup + Foundational together (T001-T014)
  2. Once Foundational is done:
    • Developer A: User Story 1 (T015-T026)
    • Developer B: User Story 2 (T027-T033) - waits for US1 completion
    • Developer C: User Story 3 (T034-T043) - can start in parallel
    • Developer D: User Story 4 (T044-T052) - can start in parallel
  3. Polish phase (T053-T067) - team collaboration

Validation Checkpoints

After Phase 2 (Foundational)

  • ✅ Umami adapter can send test events
  • ✅ Batch service queues and flushes events correctly
  • ✅ Storage service persists and retrieves cached events
  • ✅ Debounce prevents duplicate events within 500ms
  • ✅ All unit tests pass (>80% coverage for foundational code)

After Phase 3 (User Story 1)

  • ✅ Clicking element with track="test_event" uploads event to Umami
  • ✅ Event includes metadata: version, url, timestamp, sessionId
  • ✅ Nested elements with track attributes only report innermost element
  • ✅ Events batch every 10 events or 5 seconds
  • ✅ beforeunload sends remaining events with sendBeacon
  • ✅ All US1 unit tests pass

After Phase 4 (User Story 2)

  • ✅ track-params='{"key": "value"}' correctly parses and includes in event
  • ✅ Invalid JSON logs warning in dev, error in prod, continues without params
  • ✅ Events without track-params work normally
  • ✅ All US2 unit tests pass

After Phase 5 (User Story 3)

  • ✅ autoTrack: true auto-tracks 95%+ clickable elements
  • ✅ Elements in nav/header/footer are excluded
  • ✅ data-track-ignore prevents auto-tracking
  • ✅ Auto-generated event names are meaningful (based on text/ID/aria-label)
  • ✅ Manual track attributes override auto-tracking
  • ✅ All US3 unit tests pass

After Phase 6 (User Story 4)

  • ✅ track-hover="hover_event" reports on mouseenter
  • ✅ track-focus="focus_event" reports on focus
  • ✅ MutationObserver attaches listeners to dynamic elements
  • ✅ WeakMap prevents duplicate listener attachment
  • ✅ All US4 unit tests pass

After Phase 7 (Polish)

  • ✅ withTracking plugin integrates into Drawnix
  • ✅ useTracking hook provides React-friendly API
  • ✅ All E2E tests pass (declarative, auto, multi-event, batch, cache)
  • ✅ Overall test coverage >80%
  • ✅ All files comply with <500 line limit
  • ✅ quickstart.md validated end-to-end
  • ✅ Performance: <2% page load overhead, 60%+ network request reduction

Notes

  • [P] tasks = different files, no dependencies - can run in parallel
  • [Story] label (US1, US2, US3, US4) maps task to specific user story
  • Each user story is independently completable and testable
  • All unit tests use Jest + React Testing Library
  • All E2E tests use Playwright
  • Constitution compliance: all files <500 lines (verified in T065)
  • Stop at any checkpoint to validate story independently before proceeding
  • TypeScript strict mode enforced throughout
  • Follow existing Drawnix patterns (services/, plugins/, RxJS)
Reference in New Issue View Git Blame Copy Permalink