Implement PushNotificationService abstraction
epic-certification-management-foundation-task-005 — Build the PushNotificationService abstract interface and its FCM-backed implementation. Expose sendNotification(recipientId, title, body, payload) and sendBatchNotifications methods. Integrate FCM token retrieval via the token manager, handle token refresh events, and provide a no-op stub implementation for unit testing environments.
Acceptance Criteria
Technical Requirements
Implementation Notes
Do not call FCM directly from the Flutter client — this exposes the server key. Instead, create a Supabase Edge Function (send-push-notification) that receives a list of NotificationRequest objects, calls FCM HTTP v1 API using the server key stored as a Supabase secret, and returns a BatchNotificationResult. The Flutter FcmPushNotificationService calls this Edge Function via http.post. Store FCM tokens in a supabase table (e.g.
user_fcm_tokens: user_id, token, platform, updated_at) updated on every token refresh. Use Riverpod to provide PushNotificationService so tests can override with NoOpPushNotificationService. Register the onTokenRefresh listener in an AppLifecycleObserver or in the Riverpod provider's build method. Log all notification attempts to cert_notification_log before the FCM call so failures are still recorded.
Testing Requirements
Unit tests (flutter_test): inject NoOpPushNotificationService and verify that sendNotification and sendBatchNotifications complete without error; test that FcmPushNotificationService correctly chunks a list of 1200 recipients into three batches of 500/500/200; mock the Edge Function HTTP call and assert the correct request body is sent; test that a failed FCM call for one recipient does not abort the rest of the batch. Integration tests: use a local Firebase emulator (if available) or a dedicated test FCM project to verify token registration and a successful test notification delivery to a test device. TestFlight builds should include a debug notification trigger screen for manual QA.
HLF Dynamics portal webhook API contract may be undocumented, subject to change, or require a separate authentication flow not yet agreed upon with HLF. If the contract changes post-implementation, the sync service silently fails and expired peer mentors remain on public listings.
Mitigation & Contingency
Mitigation: Obtain the official Dynamics webhook specification and test credentials from HLF before starting HLFDynamicsSyncService implementation. Agree on a versioned webhook contract and request a staging endpoint for integration testing.
Contingency: If the contract is unavailable, stub the sync service behind a feature flag and ship without Dynamics sync initially. Queue sync events locally and replay once the contract is confirmed.
Supabase RLS policies for certifications must correctly scope data to the coordinator's chapter without leaking cross-organisation data, particularly complex in multi-chapter membership scenarios. A misconfigured policy could expose peer mentor PII to wrong coordinators.
Mitigation & Contingency
Mitigation: Write RLS policies against the established org-hierarchy schema used by other tables. Peer review all policies before migration deployment. Add integration tests that assert cross-organisation data isolation using test accounts with different org scopes.
Contingency: If a policy gap is discovered post-merge, immediately disable the affected query endpoint and apply a hotfix migration. Audit access logs in Supabase for any cross-org data access events.
Storing renewal history as a JSONB field rather than a normalised table simplifies queries but makes retrospective schema changes (adding fields to history entries) harder and could cause issues if history grows very large for long-tenured mentors.
Mitigation & Contingency
Mitigation: Define a versioned JSONB entry schema (include a schema_version field in each entry) so future migrations can transform old entries. Add a size guard in the repository to warn if renewal_history exceeds 500 entries.
Contingency: If JSONB approach proves limiting, add a normalised certification_renewal_events table and migrate history entries in a background job, keeping the JSONB field as a read cache.