Define MentorLocationService interface and failure types
epic-geographic-peer-mentor-map-core-services-task-003 — Define the abstract MentorLocationService interface with methods: fetchMentorsInBoundingBox(box, criteria), getMentorsSortedByDistance(origin, criteria), and clearCache(). Define sealed failure classes: ConsentCheckFailure, NetworkFailure, CacheFailure, ValidationFailure. This contract is required before any implementation or BLoC work begins.
Acceptance Criteria
Technical Requirements
Execution Context
Tier 1 - 540 tasks
Can start after Tier 0 completes
Implementation Notes
Use Dart's abstract interface class keyword (Dart 3+) rather than abstract class to signal that this is a pure interface with no default implementations. Define the sealed failure hierarchy in a separate file mentor_location_failure.dart alongside the interface. Choose Either
The FakeMentorLocationService should expose a call log so BLoC tests can assert fetchMentorsInBoundingBox was called with the expected arguments.
Testing Requirements
No tests required for the interface itself. However, create FakeMentorLocationService in test/fakes/fake_mentor_location_service.dart that implements MentorLocationService with configurable responses (e.g., setNextResponse(Either result)).
This fake will be used by all downstream BLoC tests. Write one smoke test confirming FakeMentorLocationService correctly implements all three method signatures at compile time.
The dual BLoC state machines (map view state + filter state) may introduce subtle synchronisation bugs where filter changes do not correctly re-trigger viewport queries, causing stale data to appear on the map.
Mitigation & Contingency
Mitigation: Define all BLoC state transitions in a state diagram before implementation. Use flutter_bloc's BlocObserver in development mode to log every state transition. Write explicit unit tests for filter-change → re-query transitions.
Contingency: If state synchronisation bugs appear in integration testing, refactor to a single unified BLoC that owns both map viewport state and filter state, eliminating cross-BLoC dependencies.
Cached mentor location data may become stale (mentors move, pause, or revoke consent) and coordinators in offline mode could be shown incorrect mentor information, leading to wasted outreach.
Mitigation & Contingency
Mitigation: Display a clear timestamp on cached data indicating when it was last synced. Set cache TTL to 24 hours and show an 'offline — data from [date]' banner. Revoked consent removes the mentor from the cache on next successful sync via contact-cache-sync-repository.
Contingency: If cache staleness causes user complaints, reduce TTL to 4 hours and implement background sync on app foreground. Accept that very-recently-revoked mentors may appear briefly in offline mode — document this as a known limitation in the privacy policy.