Define domain interfaces and conflict metadata models
epic-proxy-activity-registration-core-services-task-001 — Define the abstract service interfaces and data transfer objects for both domain services. This includes the DuplicateCheckRequest, DuplicateConflictResult (with original submitter ID, timestamp, and activity record reference), AttributionRecord, and ProxyAuditQueryFilter models. Establishes the contract both services must fulfill before any implementation begins.
Acceptance Criteria
Technical Requirements
Execution Context
Tier 0 - 440 tasks
Implementation Notes
Place all interfaces and DTOs under lib/domain/proxy/ in a flat structure: duplicate_check_request.dart, duplicate_conflict_result.dart, attribution_record.dart, proxy_audit_query_filter.dart, i_duplicate_detection_service.dart, i_activity_attribution_service.dart, attribution_validation_error.dart. Use freezed or manual immutable classes — if using freezed, ensure build_runner is already configured in the project. Do NOT couple these models to Supabase types at this layer; keep them pure domain objects. The composite key (peer_mentor_id, date, activity_type_id) should be encapsulated as a value object to avoid parameter ordering errors in batch calls.
ConflictType enum should at minimum include: exact_match, same_day_same_type, overlapping_time_window.
Testing Requirements
Unit tests using flutter_test for all models: JSON serialization round-trip, copyWith correctness, Equatable equality checks, and null-safety boundary conditions. Test that AttributionValidationError carries correct field metadata. No integration or widget tests required at this layer — pure Dart unit tests only. Minimum 90% line coverage on all model files.
Overly strict duplicate matching (exact date + type) may flag legitimate back-to-back sessions of the same activity type on the same day as duplicates, frustrating coordinators and undermining trust in the feature.
Mitigation & Contingency
Mitigation: Confirm with product owners whether the matching key should be (mentor_id, date, activity_type_id) only or should also consider duration and time-of-day. Document the chosen threshold in the service and surface it in the duplicate warning dialog for transparency.
Contingency: If false-positive rates are high in user testing, add a duration-window tolerance parameter to the detection query that can be tuned without code changes.
If the current session token is invalidated between the coordinator starting the proxy form and submitting it, the activity-attribution-service may fail to resolve the coordinator's user ID, causing a silent attribution error.
Mitigation & Contingency
Mitigation: Read the coordinator's user ID from the session at service call time rather than at form-open time. Validate the session is still active before committing the insert, and surface a clear re-authentication prompt if it has expired.
Contingency: If a mis-attributed record is detected post-submission, the audit log retains the original session metadata, allowing a corrective record to be created with accurate attribution.