Build Dart repository class for peer mentor status
epic-peer-mentor-pause-management-foundation-task-006 — Implement the PeerMentorStatusRepository Dart class with methods for reading current pause status, writing status transitions via RPC, subscribing to realtime status changes, and querying the status log history. Register Riverpod providers for dependency injection.
Acceptance Criteria
Technical Requirements
Execution Context
Tier 2 - 518 tasks
Can start after Tier 1 completes
Implementation Notes
Use a constructor-injected SupabaseClient (not Supabase.instance) to keep the class unit-testable. Define PeerMentorStatus and PeerMentorStatusLogEntry as immutable Dart classes with fromJson factories — use freezed if the codebase already uses it for consistency. For the Realtime subscription, use supabase.channel('peer_mentor_status:$peerMentorId').onPostgresChanges(...).subscribe() and store the channel reference so it can be removed on stream cancellation. Wrap all async Supabase calls in try/catch on PostgrestException and rethrow as PeerMentorStatusException with a code enum (notFound, unauthorized, serverError) so the BLoC layer can pattern-match without importing Supabase types.
Register providers using Riverpod's autoDispose modifier for stream providers to ensure subscriptions are cleaned up when the widget tree disposes the provider. Keep the repository focused on data access — no business logic (e.g., 'should I allow pause?') belongs here.
Testing Requirements
Write unit tests using flutter_test and mocktail (or mockito) to cover: (1) getCurrentStatus returns correct typed model on success, (2) getCurrentStatus throws PeerMentorStatusException on PostgrestException, (3) activatePause calls the correct RPC with correct parameters, (4) deactivatePause calls the correct RPC, (5) watchStatus emits updated model on Realtime event, (6) watchStatus stream cancellation triggers unsubscribe on Supabase channel, (7) getStatusHistory returns list ordered by created_at DESC, (8) getStatusHistory respects pagination limit. Integration tests against a Supabase test project should verify the full round-trip: activate → realtime event received → deactivate → history contains both entries. Aim for 90%+ line coverage on the repository class.
Supabase RLS policies for coordinator-scoped status queries may be difficult to express correctly, especially for peer mentors assigned to multiple coordinators or chapters, leading to data leakage or overly restrictive access blocking valid queries.
Mitigation & Contingency
Mitigation: Design RLS policies using security-definer RPCs rather than table-level policies for complex multi-coordinator scenarios. Write a comprehensive RLS test matrix covering all role and assignment permutations before marking complete.
Contingency: Fall back to application-level filtering in the repository layer with explicit coordinator_id parameter checks if RLS proves intractable, and document the trade-off for security review.
The HLF Dynamics portal API contract may be undocumented or subject to change, causing the DynamicsPortalClient to break during development or production rollout.
Mitigation & Contingency
Mitigation: Obtain the full Dynamics portal API specification and credentials early in the sprint. Build the client behind a well-defined interface so the HLF-specific implementation can be swapped without affecting upstream services.
Contingency: If the Dynamics API is unavailable or unstable, stub the client with a feature-flag-guarded no-op implementation so all other epics can proceed to completion independently.
Supabase Edge Functions used as the nightly scheduler host may have cold-start latency or execution time limits that prevent reliable nightly certification checks on large mentor rosters.
Mitigation & Contingency
Mitigation: Benchmark Edge Function execution time against the expected roster size. Design the expiry check to process in paginated batches to stay within execution limits. Use pg_cron with a direct database function as an alternative trigger if Edge Functions prove unreliable.
Contingency: Migrate the scheduler trigger to pg_cron invoking a Postgres function directly, removing the Edge Function dependency entirely for the scheduling layer.