Rename progress log to docs/progress.md

2026-02-14 20:12:08 +01:00
parent 577c4b33b7
commit d5146d6b09
1 changed files with 0 additions and 0 deletions
@@ -0,0 +1,203 @@
+# Relationship Saver Progress Log
+
+Updated: 2026-02-14
+
+## Current Status
+
+The Flutter app now includes a production-grade backend integration scaffold with an offline-first posture:
+
+- Local/offline UX remains primary; backend is optional for core usage.
+- A transport-agnostic gateway interface is in place.
+- REST implementation with auth refresh/retry/error mapping is implemented.
+- Deterministic fake gateway is available for local/dev without backend.
+- OpenAPI contract + ADR + setup docs + unit tests are in place.
+- `flutter analyze` and `flutter test` are passing.
+
+## What Was Implemented
+
+### 1. Core Config + Theme Shell
+
+- Added backend config with build-time + runtime override:
+  - `lib/core/config/app_config.dart`
+- Added lightweight app theme aligned with reference style direction:
+  - `lib/core/config/app_theme.dart`
+- Updated app entry shell and Riverpod root:
+  - `lib/main.dart`
+
+### 2. Network Foundation
+
+Implemented a Dio stack with request metadata, auth, refresh, retry, and error mapping:
+
+- `lib/core/network/dio_factory.dart`
+- `lib/core/network/network_constants.dart`
+- `lib/core/network/backend_exception.dart`
+- `lib/core/network/dio_error_mapper.dart`
+- Interceptors:
+  - `lib/core/network/interceptors/request_metadata_interceptor.dart`
+  - `lib/core/network/interceptors/auth_interceptor.dart`
+  - `lib/core/network/interceptors/refresh_token_interceptor.dart`
+  - `lib/core/network/interceptors/retry_interceptor.dart`
+
+Behavior implemented:
+
+- Adds per-request `X-Request-Id`.
+- Adds `Authorization: Bearer <token>` when session exists.
+- On `401`, attempts one refresh (`/v1/auth/refresh`) then retries original request.
+- If refresh fails, session is cleared and `AuthExpiredException` surfaced.
+- Retry policy (max 2 retries, exponential backoff):
+  - Retry transient failures (`timeouts`, `connection`, `5xx`).
+  - Safe methods (`GET/HEAD/OPTIONS`) retry automatically.
+  - Non-idempotent endpoints only retry when `Idempotency-Key` exists.
+- Maps Dio failures into typed backend exceptions with metadata.
+
+### 3. Auth Token Storage
+
+- Interface:
+  - `lib/core/auth/token_store.dart`
+- Production implementation:
+  - `lib/core/auth/secure_token_store.dart`
+- Test/dev implementation:
+  - `lib/core/auth/in_memory_token_store.dart`
+
+### 4. Backend Integration Layer
+
+Domain boundary and implementations:
+
+- Interface:
+  - `lib/integrations/backend/backend_gateway.dart`
+- REST:
+  - `lib/integrations/backend/backend_gateway_rest.dart`
+- Fake:
+  - `lib/integrations/backend/backend_gateway_fake.dart`
+- Optional Riverpod providers:
+  - `lib/integrations/backend/backend_gateway_provider.dart`
+- Sync validation:
+  - `lib/integrations/backend/sync_envelope_validator.dart`
+
+Implemented methods:
+
+- sign-in/out + me
+- sync pull/push (with idempotency key on push)
+- signals feed + ack
+- upload init + download URL scaffold
+
+Offline-first hardening:
+
+- `signOut()` clears local token store in `finally`, even when network call fails.
+
+### 5. Typed Models (Freezed + JSON)
+
+- `lib/integrations/backend/models/backend_models.dart`
+- Generated files:
+  - `backend_models.freezed.dart`
+  - `backend_models.g.dart`
+
+Includes DTOs/enums for:
+
+- Auth (`SignInRequest`, `AuthSession`, refresh request/response, `UserProfile`)
+- Sync (`ChangeEnvelope`, push/pull requests/results, ack/rejection)
+- Signals (`SignalsFeed`, `SignalItem`, ack request/action)
+- Uploads (`UploadInitRequest/Result`, `DownloadUrl`)
+
+### 6. Contract + Architecture Docs
+
+- OpenAPI spec:
+  - `docs/api/openapi.yaml`
+- ADR:
+  - `docs/ADR/0002-backend-protocol-rest-openapi.md`
+- Setup instructions:
+  - `docs/SETUP.md`
+- Previous concise checklist log:
+  - `docs/PROGRESS.md`
+
+### 7. Tooling + Quality
+
+- Strict analyzer/lints:
+  - `analysis_options.yaml`
+- Dependencies added in `pubspec.yaml`:
+  - runtime: `dio`, `freezed_annotation`, `json_annotation`, `flutter_secure_storage`, `uuid`, `clock`, `flutter_riverpod`
+  - dev: `freezed`, `json_serializable`, `build_runner`, `mocktail`
+
+### 8. Test Coverage Added
+
+Core network and model tests:
+
+- `test/core/network/token_refresh_interceptor_test.dart`
+- `test/core/network/dio_error_mapper_test.dart`
+- `test/core/network/retry_interceptor_test.dart`
+- `test/integrations/backend/backend_models_serialization_test.dart`
+- `test/integrations/backend/sync_envelope_validator_test.dart`
+- helper adapter: `test/helpers/queue_http_client_adapter.dart`
+- updated smoke widget test: `test/widget_test.dart`
+
+## Verification Snapshot
+
+Most recent local checks:
+
+- `flutter analyze` -> pass
+- `flutter test` -> pass
+
+## Known Gaps / Intentional Scope Limits
+
+- No realtime transport yet (SSE/WebSocket intentionally deferred).
+- No backend-generated client code from OpenAPI yet.
+- No persistence layer wiring to local DB yet (gateway is ready to plug in).
+- No UI features using backend gateway yet beyond app shell readiness.
+- Fake gateway data is deterministic sample content, not scenario-configurable yet.
+
+## Handoff Plan For Next Agent Sessions
+
+### Priority 1: Repository Hygiene + CI
+
+1. Add CI workflow for `flutter analyze` + `flutter test`.
+2. Add branch protections / PR template if desired.
+3. Keep generated files committed policy explicit in README.
+
+### Priority 2: Local DB Integration (Offline-First Core)
+
+1. Define local domain entities and repositories for `person`, `capture`, `giftIdea`, `eventIdea`, `tag`, `reminderRule`.
+2. Map local mutations to `ChangeEnvelope` and enqueue for sync.
+3. Create sync orchestrator service that:
+   - pushes pending local mutations,
+   - applies pull changes with conflict policy,
+   - stores/advances cursor.
+4. Add tests for conflict handling and cursor progression.
+
+### Priority 3: App Wiring + UX
+
+1. Wire `BackendGateway` into app services/use cases (not UI widgets directly).
+2. Add session state provider (signed in / expired / signed out).
+3. Add explicit offline indicators and non-blocking sync status UI.
+4. Start consuming fake gateway in feature screens before live backend.
+
+### Priority 4: Security + Hardening
+
+1. Add central log redaction helper for headers/bodies.
+2. Add token-expiry pre-check strategy (optional proactive refresh).
+3. Evaluate secure storage behavior on web target and fallback policy.
+4. Add tests for concurrent 401 refresh race conditions.
+
+### Priority 5: API Evolution
+
+1. Version strategy in OpenAPI (`/v1` already set).
+2. Define backend error payload schema formally in OpenAPI.
+3. Add capabilities endpoint for future realtime negotiation.
+4. Add SSE/WebSocket design ADR when backend is ready.
+
+## How To Continue Quickly
+
+1. Run: `flutter pub get`
+2. If models change: `dart run build_runner build --delete-conflicting-outputs`
+3. Validate: `flutter analyze && flutter test`
+4. Start from:
+   - gateway surface: `lib/integrations/backend/backend_gateway.dart`
+   - sync transport: `lib/integrations/backend/backend_gateway_rest.dart`
+   - contract: `docs/api/openapi.yaml`
+
+## Important Notes
+
+- Current default base URL is placeholder (`https://api.example.com`).
+- Use fake mode for local iteration:
+  - `flutter run --dart-define=USE_FAKE_BACKEND=true`
+- Build-time URL override:
+  - `flutter run --dart-define=BACKEND_BASE_URL=<your-url>`