mirror of
https://github.com/sstent/FitTrack_GarminSync.git
synced 2026-01-25 08:35:23 +00:00
feat(tasks): create task breakdown for persisted auth
This commit is contained in:
110
specs/010-specification-overview-the/tasks.md
Normal file
110
specs/010-specification-overview-the/tasks.md
Normal file
@@ -0,0 +1,110 @@
|
||||
# Task Breakdown: Persist Garmin Authentication for Stateless Sync
|
||||
|
||||
This document breaks down the implementation of the "Persist Garmin Authentication for Stateless Sync" feature into actionable, dependency-ordered tasks.
|
||||
|
||||
**Implementation Strategy**:
|
||||
The feature will be delivered in increments based on user story dependencies. The foundational database work will be done first. Then, we will implement the login/MFA flow (US2) to enable session creation. With sessions available, we'll implement the core background sync logic (US1). Finally, we'll add session invalidation and status checks (US3). This ensures a logical build-up of functionality.
|
||||
|
||||
---
|
||||
|
||||
## Phase 1: Foundational Setup
|
||||
|
||||
**Goal**: Prepare the database schema and core data structures. This phase must be completed before any user story implementation can begin.
|
||||
|
||||
- **T001**: **[DB Model]** Define the `GarminAuthenticationState` SQLAlchemy model in a new file `src/models/garmin_auth_state.py`.
|
||||
- **T002**: **[DB Migration]** Create a new Alembic migration script to add the `garmin_authentication_state` table to the database.
|
||||
- **T003**: **[Test]** Write a unit test in `tests/unit/models/test_garmin_auth_state.py` to verify the model's structure and relationships. [P]
|
||||
- **T004**: **[Pydantic Model]** Define Pydantic schemas for API requests and responses related to authentication (Login, MFA, Status) in `src/models/schemas/garmin_auth.py`. [P]
|
||||
|
||||
---
|
||||
|
||||
## Phase 2: [US2] Initial Login and MFA Flow
|
||||
|
||||
**User Story**: A user can perform a one-time login, handle an MFA challenge, and have their session persisted.
|
||||
**Independent Test**: A user can log in via the API, enter an MFA code when prompted, and a valid session will be stored in the database, verifiable by checking the `garmin_authentication_state` table.
|
||||
|
||||
- **T005**: **[Test]** Create an API test file `tests/api/test_auth_api.py` with tests for the `POST /login` and `POST /mfa` endpoints, covering success, MFA required, and failure cases.
|
||||
- **T006**: **[Service]** Create a new service `src/services/garmin_auth_service.py` containing the business logic for logging in, handling MFA, and saving the session to the database using `garth`.
|
||||
- **T007**: **[API Endpoint]** Create a new API router in `src/api/v1/auth.py`. Implement the `POST /api/v1/garmin/session/login` endpoint, calling the auth service.
|
||||
- **T008**: **[API Endpoint]** Implement the `POST /api/v1/garmin/session/mfa` endpoint in `src/api/v1/auth.py`, calling the auth service.
|
||||
- **T009**: **[Test]** Write unit tests in `tests/unit/services/test_garmin_auth_service.py` to mock `garth` and the database, verifying the service logic for login and MFA handling. [P]
|
||||
|
||||
**Checkpoint**: User Story 2 is complete. The system can now authenticate users and persist their sessions.
|
||||
|
||||
---
|
||||
|
||||
## Phase 3: [US1] Seamless Background Sync
|
||||
|
||||
**User Story**: Background sync jobs can run automatically using the persisted session.
|
||||
**Independent Test**: Trigger a background sync for a user with a valid persisted session. Verify that the job completes successfully without any manual intervention and that new data is fetched. Test the auto-refresh mechanism by using a slightly expired (but refreshable) mock session.
|
||||
|
||||
- **T010**: **[Test]** Update tests for background sync services (e.g., `tests/unit/services/test_activity_sync.py`) to include scenarios where the service loads a session from the database.
|
||||
- **T011**: **[Service]** Modify the existing background sync services (e.g., `GarminActivityService`) to implement the "Load-Use-Update" pattern:
|
||||
- Load the `GarminAuthenticationState` from the DB.
|
||||
- Initialize `garth` with the session data.
|
||||
- Perform the sync.
|
||||
- If the session was refreshed by `garth`, update the `session_data` and `last_validated` fields in the database.
|
||||
|
||||
**Checkpoint**: User Story 1 is complete. The system can now perform its core function of stateless, automated synchronization.
|
||||
|
||||
---
|
||||
|
||||
## Phase 4: [US3] Session Invalidation and Status
|
||||
|
||||
**User Story**: The system can detect an invalid session, report it, and allow a client to check the session's status.
|
||||
**Independent Test**: For a user with a persisted session, manually invalidate it. Trigger a sync and verify the job status becomes `AUTH_EXPIRED` and the session data is cleared from the DB. Also, call the `GET /status` endpoint before and after to see the status change.
|
||||
|
||||
- **T012**: **[Test]** Add API tests to `tests/api/test_auth_api.py` for the `GET /status` endpoint.
|
||||
- **T013**: **[API Endpoint]** Implement the `GET /api/v1/garmin/session/status` endpoint in `src/api/v1/auth.py`. The endpoint should use the auth service to validate the token. [P]
|
||||
- **T014**: **[Test]** Add unit tests to `tests/unit/services/test_garmin_auth_service.py` for the session validation logic.
|
||||
- **T015**: **[Service]** Add a `get_session_status` method to `src/services/garmin_auth_service.py` that performs a lightweight check on the session.
|
||||
- **T016**: **[Service]** Enhance the error handling in background sync services. If a sync fails with an unrecoverable auth error, the service must call a method in the auth service to clear the `session_data` from the database.
|
||||
|
||||
**Checkpoint**: User Story 3 is complete. The system is now resilient to session invalidation.
|
||||
|
||||
---
|
||||
|
||||
## Phase 5: Polish & Integration
|
||||
|
||||
- **T017**: **[Documentation]** Update the main `README.md` and any relevant developer docs to explain the new authentication flow.
|
||||
- **T018**: **[CI/CD]** Ensure all new tests are integrated into the CI pipeline and that all pre-commit hooks pass.
|
||||
|
||||
## Dependencies
|
||||
|
||||
```mermaid
|
||||
graph TD
|
||||
subgraph Phase 1 [Foundational]
|
||||
T001(DB Model) --> T002(DB Migration);
|
||||
T003(Test Model);
|
||||
T004(Pydantic Model);
|
||||
end
|
||||
|
||||
subgraph Phase 2 [US2 - Login/MFA]
|
||||
T005(API Tests) --> T007(Login Endpoint);
|
||||
T007 --> T008(MFA Endpoint);
|
||||
T009(Unit Tests) --> T006(Auth Service);
|
||||
T007 & T008 --> T006;
|
||||
end
|
||||
|
||||
subgraph Phase 3 [US1 - Background Sync]
|
||||
T010(Sync Tests) --> T011(Update Sync Service);
|
||||
end
|
||||
|
||||
subgraph Phase 4 [US3 - Invalidation]
|
||||
T012(Status API Test) --> T013(Status Endpoint);
|
||||
T014(Status Unit Test) --> T015(Status Service Logic);
|
||||
T013 --> T015;
|
||||
T011 --> T016(Enhance Error Handling);
|
||||
end
|
||||
|
||||
Phase 1 --> Phase 2;
|
||||
Phase 2 --> Phase 3;
|
||||
Phase 3 --> Phase 4;
|
||||
Phase 4 --> T017(Docs) & T018(CI/CD);
|
||||
```
|
||||
|
||||
## Parallel Execution Examples
|
||||
|
||||
- **Within Phase 1**: `T003` and `T004` can be done in parallel while `T001` and `T002` are being worked on sequentially.
|
||||
- **Within Phase 2**: The API tests (`T005`) and unit tests (`T009`) can be developed in parallel before the service (`T006`) and endpoints (`T007`, `T008`) are implemented.
|
||||
- **Within Phase 4**: The status endpoint (`T012`-`T015`) can be developed in parallel with the error handling enhancements for the sync service (`T016`).
|
||||
Reference in New Issue
Block a user