Implement Duplicate Reviewed Flag Middleware
epic-duplicate-activity-detection-state-management-task-003 — Create the infrastructure middleware that intercepts activity save operations and tags records with a duplicate-reviewed flag once the user has explicitly acknowledged or resolved a duplicate warning. This flag prevents re-triggering detection for already-reviewed conflicts and must integrate with the Supabase RLS policy layer.
Acceptance Criteria
Technical Requirements
Execution Context
Tier 1 - 540 tasks
Can start after Tier 0 completes
Implementation Notes
Implement the middleware as a Dart class following the decorator pattern: `DuplicateReviewedMiddleware implements ActivityRepository` wraps a delegate `ActivityRepository` and adds the flag logic before delegating to the wrapped save. This keeps the middleware testable in isolation without requiring a full BLoC stack. The ActivitySaveContext should be a value object (not a map) carrying typed optional fields including `duplicateReviewed: bool?`. Pitfall: using a separate UPDATE after the initial INSERT to set the flag creates a race condition if the activity is fetched between the two operations — always bundle the flag in the original upsert.
For the RLS policy, use a PostgreSQL column-level security check or a CHECK constraint combined with a role condition: `CHECK (duplicate_reviewed = false OR current_setting('role') = 'coordinator')`. Ensure the `duplicate_reviewed_at` column defaults to NULL (not a timestamp) so that unflagged activities are distinguishable from a flag set at epoch.
Testing Requirements
Unit tests using flutter_test: (1) save with duplicateReviewed=true includes duplicate_reviewed=true and duplicate_reviewed_at in the upsert payload; (2) save without duplicateReviewed context sends payload without the flag fields (no null overwrite); (3) ActivitySaveContext is correctly threaded through BLoC → repository → middleware without losing type safety; (4) middleware composes correctly when stacked with other hypothetical middleware (e.g., audit logging). Integration test against local Supabase: (1) insert an activity with duplicate_reviewed=true; (2) call check_activity_duplicates for the same peer_mentor + date + type; (3) assert the reviewed activity is excluded from results. RLS test: attempt to set duplicate_reviewed=true as a peer_mentor role user and assert PostgrestException with code 42501 (insufficient privilege).
For bulk registration with many participants, running duplicate checks sequentially before surfacing the consolidated summary could introduce a multi-second delay as each peer mentor is checked individually against the RPC. This degrades the bulk submission UX significantly.
Mitigation & Contingency
Mitigation: Issue all duplicate check RPC calls concurrently using Dart's `Future.wait` or a bounded parallel executor (max 5 concurrent calls to avoid Supabase rate limits). The BLoC collects all results and emits a single BulkDuplicateSummary state with the consolidated list.
Contingency: If concurrent RPC calls hit Supabase connection limits or rate limits, implement a batched sequential approach with a progress indicator showing 'Checking participant N of M' so the coordinator understands the delay is expected and bounded.
In proxy registration, the peer mentor's ID must be used as the duplicate check parameter, not the coordinator's ID. If the proxy context is not correctly threaded through the BLoC and service layer, duplicate checks will silently run against the wrong person, missing actual duplicates.
Mitigation & Contingency
Mitigation: Define a `SubmissionContext` model that carries the effective `peer_mentor_id` (distinct from `submitter_id`) and pass it explicitly through the BLoC event payload. The DuplicateDetectionService always reads peer_mentor_id from SubmissionContext, never from the authenticated user session.
Contingency: If SubmissionContext threading proves difficult to retrofit into the existing proxy registration BLoC, add an assertion in DuplicateDetectionService that throws a descriptive error when peer_mentor_id is null or matches the coordinator's own ID in a proxy context, making the bug immediately visible in testing.