Implement retry backoff and trigger wiring in SyncService
epic-dynamic-terminology-and-labels-service-layer-task-006 — Implement the full TerminologySyncService: subscribe to AppLifecycleState changes (foreground trigger) and connectivity stream (connectivity-restore trigger), invoke the version check, trigger OrganizationLabelsNotifier reload on refreshRequired, and apply exponential backoff with jitter on network failure. Ensure the service does not trigger concurrent syncs and cancels pending retries on logout.
Acceptance Criteria
Technical Requirements
Execution Context
Tier 2 - 518 tasks
Can start after Tier 1 completes
Implementation Notes
Mix in WidgetsBindingObserver and call WidgetsBinding.instance.addObserver(this) in start(), removeObserver in stop(). Use a StreamController.broadcast() for the events stream. Implement backoff with a recursive _scheduleRetry(int attempt) method that creates a new Timer and stores the reference for cancellation. Use Random().nextDouble() * 0.2 * baseDelay as jitter.
Guard against logout races: store a _stopped bool; check it at the start of every async step in the retry chain and abort if true. Keep the concrete class internal to the feature layer; expose only via TerminologySyncService abstract type and Riverpod provider. Consider using package:clock for testable time if the project already uses it — fakeAsync works without it but clock makes intent clearer.
Testing Requirements
Unit tests with flutter_test and fakeAsync. Mock connectivity stream and app lifecycle observer. Test scenarios: (1) foreground trigger → version upToDate → no reload; (2) foreground trigger → refreshRequired → reload called once; (3) concurrent triggers → only one sync runs; (4) network failure → retry scheduled at correct backoff delay (verify with fakeAsync timers); (5) maxRetries exhausted → syncFailed event emitted, no further timers; (6) stop() during retry → timer cancelled, no reload called. Use mockito to verify OrganizationLabelsNotifier.reload() call count.
Verify jitter: run 100 iterations, assert all delays fall within [baseDelay, baseDelay * 1.2].
When a user switches organization context (e.g., a coordinator with multi-org access), a race condition between the outgoing organization's map disposal and the incoming organization's fetch could briefly expose the wrong organization's terminology to the widget tree.
Mitigation & Contingency
Mitigation: Implement an explicit loading state in OrganizationLabelsNotifier that widgets check before rendering any resolved labels. The provider graph should cancel the previous organization's fetch via Riverpod's ref.onDispose before initiating the next.
Contingency: If the race manifests in production, fall back to English defaults during the transition window and emit a Sentry error event for investigation; the UX impact is a brief English flash rather than wrong-org terminology.
Supabase Row Level Security policies on organization_configs may inadvertently restrict the authenticated user from reading their own organization's labels JSONB column, causing silent empty maps that appear as English fallbacks.
Mitigation & Contingency
Mitigation: Write and test explicit RLS policies that grant SELECT on the labels column to any authenticated user whose organization_id matches. Add an integration test that verifies label fetch succeeds for each role (peer mentor, coordinator, admin).
Contingency: If RLS blocks are discovered in production, temporarily escalate label fetch to a service-role edge function while the RLS policy is corrected, ensuring no labels are exposed cross-organization.
A peer mentor who installs the app for the first time with no internet connection will have no cached terminology map and will see only English defaults, which may be confusing for organizations like NHF that use Norwegian-specific role names exclusively.
Mitigation & Contingency
Mitigation: Bundle a default fallback terminology map for each known organization as a compile-time asset (Dart asset file) so that even fresh installs without connectivity render correct organizational terminology immediately.
Contingency: If bundled assets are out of date, display a one-time informational banner noting that terminology will update on next connectivity restore, with no functional blocking of the app.