Implement ContactChapterRepository CRUD operations
epic-multi-chapter-membership-handling-data-layer-task-002 — Implement the concrete Supabase-backed ContactChapterRepository class. Wire up to the supabase-contact-chapter-adapter (217) for all database interactions. Implement getChaptersForContact, addChapterAffiliation, removeChapterAffiliation, and updateAffiliation. Enforce the 5-affiliation maximum by querying the current count before any insert and throwing the domain exception if the limit would be exceeded. Use Supabase transactions where atomicity is required.
Acceptance Criteria
Technical Requirements
Execution Context
Tier 1 - 540 tasks
Can start after Tier 0 completes
Implementation Notes
Use Supabase's .count() modifier on the select query for the pre-insert count check rather than fetching all rows and counting in Dart — this is a single round-trip and accurate under concurrent writes. For the duplicate check, use .eq('contact_id', contactId).eq('chapter_id', chapterId).maybeSingle() — if result is non-null, throw AlreadyAssignedToChapterException. Note that Supabase PostgREST does not support multi-statement transactions natively from the client; if atomicity between count-check and insert is critical, implement this as a Supabase database function (RPC) called via .rpc(). Coordinate with the backend team on whether an RPC is needed or if an optimistic insert with a unique constraint + error catch is acceptable.
Testing Requirements
Write integration tests using a Supabase test environment (or a local Supabase instance via Docker) for the full CRUD cycle: add first affiliation, add fifth affiliation, attempt sixth (expect exception), remove, attempt to remove non-existent (expect exception). Also write unit tests with a mocked Supabase client to verify the count-check and duplicate-check logic without network calls. Integration tests go in test/integration/repositories/; unit tests in test/data/repositories/. Run unit tests in CI; gate integration tests separately.
The Cross-Chapter Activity Query must avoid N+1 fetches across chapters. If naively implemented as a per-chapter loop, it will cause severe performance degradation for contacts affiliated with 5 chapters on poor mobile connections.
Mitigation & Contingency
Mitigation: Design the query as a single PostgREST join of contact_chapters and activities on contact_id from the start. Add a query performance test with 5 affiliations and 100+ activities to the integration test suite and enforce a maximum execution time threshold.
Contingency: If a performance regression is detected post-merge, introduce a Supabase RPC function (stored procedure) to move the join server-side, bypassing any client-side N+1 pattern.
If the Duplicate Warning Event Logger write fails silently (network error, RLS denial), audit entries will be missing from the Bufdir compliance record without the user being aware.
Mitigation & Contingency
Mitigation: Implement the logger with a local fallback queue: if the Supabase write fails, persist the event locally and retry on next launch. Log all failures to a verbose output channel.
Contingency: Add a reconciliation job that compares locally queued events to Supabase entries and re-submits any gaps. Provide a data export of the local queue for manual audit if reconciliation fails.
Two coordinators simultaneously adding the 5th chapter affiliation for the same contact could bypass the maximum enforcement check if both reads occur before either write completes.
Mitigation & Contingency
Mitigation: Enforce the 5-affiliation maximum as a database-level constraint (CHECK + trigger or RPC with a FOR UPDATE lock) rather than relying solely on application-layer validation.
Contingency: If a constraint violation is detected in production, run a corrective query to end the most recently created excess affiliation and notify the relevant coordinator.