From 4b0ba76c22fbc9eb7fef772ef1c3b46579835c89 Mon Sep 17 00:00:00 2001 From: sstent Date: Mon, 22 Dec 2025 07:26:39 -0800 Subject: [PATCH] feat(tasks): create task breakdown for persisted auth --- specs/010-specification-overview-the/tasks.md | 110 ++++++++++++++++++ 1 file changed, 110 insertions(+) create mode 100644 specs/010-specification-overview-the/tasks.md diff --git a/specs/010-specification-overview-the/tasks.md b/specs/010-specification-overview-the/tasks.md new file mode 100644 index 0000000..7f9c8e4 --- /dev/null +++ b/specs/010-specification-overview-the/tasks.md @@ -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`).