# Module: DataAccess/Repositories/TileRepository

## Purpose
Dapper-based repository for the `tiles` table. Handles CRUD operations and spatial queries for satellite tile records.

## Public Interface

### ITileRepository (interface)
- `GetByIdAsync(Guid id) → Task<TileEntity?>`
- `GetByTileCoordinatesAsync(int tileZoom, int tileX, int tileY) → Task<TileEntity?>`: finds the most-recent tile across all sources / flights for the given slippy coordinates. AZ-505 rewired the predicate to compute `location_hash = Uuidv5(TileNamespace, "{z}/{x}/{y}")` and filter by `WHERE location_hash = $1` so the read becomes an `Index Only Scan` against `tiles_leaflet_path`. Selection rule preserved unchanged: `ORDER BY captured_at DESC, updated_at DESC, id DESC LIMIT 1` (v2.0.0 contract).
- `GetTilesByRegionAsync(double lat, double lon, double sizeMeters, int zoomLevel) → Task<IEnumerable<TileEntity>>`: spatial bounding box query (expanded by 2 × tile size to cover edges); applies `DISTINCT ON (latitude, longitude, tile_zoom, tile_size_meters)` per AZ-484 to return at most one row per cell — the most-recent across sources — preserving the historical caller-facing order `latitude DESC, longitude ASC`.
- `GetTilesByLocationHashesAsync(IReadOnlyList<Guid> locationHashes) → Task<IReadOnlyDictionary<Guid, TileEntity>>` (AZ-505): bulk lookup keyed by `location_hash` for the inventory endpoint. Single round-trip; `DISTINCT ON (location_hash) ... WHERE location_hash = ANY($1::uuid[]) ORDER BY location_hash, captured_at DESC, updated_at DESC, id DESC`. NOT routed through Dapper — uses `NpgsqlCommand` with an explicit `NpgsqlParameter` typed `Array | Uuid` because Dapper's parameter expander rewrites `IEnumerable` to scalar placeholders, which is invalid against `ANY($1::uuid[])`.
- `InsertAsync(TileEntity tile) → Task<Guid>`: AZ-503 integer-only + flight-aware UPSERT — `ON CONFLICT (tile_zoom, tile_x, tile_y, tile_size_meters, source, COALESCE(flight_id, '00000000-0000-0000-0000-000000000000'::uuid)) DO UPDATE file_path, latitude, longitude, captured_at, location_hash, content_sha256, updated_at`. `id` is intentionally NOT overwritten on conflict — preserves AZ-503 AC-2 idempotence (same inputs ⇒ same `id`). Supersedes the AZ-484 5-column float-based unique key (`idx_tiles_unique_location_source`).
- `UpdateAsync(TileEntity tile) → Task<int>`: full row update by `id` including `source`, `captured_at`, `flight_id`, `location_hash`, and `content_sha256`.
- `DeleteAsync(Guid id) → Task<int>`

### TileRepository (implementation)
Constructs a new `NpgsqlConnection` per method call (no connection pooling at the repository level; Npgsql pools connections internally). Logs a `Slow GetTilesByRegionAsync` warning when the region query exceeds 500 ms.

## Internal Logic
- `GetTilesByRegionAsync` calculates a bounding box by expanding the requested region by 2 × tile size to ensure edge tiles are included. Uses meters-to-degrees approximation via `GeoUtils` (post-AZ-377 — single source of truth for Earth constants).
- `InsertAsync` uses the AZ-503 integer-only + flight-aware UPSERT keyed on `idx_tiles_unique_identity` (created by migration 014, replacing the AZ-484 `idx_tiles_unique_location_source`). The conflict key uses `COALESCE(flight_id, '00000000-0000-0000-0000-000000000000'::uuid)` so anonymous (`flight_id IS NULL`) and per-flight UAV rows share a flat key space. Two producers (`google_maps` + `uav`) at the same cell with the same `flight_id` (typically `NULL` for `google_maps`) still coexist via `source` discrimination. Same-source same-flight re-insert refreshes `file_path`, `latitude`, `longitude`, `captured_at`, `location_hash`, `content_sha256`, `updated_at` — but NOT `id` (idempotence — AZ-503 AC-2).
- `GetByTileCoordinatesAsync` and `GetTilesByRegionAsync` apply the AZ-484 selection rule unchanged: most-recent across sources, deterministic tie-break on `(captured_at DESC, updated_at DESC, id DESC)`. AZ-505 rewrote `GetByTileCoordinatesAsync` to filter on `location_hash` instead of `(tile_zoom, tile_x, tile_y)` — this is a behavior-preserving rewrite (deterministic UUIDv5) that enables `Index Only Scan` against `tiles_leaflet_path`. `GetTilesByRegionAsync` retains the lat/lon filter because spatial bounding-box queries don't reduce to a finite hash-set lookup.
- `GetTilesByLocationHashesAsync` (AZ-505) is the inventory hot path. Deliberately bypasses Dapper because the `ANY($1::uuid[])` predicate requires array-typed parameter binding (Npgsql `NpgsqlDbType.Array | Uuid`) that Dapper's `IEnumerable` parameter expansion replaces with a comma-separated list of scalar placeholders, producing invalid SQL. Manual `NpgsqlDataReader` mapping to `TileEntity` is the trade-off. Slow-query threshold matches `GetTilesByRegionAsync` (500 ms).
- `TileEntity.Source` is a plain `string` storing the snake_case wire value (`'google_maps'` | `'uav'`); enum<->wire conversion happens via `SatelliteProvider.Common.Enums.TileSourceConverter`. This avoids Dapper issue #259 (TypeHandler<T> bypass for enum reads — see `_docs/LESSONS.md` L-001).
- `FindExistingTileAsync` was removed by AZ-376 (see `_docs/04_refactoring/03-code-quality-refactoring/`).

## Dependencies
- NuGet: `Dapper`, `Npgsql`
- `SatelliteProvider.DataAccess.Models.TileEntity`
- `SatelliteProvider.Common.GeoUtils` (Earth constants / meters-to-degrees)
- `Microsoft.Extensions.Logging`

## Contract
Implements the frozen v2.0.0 contract `_docs/02_document/contracts/data-access/tile-storage.md` — captures the four AZ-503-foundation columns (`flight_id`, `location_hash`, `content_sha256`, `legacy_id`), the integer-only flight-aware UPSERT key (`idx_tiles_unique_identity`), the `tiles_leaflet_path` covering index (AZ-505 migration 015), the new `location_hash`-keyed `GetByTileCoordinatesAsync` read path (AZ-505), and the new `GetTilesByLocationHashesAsync` bulk lookup (AZ-505). Inv-1..Inv-9 from the v2.0.0 contract apply.

## Consumers
- `TileService` — all read/write operations including `GetInventoryAsync` (AZ-505) which routes through `GetTilesByLocationHashesAsync`
- `Program.cs` (ServeTile, GetTileByLatLon, `GetTilesInventory` handlers) — `GetByTileCoordinatesAsync`, `InsertAsync`, indirectly `GetTilesByLocationHashesAsync` via `TileService.GetInventoryAsync`

## Data Models
Operates on `TileEntity`.

## Configuration
Receives connection string via constructor.

## External Integrations
PostgreSQL — SQL queries via Dapper + Npgsql.

## Security
None.

## Tests
No dedicated repository tests.
