satellite-provider/_docs/02_document/modules/dataaccess_tile_repository.md

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 for the given slippy coordinates. Selection rule: ORDER BY captured_at DESC, updated_at DESC, id DESC LIMIT 1 (AZ-484 v1.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.
• 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-503 does NOT rewrite the read path to use location_hash — that's deferred to AZ-505 alongside the Leaflet covering index.
• 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 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 v1.0.0 contract _docs/02_document/contracts/data-access/tile-storage.md plus the AZ-503-introduced columns (flight_id, location_hash, content_sha256, legacy_id) and the integer-only UPSERT key. Schema invariants Inv-1..Inv-5 (UPSERT semantics, selection rule, source value space) are preserved; the only contract change is that the UPSERT conflict detection no longer depends on bit-identical float latitude/longitude (AZ-503 AC-4).

Consumers

• TileService — all read/write operations
• Program.cs (ServeTile, GetTileByLatLon handlers) — GetByTileCoordinatesAsync, InsertAsync

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.