Implement DeclarationRepository with lifecycle state management
epic-driver-and-confidentiality-management-foundation-task-006 — Implement the Dart repository class for confidentiality declarations. Expose methods for creating a declaration (pending), fetching declarations by driver, updating status to acknowledged, and retrieving declarations by template version. Ensure soft-delete is used throughout to preserve tamper-evident records.
Acceptance Criteria
Technical Requirements
Execution Context
Tier 2 - 518 tasks
Can start after Tier 1 completes
Implementation Notes
Follow the existing repository pattern in the codebase (abstract interface + concrete Supabase implementation). Use Riverpod's Provider or AsyncNotifierProvider for the repository, not BLoC directly — the BLoC layer sits above the repository. The Declaration Dart model should use freezed for immutability and copyWith support; add fromJson/toJson for Supabase response mapping. Status transition validation should be in the repository (not just the BLoC) because the repository is the single gatekeeper for persistence — the BLoC can also validate for UX, but the repository is the enforcer.
When building the soft-delete query, use .update({'deleted_at': DateTime.now().toIso8601String(), 'deleted_by': supabase.auth.currentUser!.id}).eq('id', declarationId) and always chain .is_('deleted_at', null) on read queries. Avoid exposing raw Supabase PostgrestException to callers — catch it in every public method and rethrow as a domain exception with a human-readable message.
Testing Requirements
Write unit tests using flutter_test with a mocked SupabaseClient (use mockito or mocktail). Test cases must cover: (1) createDeclaration returns a Declaration with status pending; (2) getDeclarationsByDriver excludes soft-deleted rows; (3) acknowledgeDeclaration succeeds when status is pending; (4) acknowledgeDeclaration throws DeclarationStatusTransitionException when status is acknowledged; (5) acknowledgeDeclaration throws DeclarationStatusTransitionException when status is expired; (6) softDeleteDeclaration sets deleted_at and deleted_by; (7) getDeclarationsByTemplateVersion returns correct subset; (8) network error from Supabase is wrapped in DeclarationRepositoryException. Write one Supabase integration test (against local emulator) verifying the full create→acknowledge lifecycle end-to-end.
Row-level security policies for driver assignments and declarations must correctly scope data to the coordinator's chapter without leaking records across organizations. An incorrect RLS predicate could silently return empty result sets or, worse, expose cross-org data, both of which are difficult to detect in unit tests.
Mitigation & Contingency
Mitigation: Write dedicated RLS integration test scenarios with multiple org fixtures asserting both data isolation and correct data visibility. Use Supabase's built-in policy testing utilities and review policies with a second developer.
Contingency: If RLS policies prove too complex to get right quickly, implement application-layer org scoping as a temporary guard while RLS is fixed in a follow-up, with an explicit security review gate before production deployment.
The declaration audit logger must produce tamper-evident records. If the database allows updates or deletes on audit rows, the compliance guarantee is broken. Supabase does not natively prevent row deletion by default.
Mitigation & Contingency
Mitigation: Implement an insert-only RLS policy on the audit table that denies UPDATE and DELETE for all roles including the service role. Add a database trigger that rejects mutation attempts and logs the attempt itself.
Contingency: If immutability cannot be enforced at the database level within the sprint, store audit entries in an append-only Supabase Edge Function log stream as a temporary alternative, with a migration plan to the proper table once constraints are implemented.
The org-feature-flag-service caches flag values to avoid repeated database reads. If the cache is not invalidated promptly after an admin toggles the flag, coordinators may see stale UI state — either seeing driver features when they should not, or not seeing them when they should.
Mitigation & Contingency
Mitigation: Use a Supabase Realtime subscription to listen for changes on the driver_feature_flag_config table and invalidate the in-memory cache immediately on change. Set a short TTL (60 seconds) as a safety net.
Contingency: If Realtime subscription proves unreliable, expose a manual cache-bust endpoint accessible from the admin toggle action, ensuring the cache is cleared synchronously on every flag change.