# Module: DataAccess/Repositories/RouteRepository

## Purpose
Dapper-based repository for the `routes`, `route_points`, and `route_regions` tables. Handles route persistence, point storage, and route-region linking (including geofence metadata).

## Public Interface

### IRouteRepository (interface)
- `GetByIdAsync(Guid id) → Task<RouteEntity?>`
- `GetRoutePointsAsync(Guid routeId) → Task<IEnumerable<RoutePointEntity>>`: ordered by `sequence_number`
- `InsertRouteAsync(RouteEntity route) → Task<Guid>`
- `InsertRoutePointsAsync(IEnumerable<RoutePointEntity> points) → Task`: bulk insert
- `UpdateRouteAsync(RouteEntity route) → Task<int>`
- `DeleteRouteAsync(Guid id) → Task<int>`
- `LinkRouteToRegionAsync(Guid routeId, Guid regionId, bool isGeofence, int? geofencePolygonIndex) → Task`: inserts into `route_regions` with `ON CONFLICT DO NOTHING`
- `GetRegionIdsByRouteAsync(Guid routeId) → Task<IEnumerable<Guid>>`: non-geofence region IDs
- `GetGeofenceRegionIdsByRouteAsync(Guid routeId) → Task<IEnumerable<Guid>>`: geofence-only region IDs
- `GetGeofenceRegionsByPolygonAsync(Guid routeId) → Task<Dictionary<int, List<Guid>>>`: groups geofence regions by polygon index
- `GetRoutesWithPendingMapsAsync() → Task<IEnumerable<RouteEntity>>`: routes where `request_maps = true AND maps_ready = false`

### RouteRepository (implementation)
Same connection-per-call pattern. `InsertRoutePointsAsync` uses Dapper's bulk execute to insert all points in a single round-trip.

## Internal Logic
- `LinkRouteToRegionAsync` uses `ON CONFLICT DO NOTHING` to handle duplicate links gracefully
- `GetGeofenceRegionsByPolygonAsync` groups results into a dictionary keyed by `geofence_polygon_index`
- `GetRoutesWithPendingMapsAsync` drives the `RouteProcessingService` polling loop

## Dependencies
- NuGet: `Dapper`, `Npgsql`
- `SatelliteProvider.DataAccess.Models.RouteEntity`, `RoutePointEntity`
- `Microsoft.Extensions.Logging`

## Consumers
- `RouteService` — insert route, points, link regions
- `RouteProcessingService` — read route state, points, region links; update route after map generation

## Data Models
Operates on `RouteEntity`, `RoutePointEntity`, and the `route_regions` junction table.

## Configuration
Connection string via constructor.

## External Integrations
PostgreSQL.

## Security
None.

## Tests
No dedicated tests.