Implement platform permission rationale dialogs
epic-push-notification-delivery-foundation-task-011 — Build the pre-permission rationale dialog shown before the OS permission prompt on both iOS and Android. The dialog must explain why HLF needs notifications (activity reminders, certification expiry, important updates) using plain language meeting cognitive accessibility requirements. Include 'Allow' and 'Not Now' actions. For permanently denied state, show a settings-redirect dialog. All dialog text must be accessible via screen reader with proper semantics labels.
Acceptance Criteria
Technical Requirements
Execution Context
Tier 2 - 518 tasks
Can start after Tier 1 completes
Implementation Notes
Implement as two stateless widget dialogs: PermissionRationaleDialog and PermissionDeniedSettingsDialog, both in lib/notifications/widgets/. Do not use showDialog directly inside the permission manager — instead expose callbacks (onAllow, onNotNow) so the calling widget controls navigation, keeping the dialogs purely presentational and easily testable. Use the app's existing AppButton and AppTextField design token primitives rather than raw ElevatedButton/TextButton to ensure consistent styling. For Semantics, wrap the entire dialog content in a Semantics(container: true) and add individual Semantics(label: '...', button: true) to each action button.
The cognitive accessibility requirement from the workshop (plain language, no jargon) maps directly to dialog copy: write at a Grade 6 reading level, use short sentences, and avoid technical terms like 'push notification' — say 'app messages' or 'reminders' instead. Confirm copy with HLF stakeholder before finalising.
Testing Requirements
Widget tests (flutter_test): render PermissionRationaleDialog and assert title, body, 'Allow' button, and 'Not Now' button are present in the widget tree; tap 'Allow' and verify onAllow callback is called; tap 'Not Now' and verify onNotNow callback is called; verify Semantics labels exist on all interactive elements. Widget test for settings-redirect dialog: assert 'Open Settings' and 'Cancel' buttons; tap 'Open Settings' and verify openAppSettings() mock is called. Accessibility test: use flutter_test's SemanticsHandle to assert all interactive nodes have non-empty labels. Visual QA: compare dialog against design spec on both iOS and Android, verify contrast ratios with a contrast checker tool.
iOS only allows one system permission prompt per app install. If the rationale dialog timing or content is wrong the user may permanently deny permissions during onboarding, permanently blocking push delivery for that device with no recovery path short of manual system settings navigation.
Mitigation & Contingency
Mitigation: Design and user-test the rationale dialog content and trigger point (after onboarding value-demonstration step, not at first launch). Implement the settings-deep-link fallback in NotificationPermissionManager so the permission state screen always offers a path to system settings if denied.
Contingency: If denial rates are high in TestFlight testing, revise the rationale copy and trigger timing before production release. Ensure the in-app notification centre provides full value without push so denied users are not blocked from the feature.
FCM token rotation callbacks can fire at any time, including during app termination or network outage. If the token rotation is not persisted reliably the backend trigger service will dispatch to a stale token, resulting in silent notification failures that are hard to diagnose.
Mitigation & Contingency
Mitigation: Persist token rotation updates with a local queue that retries on next app foreground if network is unavailable. Use Supabase upsert by (user_id, device_id) to prevent duplicate token rows and ensure the latest token always wins.
Contingency: If token staleness is observed in production, add a token validity check on each app foreground and force a re-registration if the stored token does not match the FCM-reported current token.
Incorrect RLS policies on notification_preferences or fcm_tokens could expose one user's preferences or device tokens to another user, or could block the backend Edge Function service role from reading token lists needed for dispatch, silently dropping all notifications.
Mitigation & Contingency
Mitigation: Write explicit RLS policy tests using the Supabase test harness covering user-scoped read/write, service-role read for dispatch, and cross-user access denial. Review policies during code review with a security checklist.
Contingency: Maintain a rollback migration that reverts the RLS changes, and add an integration test in CI that asserts the service role can query all tokens and that a normal user JWT cannot access another user's token rows.