mirror of
https://github.com/sstent/FitTrack_GarminSync.git
synced 2026-01-26 17:12:00 +00:00
117 lines
7.9 KiB
Markdown
117 lines
7.9 KiB
Markdown
# Feature Specification: IntialSpecV2
|
|
|
|
**Feature Branch**: `feature/intial-spec-v2`
|
|
**Created**: 2025-10-09
|
|
**Status**: Draft
|
|
**Input**: User description: "Create a detailed feature specification based on the provided context."
|
|
|
|
## User Scenarios & Testing *(mandatory)*
|
|
|
|
### User Story 1 - Garmin Connect Activity Synchronization (Priority: P1)
|
|
|
|
As a user, I want to authenticate with Garmin Connect and have my activities (FIT, GPX, TCX files) downloaded and stored in CentralDB so that I can track my fitness data.
|
|
|
|
**Why this priority**: This is a core function for the GarminSync service, enabling fundamental data collection.
|
|
|
|
**Independent Test**: Can be fully tested by authenticating with Garmin Connect, triggering an activity sync, and then verifying that activity files are correctly stored in CentralDB.
|
|
|
|
**Acceptance Scenarios**:
|
|
|
|
1. **Given** a user has successfully authenticated with Garmin Connect, **When** they trigger an activity sync via `POST /api/sync/garmin/activities`, **Then** their recent activities are downloaded from Garmin Connect and stored as FIT/GPX/TCX files in CentralDB.
|
|
2. **Given** a user has authenticated with Garmin Connect, **When** a sync is triggered, **Then** only new or updated activities are downloaded to avoid redundant data.
|
|
|
|
---
|
|
|
|
### User Story 2 - Garmin Connect Health Metrics Synchronization (Priority: P2)
|
|
|
|
As a user, I want my health metrics to be synchronized from Garmin Connect to CentralDB so I can have a comprehensive view of my health data.
|
|
|
|
**Why this priority**: Important for a holistic view of user health, complementing activity data.
|
|
|
|
**Independent Test**: Can be fully tested by authenticating with Garmin Connect, triggering a sync, and verifying that health metrics (e.g., heart rate, sleep data) are correctly synchronized and stored in CentralDB.
|
|
|
|
**Acceptance Scenarios**:
|
|
|
|
1. **Given** a user has successfully authenticated with Garmin Connect, **When** they trigger a sync, **Then** their health metrics are synchronized from Garmin Connect to CentralDB.
|
|
|
|
---
|
|
|
|
### User Story 3 - Garmin Workout Upload (Priority: P2)
|
|
|
|
As a user, I want to be able to upload workouts from the application to Garmin Connect.
|
|
|
|
**Why this priority**: This provides bidirectional sync functionality, enhancing the utility of the service.
|
|
|
|
**Independent Test**: Can be fully tested by creating a workout in the application, initiating its upload to Garmin Connect, and then verifying that the workout appears correctly on the user's Garmin Connect account.
|
|
|
|
**Acceptance Scenarios**:
|
|
|
|
1. **Given** a user has a workout defined within the application, **When** they initiate the workout upload to Garmin, **Then** the workout is successfully transmitted and appears on their Garmin Connect account.
|
|
|
|
---
|
|
|
|
### User Story 4 - Check Sync Status (Priority: P3)
|
|
|
|
As a user, I want to be able to check the status of my synchronization processes.
|
|
|
|
**Why this priority**: Provides essential feedback to the user on ongoing and completed operations, improving user experience.
|
|
|
|
**Independent Test**: Can be fully tested by triggering a synchronization process, then querying the `/api/sync/status` endpoint to verify that it accurately reflects the ongoing or completed status of the sync.
|
|
|
|
**Acceptance Scenarios**:
|
|
|
|
1. **Given** a synchronization process is in progress, **When** the user makes a `GET` request to `/api/sync/status`, **Then** the system returns the current status of the synchronization, including any progress or errors.
|
|
2. **Given** a synchronization process has completed, **When** the user makes a `GET` request to `/api/sync/status`, **Then** the system returns the final status of the synchronization, including success or failure details.
|
|
|
|
---
|
|
|
|
### Edge Cases
|
|
|
|
- What happens when the Garmin Connect API is unavailable or returns an error during activity or health metrics synchronization?
|
|
- How does the system handle exceeding rate limits imposed by the Garmin Connect API?
|
|
- What is the behavior of the system if CentralDB is unavailable or encounters an error during data storage operations?
|
|
- How does the system respond if a user revokes the OAuth2 authentication for Garmin Connect?
|
|
- What happens if there are conflicts between existing data in CentralDB and incoming data from Garmin Connect during synchronization?
|
|
|
|
## Requirements *(mandatory)*
|
|
|
|
### Functional Requirements
|
|
|
|
- **FR-001**: System MUST support Garmin Connect username and password authentication for user authorization.
|
|
- **FR-002**: System MUST download activity files (FIT, GPX, TCX) from Garmin Connect.
|
|
- **FR-003**: System MUST store downloaded activity files in CentralDB.
|
|
- **FR-004**: System MUST synchronize health metrics data from Garmin Connect to CentralDB.
|
|
- **FR-005**: System MUST allow users to upload workouts to Garmin Connect.
|
|
- **FR-006**: System MUST provide a `POST /api/sync/garmin/activities` API endpoint to trigger activity synchronization.
|
|
- **FR-007**: System MUST provide a `GET /api/sync/status` API endpoint to check the current status of synchronization processes.
|
|
- **FR-008**: System MUST process all synchronization tasks as background jobs to ensure responsiveness.
|
|
- **FR-009**: System MUST implement rate limiting mechanisms for all external API calls, especially to Garmin Connect.
|
|
- **FR-010**: System MUST include robust error handling and retry logic for transient failures during external API interactions and CentralDB operations.
|
|
- **FR-011**: System MUST maintain a history of synchronization events and provide mechanisms for conflict resolution using CentralDB.
|
|
- **FR-012**: The application MUST be designed as a single-user system.
|
|
- **FR-013**: The service MUST default to listening on port 8001.
|
|
- **FR-014**: System MUST support configuration via YAML files or environment variables.
|
|
- **FR-015**: System MUST reuse existing code and logic from @GarminAnalyser.md for Garmin integration where applicable.
|
|
- **FR-016**: System MUST utilize CentralDB for all persistent storage, including user authentication tokens (e.g., username and password hashes).
|
|
- **FR-019**: System WILL leverage the `garth` and `garminconnect` libraries for Garmin Connect integration, particularly for handling authentication and data synchronization.
|
|
- **FR-017**: System MUST integrate with the CentralDB API as defined in @DB_API_SPEC.json (with the ability to refresh the spec from `http://localhost:8000/openapi.json`).
|
|
- **FR-018**: System SHOULD support Fitbit weight data synchronization in a future iteration.
|
|
|
|
### Key Entities *(include if feature involves data)*
|
|
|
|
- **User**: The single authenticated individual utilizing the GarminSync service.
|
|
- **Garmin Connect Account**: Represents the user's linked Garmin account, storing OAuth2 tokens and other necessary authentication credentials.
|
|
- **Activity**: A record of a fitness activity (e.g., running, cycling) obtained from Garmin Connect, encompassing raw data files (FIT, GPX, TCX) and metadata.
|
|
- **Health Metric**: A data point representing a user's health measurement (e.g., heart rate, sleep data, body composition) synchronized from Garmin Connect.
|
|
- **Workout**: A structured training plan or session that can be uploaded to Garmin Connect.
|
|
- **Sync Job**: An instance of a synchronization operation (e.g., activity sync, health metrics sync), tracking its status, progress, and any associated errors.
|
|
|
|
## Success Criteria *(mandatory)*
|
|
|
|
### Measurable Outcomes
|
|
|
|
- **SC-001**: 95% of all triggered Garmin Connect activity synchronizations complete successfully within 5 minutes.
|
|
- **SC-002**: Garmin Connect OAuth2 authentication process completes successfully for 100% of first-time users.
|
|
- **SC-003**: The `GET /api/sync/status` endpoint returns an accurate synchronization status within 5 seconds of being queried.
|
|
- **SC-004**: Data stored in CentralDB (activities, health metrics, tokens) maintains 99.9% integrity and availability.
|
|
- **SC-005**: Workout uploads to Garmin Connect succeed for 98% of attempts. |