Implement PostGIS spatial query adapter
epic-geographic-peer-mentor-map-data-infrastructure-task-008 — Implement the PostgisSpatialAdapter class that translates flutter_map LatLngBounds into Supabase RPC call parameters (min_lat, min_lng, max_lat, max_lng). Wrap the Supabase RPC invocation, handle network errors with typed exceptions, map the raw response rows into MentorLocationResult domain objects, and expose a queryMentorsInBounds(LatLngBounds bounds, String orgId) method consumed by the repository.
Acceptance Criteria
Technical Requirements
Execution Context
Tier 5 - 253 tasks
Can start after Tier 4 completes
Implementation Notes
Place at lib/features/map/data/postgis_spatial_adapter.dart. The adapter is a thin translation layer — keep it under 100 lines. The distinction from MentorLocationRepository: the adapter owns the RPC invocation detail (parameter names, response shape), while the repository owns domain logic (consent validation, caching policy). This separation allows swapping the spatial backend (e.g.
to a different RPC or REST endpoint) without touching repository logic. For LatLngBounds from flutter_map/latlong2: bounds.southWest.latitude = min_lat, bounds.southWest.longitude = min_lng, bounds.northEast.latitude = max_lat, bounds.northEast.longitude = max_lng. Define SpatialQueryException as: class SpatialQueryException implements Exception { final String message; final Object? cause; const SpatialQueryException(this.message, {this.cause}); }.
For malformed rows in the response, use a try/catch around fromJson() inside the map() call and log the error with debugPrint in kDebugMode — return null and then whereType
Testing Requirements
Unit tests (flutter_test with mocktail): (1) queryMentorsInBounds maps LatLngBounds correctly to RPC params (assert south→min_lat, west→min_lng, north→max_lat, east→max_lng), (2) successful RPC response maps to List
Supabase's hosted PostGIS extension behaviour may differ from the local emulator for spatial RPC functions, causing bounding-box queries to return incorrect results or fail in production while passing locally.
Mitigation & Contingency
Mitigation: Write integration tests against the Supabase emulator from the start and run the same test suite against a staging Supabase project before merging. Use ST_DWithin and ST_MakeEnvelope in plain SQL first, validate with psql, then wrap as RPC.
Contingency: If PostGIS RPC proves unreliable, fall back to client-side bounding box filtering on a full fetch of consented mentor locations (acceptable for up to ~200 mentors per chapter) until the spatial query is stabilised.
OpenStreetMap tile usage may require attribution handling and rate limiting. Switching to Google Maps Flutter plugin mid-implementation would require significant rework of the map-provider-integration abstraction.
Mitigation & Contingency
Mitigation: Define the map-provider-integration abstraction interface before selecting the SDK so that the concrete implementation is swappable. Implement OSM first with correct attribution. Document Google Maps as the alternate with its API key setup steps.
Contingency: If OSM tiles are rejected by stakeholders or tile server limits are hit, activate the Google Maps Flutter plugin implementation behind the same interface without touching any UI or service code.
Incorrect RLS configuration could allow a coordinator to query mentor locations from a different organisation, constituting a GDPR data breach.
Mitigation & Contingency
Mitigation: Write dedicated RLS integration tests with two isolated test organisations and assert that cross-organisation queries return zero rows. Include these tests in CI. Have a second developer review all RLS policy SQL before migration is applied.
Contingency: If a cross-organisation data leak is discovered post-deployment, immediately disable the map feature via the organisation feature flag, revoke the affected Supabase RLS policy, and notify the data protection officer per the organisation's GDPR incident response procedure.