Implement Statistics Repository with Supabase Views
epic-coordinator-statistics-dashboard-core-logic-task-003 — Implement StatsRepository that queries the Supabase stats views (activity counts by type, by period, by peer mentor) using parameterised RPC calls. Repository must accept scope parameters (coordinator_id, org_id) and a StatsFilter, return raw aggregation rows, and propagate errors as typed exceptions. Wire up the Supabase client via Riverpod provider.
Acceptance Criteria
Technical Requirements
Execution Context
Tier 1 - 540 tasks
Can start after Tier 0 completes
Implementation Notes
Define Supabase RPC functions as PostgreSQL functions with explicit parameter types — avoid using `filter()` chaining on views for stats aggregations since it bypasses the query planner's ability to use indexes on the aggregate. Example RPC signature: `get_coordinator_stats(p_chapter_id uuid, p_date_from timestamptz, p_date_to timestamptz, p_activity_type text) RETURNS json`. Map the raw JSON response rows to intermediate DTOs before constructing ViewModels — this isolates the repository from schema changes. Use Riverpod's `ref.read(supabaseClientProvider)` to obtain the client, not a global Supabase singleton, so the provider can be overridden in tests.
For error handling, wrap the entire RPC call in a try/catch on `PostgrestException` and inspect `code` for '42501' to distinguish permission errors from generic network failures. Ensure the Riverpod provider for StatsRepository is `autoDispose` unless a long-lived singleton is intentionally required.
Testing Requirements
Write integration tests that connect to a local Supabase instance (via Docker or the Supabase CLI) seeded with known test data. Verify: (1) Coordinator-scoped query returns only records from the correct chapter. (2) Org-admin-scoped query returns aggregated records across all chapters in the org. (3) Personal stats query returns only the specified peer mentor's activities.
(4) Applying a StatsFilter with a date range excludes out-of-range records. (5) Network failure (simulate by pointing to a non-existent host) throws StatsNetworkException. (6) RLS violation scenario throws StatsPermissionException. Use flutter_test with a real Supabase test client — do not mock the Supabase client for integration tests.
Unit tests with a mocked Supabase client are acceptable for error-path coverage only.
fl_chart's default colour palette may not meet WCAG 2.2 AA contrast requirements when rendered on the app's dark or light backgrounds. If segment colours are insufficient, the donut chart will fail accessibility audits, which is a compliance blocker for all three organisations.
Mitigation & Contingency
Mitigation: Define all chart colours in the design token system with pre-validated contrast ratios. Run the contrast-ratio-validator against every chart colour during the adapter's unit tests. Use the contrast-safe-color-palette as the source palette.
Contingency: If a colour fails validation, replace with the nearest compliant token. If activity types exceed the available token set, implement a deterministic hashing algorithm that maps activity type IDs to compliant colours.
StatsBloc subscribing to the activity registration stream creates a long-lived subscription. If the subscription is not disposed correctly when the dashboard is closed, it will cause a stream leak and potentially trigger re-fetches on a disposed BLoC, resulting in uncaught errors in production.
Mitigation & Contingency
Mitigation: Implement subscription disposal in the BLoC's close() override. Write a widget test that navigates away from the dashboard and asserts no BLoC events are emitted after disposal.
Contingency: If leaks are detected in QA, add a mounted check guard before emitting states from async callbacks, and audit all other BLoC stream subscriptions in the codebase for the same pattern.
PersonalStatsService's Phase 4 gamification data structure is designed against an assumed future schema. If the Phase 4 Spotify Wrapped feature defines a different data contract when it is developed, the structure built now will require a breaking change and migration.
Mitigation & Contingency
Mitigation: Document the contribution data structure with explicit field semantics and versioning comments. Keep the Phase 4 fields as optional/nullable so they do not break existing consumers if the schema evolves.
Contingency: If the Phase 4 schema diverges significantly, the personal stats data can be re-mapped in a thin adapter layer without changing PersonalStatsService's core implementation.