Implement feature flag repository with Supabase data access
epic-organization-feature-flags-foundation-task-004 — Build the FeatureFlagRepository class that reads and persists feature flag records from the organization_configs Supabase table. All queries must be scoped by organization_id. Implement getFlag(orgId, flagKey), getAllFlags(orgId), and setFlag(orgId, flagKey, value) methods with proper error handling and typed return values using flag key constants.
Acceptance Criteria
Technical Requirements
Execution Context
Tier 2 - 518 tasks
Can start after Tier 1 completes
Implementation Notes
Use `supabase.from('organization_configs').select().eq('organization_id', orgId).eq('flag_key', flagKey).maybeSingle()` for `getFlag` — `maybeSingle()` returns null on no match without throwing, which maps cleanly to `false`. For `getAllFlags`, use `.select('flag_key, flag_value').eq('organization_id', orgId)` and convert the list to a Map. For `setFlag`, use `.upsert({'organization_id': orgId, 'flag_key': flagKey, 'flag_value': value}, onConflict: 'organization_id,flag_key')`. Define `FeatureFlagRepositoryException` as a domain exception class, not re-throwing raw Supabase exceptions, so the caller is decoupled from the Supabase SDK.
Register the repository with Riverpod as a `Provider
Testing Requirements
Unit tests using `mocktail` to mock `SupabaseClient` and `SupabaseQueryBuilder`. Test cases: (1) `getFlag` returns true when Supabase returns a matching enabled row; (2) `getFlag` returns false when no row found (empty result); (3) `getFlag` throws `FeatureFlagRepositoryException` on `PostgrestException`; (4) `getAllFlags` returns correct map from multi-row response; (5) `setFlag` calls upsert with correct payload including orgId and flagKey; (6) `setFlag` throws on network error. Integration tests against local Supabase instance: verify RLS blocks cross-org access at the repository level. Minimum 90% branch coverage on the repository class.
Run via `flutter test`.
Supabase RLS policies for organization_configs may have gaps that allow cross-organization reads if the JWT claim for organization_id is absent or malformed, leading to data leakage between tenants.
Mitigation & Contingency
Mitigation: Implement RLS policies using auth.uid() joined against a memberships table to derive organization_id rather than trusting a client-supplied claim. Write integration tests that simulate a cross-org read attempt and assert it returns zero rows.
Contingency: If a gap is discovered post-launch, immediately disable the affected RLS policy, roll back the migration, and re-implement with a parameterized policy tested against all organization fixture data.
Dart does not have a built-in semantic version comparison library; a naive string comparison (e.g., '2.10.0' < '2.9.0' lexicographically) would cause rollout evaluator to produce incorrect eligibility results for organizations on different app versions.
Mitigation & Contingency
Mitigation: Use the pub.dev `pub_semver` package or implement a proper three-segment integer comparison. Add parameterized unit tests covering 20+ version pairs including double-digit minor/patch segments.
Contingency: If incorrect comparison is discovered in production, push a hotfix with corrected comparison logic and temporarily disable phase-gated flags until all affected organizations have updated to the corrected version.
Persistent local cache written to shared_preferences or Hive could become corrupted or deserialized incorrectly after an app update changes the FeatureFlag schema, causing startup crashes or all flags defaulting to disabled.
Mitigation & Contingency
Mitigation: Wrap all cache reads in try/catch with explicit fallback to the all-disabled default map. Version the cache key (e.g., `feature_flags_v2_{orgId}`) so schema changes automatically invalidate old entries.
Contingency: If cache corruption is detected in a release, publish an app update that clears the versioned cache key on first launch and re-fetches from Supabase.