Implement BatchInsertRpcAdapter Dart Class
epic-bulk-and-proxy-registration-foundation-task-003 — Build the BatchInsertRpcAdapter infrastructure component in Dart that wraps the insert_bulk_activities Supabase RPC function. Expose a typed insertBatch(List<ActivityRecord> records) method that serializes payloads, calls the RPC, deserializes the response IDs, and propagates database-level errors as typed Dart exceptions. Register the adapter as a Riverpod provider so dependent services can inject it.
Acceptance Criteria
Technical Requirements
Execution Context
Tier 2 - 518 tasks
Can start after Tier 1 completes
Implementation Notes
Place the adapter in lib/infrastructure/supabase/ following the project layer conventions. Define ActivityRecord.toRpcPayload() as a separate method from the existing toJson() to avoid coupling the DB wire format to other serialization uses. Use final class modifier to prevent accidental subclassing. For the Riverpod registration, use Provider rather than StateProvider since the adapter is stateless.
Consider adding a debug-mode request/response logger behind a kDebugMode guard for easier local development. The typed exception hierarchy (BatchInsertException, BatchSizeExceededException) should be defined in a shared exceptions file, not inside the adapter file, for reuse by other RPC adapters.
Testing Requirements
Write flutter_test unit tests using a mock Supabase client (mockito or manual stub): (1) happy path returns list of ID strings matching mock response, (2) PostgrestException is rethrown as BatchInsertException with correct message, (3) empty list returns empty list without calling RPC, (4) list of 201 records throws BatchSizeExceededException before RPC call, (5) network timeout throws NetworkException. Write one integration test against a local Supabase instance that performs a real RPC call with 3 records and verifies returned IDs. Achieve > 90% line coverage on the adapter class.
Adding recorded_by_user_id to the activities table and writing correct RLS policies is error-prone: overly permissive policies would allow coordinators to record activities under arbitrary user IDs they do not manage, while overly restrictive policies would silently block valid proxy inserts. A policy defect here would either create a security vulnerability or break the entire proxy feature at runtime.
Mitigation & Contingency
Mitigation: Write RLS policies in a local Supabase emulator first. Include policy unit tests using pg_tap or supabase test helpers. Have a second reviewer check the migration SQL before merging. Explicitly test the three cases: coordinator inserting for their own mentors (should succeed), coordinator inserting for another chapter's mentors (should fail), peer mentor inserting for themselves (should succeed as before).
Contingency: If a policy defect is discovered in staging, roll back the migration with a down-migration script. Delay feature release until the policy is corrected and re-verified. Apply a feature flag to keep the proxy entry point hidden from coordinators until the fix is confirmed.
The insert_bulk_activities RPC must behave atomically — a failure on row 7 of 12 must roll back rows 1–6. If Supabase's RPC transaction handling is misconfigured or if network interruptions cause partial acknowledgements, some peer mentors could receive duplicate or missing activity records, directly corrupting Bufdir statistics for the coordinator's chapter.
Mitigation & Contingency
Mitigation: Implement the RPC as a PostgreSQL function with explicit BEGIN/EXCEPTION/END block to guarantee atomicity. Add an integration test that inserts a batch where one row violates a unique constraint and asserts zero rows are committed. Document the transaction semantics in code comments.
Contingency: If atomicity cannot be guaranteed via RPC (e.g., due to Supabase plan limitations), fall back to a sequential insert loop with a compensating DELETE in case of partial failure, and surface a clear error to the coordinator listing which mentors failed and which succeeded.