mirror of
https://github.com/sstent/FitTrack_GarminSync.git
synced 2026-01-25 16:41:41 +00:00
222 lines
10 KiB
Markdown
222 lines
10 KiB
Markdown
# Tasks: IntialSpecV2
|
|
|
|
**Input**: Design documents from `/specs/002-intialspecv2/`
|
|
**Prerequisites**: plan.md (required), spec.md (required for user stories), research.md, contracts/
|
|
|
|
**Tests**: The examples below include test tasks. Tests are OPTIONAL - only include them if explicitly requested in the feature specification.
|
|
|
|
**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)
|
|
- Include exact file paths in descriptions
|
|
|
|
## Path Conventions
|
|
- **Web app**: `backend/src/`, `frontend/src/`
|
|
|
|
## Phase 1: Setup (Shared Infrastructure)
|
|
|
|
**Purpose**: Project initialization and basic structure
|
|
|
|
- [X] T001 Create project structure (`backend/`, `frontend/`, `tests/`)
|
|
- [X] T002 Initialize Python backend project with dependencies (FastAPI, `garth`, `garminconnect`) in `backend/`
|
|
- [X] T003 [P] Configure linting and formatting tools for Python in `backend/`
|
|
- [X] T004 [P] Setup Docker and Docker Compose for development environment
|
|
|
|
---
|
|
|
|
## 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
|
|
|
|
- [X] T005 Setup CentralDB integration (FR-016, FR-017)
|
|
- [X] Define CentralDB client/SDK generation from `DB_API_SPEC.json`
|
|
- [X] Implement CentralDB client in `backend/src/services/central_db_service.py`
|
|
|
|
- [X] T007 Implement authentication/authorization framework (FR-001, FR-012)
|
|
- [X] Create User authentication service in `backend/src/services/auth_service.py` to use CentralDB for authentication
|
|
- [X] Implement Garmin Connect authentication flow using `garth` and `garminconnect` (FR-019)
|
|
- [X] T008 Setup API routing and middleware structure (FR-013: default to port 8001)
|
|
- [X] Create basic FastAPI application setup in `backend/src/main.py`
|
|
- [X] Implement configuration management (YAML/Environment variables) (FR-014)
|
|
- [X] T009 Configure error handling and logging infrastructure (FR-010)
|
|
- [X] T010 Implement in-memory background job processing mechanism (FR-008)
|
|
- [X] T011 Implement rate limiting for external API calls (FR-009)
|
|
- [X] T012 Integrate `garth` and `garminconnect` libraries (FR-019)
|
|
- [X] T013 Reuse code/logic from @GarminAnalyser.md (FR-015)
|
|
|
|
**Checkpoint**: Foundation ready - user story implementation can now begin in parallel
|
|
|
|
---
|
|
|
|
## Phase 3: User Story 1 - Garmin Connect Activity Synchronization (Priority: P1) 🎯 MVP
|
|
|
|
**Goal**: Synchronize Garmin Connect activities and store them as FIT/GPX/TCX files in CentralDB.
|
|
|
|
**Independent Test**: Authenticate with Garmin Connect, trigger an activity sync via `POST /api/sync/garmin/activities`, and then verify that activity files are correctly stored in CentralDB, with only new or updated activities downloaded.
|
|
|
|
### Implementation for User Story 1
|
|
|
|
|
|
- [X] T015 [P] [US1] Define `SyncJob` Pydantic model for in-memory job tracking
|
|
- [X] T016 [US1] Implement Garmin Activity Service for downloading activities (`backend/src/services/garmin_activity_service.py`) (FR-002)
|
|
- [X] T017 [US1] Implement CentralDB storage for activity files (`backend/src/services/central_db_service.py`) (FR-003)
|
|
- [X] T018 [US1] Implement activity synchronization logic (handling new/updated activities) (FR-002)
|
|
- [X] T019 [US1] Create `POST /api/sync/garmin/activities` endpoint (`backend/src/api/garmin_sync.py`) (FR-006)
|
|
- [X] T020 [US1] Implement background job for activity synchronization (FR-008)
|
|
- [X] T021 [US1] Add error handling and retry logic for activity sync (FR-010)
|
|
- [X] T022 [US1] Update in-memory `SyncJob` status and details (FR-011)
|
|
|
|
**Checkpoint**: At this point, User Story 1 should be fully functional and testable independently
|
|
|
|
---
|
|
|
|
## Phase 4: User Story 2 - Garmin Connect Health Metrics Synchronization (Priority: P2)
|
|
|
|
**Goal**: Synchronize Garmin Connect health metrics and store them in CentralDB.
|
|
|
|
**Independent Test**: Authenticate with Garmin Connect, trigger a sync, and verify that health metrics (e.g., heart rate, sleep data) are correctly synchronized and stored in CentralDB.
|
|
|
|
### Implementation for User Story 2
|
|
|
|
|
|
- [X] T024 [US2] Implement Garmin Health Metrics Service for downloading metrics (`backend/src/services/garmin_health_service.py`) (FR-004)
|
|
- [X] T025 [US2] Implement CentralDB storage for health metrics (`backend/src/services/central_db_service.py`) (FR-004)
|
|
- [X] T026 [US2] Implement health metrics synchronization logic
|
|
- [X] T027 [US2] Integrate health metrics sync into in-memory `SyncJob` mechanism
|
|
- [X] T028 [US2] Add error handling and retry logic for health metrics sync (FR-010)
|
|
|
|
**Checkpoint**: At this point, User Stories 1 AND 2 should both work independently
|
|
|
|
---
|
|
|
|
## Phase 5: User Story 3 - Garmin Workout Upload (Priority: P2)
|
|
|
|
**Goal**: Allow users to upload workouts from the application to Garmin Connect.
|
|
|
|
**Independent Test**: Create a workout in the application, initiate its upload to Garmin Connect, and then verify that the workout appears correctly on the user's Garmin Connect account.
|
|
|
|
### Implementation for User Story 3
|
|
|
|
|
|
- [X] T030 [US3] Implement Garmin Workout Service for uploading workouts (`backend/src/services/garmin_workout_service.py`) (FR-005)
|
|
- [X] T031 [US3] Create `POST /api/sync/garmin/workouts` endpoint (`backend/src/api/garmin_sync.py`) (FR-005)
|
|
- [X] T032 [US3] Implement background job for workout upload (FR-008)
|
|
- [X] T033 [US3] Add error handling and retry logic for workout upload (FR-010)
|
|
- [X] T034 [US3] Update in-memory `SyncJob` status and details for workout uploads
|
|
|
|
**Checkpoint**: All user stories should now be independently functional
|
|
|
|
---
|
|
|
|
## Phase 6: User Story 4 - Check Sync Status (Priority: P3)
|
|
|
|
**Goal**: Provide essential feedback to the user on ongoing and completed synchronization operations.
|
|
|
|
**Independent Test**: Trigger a synchronization process, then query the `/api/sync/status` endpoint to verify that it accurately reflects the ongoing or completed status of the sync.
|
|
|
|
### Implementation for User Story 4
|
|
|
|
- [X] T035 [US4] Implement `SyncStatusService` to query in-memory `SyncJob` records (`backend/src/services/sync_status_service.py`)
|
|
- [X] T036 [US4] Create `GET /api/sync/status` endpoint (`backend/src/api/garmin_sync.py`) (FR-007)
|
|
- [X] T037 [US4] Format and return synchronization status, progress, and error details
|
|
|
|
---
|
|
|
|
## Phase N: Polish & Cross-Cutting Concerns
|
|
|
|
**Purpose**: Improvements that affect multiple user stories
|
|
|
|
- [X] T038 [P] Documentation updates in `specs/002-intialspecv2/` (e.g., `quickstart.md` for new features)
|
|
- [X] T039 Code cleanup and refactoring across services and API endpoints
|
|
- [X] T040 Performance optimization (e.g., for large data syncs)
|
|
- [X] T041 [P] Additional unit tests for new services and utilities in `backend/tests/unit/`
|
|
- [X] T042 Security hardening (e.g., validation rules)
|
|
- [X] T043 Run `quickstart.md` validation and update as necessary
|
|
- [X] T044 Implement `auth_token` and `refresh_token` management (refreshing tokens before expiry)
|
|
|
|
---
|
|
|
|
## 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+)**: All depend on Foundational phase completion
|
|
- User stories can then proceed in parallel (if staffed)
|
|
- Or sequentially in priority order (P1 → P2 → P3)
|
|
- **Polish (Final Phase)**: Depends on all desired user stories being complete
|
|
|
|
### User Story Dependencies
|
|
|
|
- **User Story 1 (P1)**: Can start after Foundational (Phase 2) - No dependencies on other stories
|
|
- **User Story 2 (P2)**: Can start after Foundational (Phase 2) - May integrate with US1 but should be independently testable
|
|
- **User Story 3 (P3)**: Can start after Foundational (Phase 2) - May integrate with US1/US2 but should be independently testable
|
|
- **User Story 4 (P3)**: Can start after Foundational (Phase 2) - Depends on SyncJob from US1/US2/US3 to provide status
|
|
|
|
### Within Each User Story
|
|
|
|
- Tests (if included) MUST be written and FAIL before implementation
|
|
- Services before endpoints
|
|
- Core implementation before integration
|
|
- Story complete before moving to next priority
|
|
|
|
### Parallel Opportunities
|
|
|
|
- All Setup tasks marked [P] can run in parallel
|
|
- All Foundational tasks marked [P] can run in parallel (within Phase 2)
|
|
- Once Foundational phase completes, all user stories can start in parallel (if team capacity allows)
|
|
- All tests for a user story marked [P] can run in parallel
|
|
- Models within a story marked [P] can run in parallel
|
|
- Different user stories can be worked on in parallel by different team members
|
|
|
|
|
|
|
|
---
|
|
|
|
## Implementation Strategy
|
|
|
|
### MVP First (User Story 1 Only)
|
|
|
|
1. Complete Phase 1: Setup
|
|
2. Complete Phase 2: Foundational (CRITICAL - blocks all stories)
|
|
3. Complete Phase 3: User Story 1
|
|
4. **STOP and VALIDATE**: Test User Story 1 independently
|
|
5. Deploy/demo if ready
|
|
|
|
### Incremental Delivery
|
|
|
|
1. Complete Setup + Foundational → Foundation ready
|
|
2. Add User Story 1 → Test independently → Deploy/Demo (MVP!)
|
|
3. Add User Story 2 → Test independently → Deploy/Demo
|
|
4. Add User Story 3 → Test independently → Deploy/Demo
|
|
5. Add User Story 4 → Test independently → Deploy/Demo
|
|
6. Each story adds value without breaking previous stories
|
|
|
|
### Parallel Team Strategy
|
|
|
|
With multiple developers:
|
|
|
|
1. Team completes Setup + Foundational together
|
|
2. Once Foundational is done:
|
|
- Developer A: User Story 1
|
|
- Developer B: User Story 2
|
|
- Developer C: User Story 3
|
|
- Developer D: User Story 4
|
|
3. Stories complete and integrate independently
|
|
|
|
---
|
|
|
|
## Notes
|
|
|
|
- [P] tasks = different files, no dependencies
|
|
- [Story] label maps task to specific user story for traceability
|
|
- Each user story should be independently completable and testable
|
|
- Verify tests fail before implementing
|
|
- Commit after each task or logical group
|
|
- Stop at any checkpoint to validate story independently
|
|
- Avoid: vague tasks, same file conflicts, cross-story dependencies that break independence |