Implement Push Notification Service
epic-push-notification-delivery-ui-task-008 — Build the PushNotificationService that integrates FCMTokenManager and NotificationDeepLinkHandler to handle incoming FCM messages in foreground, background, and terminated states. Persist received notifications via NotificationRepository, show local in-app banners for foreground messages, and route deep links on notification tap. Handle all Firebase message lifecycle callbacks.
Acceptance Criteria
Technical Requirements
Execution Context
Tier 2 - 518 tasks
Can start after Tier 1 completes
Implementation Notes
Structure PushNotificationService as a Riverpod AsyncNotifier that subscribes to all three FirebaseMessaging streams in its build method. The background message handler must be a top-level async function (not a method) — place it in a dedicated notifications_background_handler.dart file. In main.dart, call FirebaseMessaging.onBackgroundMessage(backgroundMessageHandler) before runApp(). For the foreground in-app banner, use an OverlayEntry inserted into the root overlay; create a custom BannerWidget that auto-dismisses after 4 seconds using a Timer.
For Android foreground notifications, configure flutter_local_notifications with a high-importance channel. Store a StreamController
Testing Requirements
Unit tests: mock FirebaseMessaging streams and assert NotificationRepository.insert() is called with correct payload for each lifecycle path. Test idempotency: calling handler twice with same message_id results in one DB record. Test preference filtering: foreground banner suppressed when category disabled. Test unreadCount stream emits correct value after insert and after mark-as-read.
Integration test: full foreground message flow using fake async and mocked overlay. Widget test: verify badge count updates when unreadCount stream emits. Test background handler function in isolation with mocked Supabase client.
The notification badge widget depends on a persistent Supabase Realtime websocket subscription for live unread count updates. On mobile, network transitions (WiFi to cellular, background app state) can silently drop the websocket, resulting in a stale badge count that does not update until the next app foreground — reducing trust in the notification system.
Mitigation & Contingency
Mitigation: Implement connection lifecycle management in the badge widget's BLoC that re-subscribes on app foreground and on network reconnection events. Add a fallback polling query (every 60 seconds when app is foregrounded) to reconcile the badge count if the Realtime subscription is interrupted.
Contingency: If Realtime reliability proves insufficient in production, replace the live subscription with a polling approach using a configurable interval, accepting slightly delayed badge updates in exchange for reliability.
The notification list item widget requires merged semantics combining title, body, timestamp, read state, and role-context icon into a single VoiceOver/TalkBack announcement. Getting the merged semantics structure right for both iOS (VoiceOver) and Android (TalkBack) simultaneously is non-trivial and common to break silently when widgets are refactored.
Mitigation & Contingency
Mitigation: Use the project's existing semantics-wrapper-widget pattern with explicit Semantics widgets and excludeSemantics on decorative children. Write accessibility widget tests using Flutter's SemanticsController to assert the exact announcement string. Test on physical devices with VoiceOver and TalkBack enabled before release.
Contingency: If merged semantics cannot be achieved cleanly on both platforms, implement platform-specific semantic trees using defaultTargetPlatform branching, ensuring each platform receives an optimal announcement even if the implementation differs.