Define ActivityRecord data model and Dart types
epic-quick-activity-registration-data-infrastructure-task-001 — Define the ActivityRecord Dart class with all required fields (id, activityTypeId, date, durationMinutes, notes, peerId, orgId, createdAt, syncStatus). Include a temporary local ID strategy (UUID prefixed with 'local_') for optimistic inserts, a SyncStatus enum (pending, synced, failed), and fromJson/toJson serialization. This model is the shared contract consumed by all layers in this epic.
Acceptance Criteria
Technical Requirements
Implementation Notes
Use the uuid Dart package (already likely in pubspec) for UUID generation. Keep the model in the data layer (not domain) since it contains serialization logic. If the project uses freezed or equatable, apply those annotations rather than hand-writing == and copyWith — check existing models in the codebase for the established pattern and match it. The 'local_' prefix convention is critical for the sync layer to distinguish optimistic records from server-confirmed records — document this contract in a code comment.
Avoid using dynamic in fromJson — cast explicitly and handle missing keys with null-coalescence for optional fields.
Testing Requirements
Unit tests in test/features/activity_registration/data/models/activity_record_test.dart. Test fromJson round-trip: serialize a known ActivityRecord to JSON and deserialize back, assert all fields are equal to original. Test localOptimistic() factory: assert id starts with 'local_', is a valid UUID after the prefix, and syncStatus == SyncStatus.pending. Test equality: two ActivityRecords with the same id but different notes are equal.
Test copyWith: changing a single field produces a new instance with only that field changed. Test fromJson handles null notes field without throwing.
The optimistic insert pattern requires reconciling temporary local IDs with server-assigned IDs after the async Supabase write completes. If reconciliation logic is incorrect, the UI may display stale records, duplicate entries may appear, or subsequent operations (edit, delete) may target the wrong record ID, corrupting data integrity.
Mitigation & Contingency
Mitigation: Define a clear contract for temporary ID generation (e.g., UUID prefixed with 'local-') and implement a dedicated reconciliation method in ActivityRepository that atomically swaps the temporary ID. Write integration tests that simulate the full optimistic → confirm cycle.
Contingency: If reconciliation proves too complex, fall back to a simpler non-optimistic insert with a loading spinner for the network round-trip. The UX degrades slightly but correctness is preserved. Re-introduce optimistic behaviour once the pattern is stable.
Supabase row-level security policies on the activities table may not be configured to match the access patterns required by the client. If RLS blocks inserts or selects for the authenticated peer mentor session, all activity registration operations will silently fail or return empty results, which is difficult to diagnose in production.
Mitigation & Contingency
Mitigation: Define and test RLS policies in a dedicated Supabase migration script as part of this epic. Create integration tests that execute against a local Supabase instance with RLS enabled, covering insert, select by peer mentor ID, and denial of cross-mentor access.
Contingency: Maintain a fallback service-role client path (server-side only) that can be activated via a feature flag if client-side RLS is blocking legitimate operations while policies are corrected.
SharedPreferences on Flutter can become corrupted if the app crashes mid-write or if the device runs out of storage. A corrupted last-used activity type preference would cause the defaults manager to return null or an invalid ID, breaking the zero-interaction happy path.
Mitigation & Contingency
Mitigation: Wrap all LocalStorageAdapter reads in try/catch with typed safe defaults. Validate the retrieved activity type ID against the known list before returning it. Use atomic write operations where the platform supports them.
Contingency: If the preference store is corrupted, silently reset to the hardcoded default (first activity type alphabetically or 'general') and log a warning. The user loses their last-used preference but the app remains functional.