[AZ-484] Multi-source tile storage: source + captured_at

Add per-source tile rows to support multi-provider imagery (Google
Maps + future UAV). Migration 013 (transactional) introduces
source/captured_at columns, backfills existing rows to
(source='google_maps', captured_at=created_at), and replaces the
4-column unique index with a 5-column index that includes source.

TileRepository:
- ColumnList includes source + captured_at
- GetByTileCoordinatesAsync returns most-recent row across sources
  (ORDER BY captured_at DESC, updated_at DESC, id DESC)
- GetTilesByRegionAsync uses DISTINCT ON to pick the most-recent
  tile per cell, restoring caller-facing row order
- Insert/Update upsert on the new 5-column conflict key

TileSource enum lives in Common.Enums. Snake_case wire format
(google_maps, uav) is enforced by a focused TileSourceTypeHandler
because the generic ToLowerInvariant pattern would emit
"googlemaps", violating contract v1.0.0.

TileService stamps Source=GoogleMaps + CapturedAt=UtcNow on every
new tile. Tile-storage contract is now frozen at v1.0.0.

AC coverage 7/7. New unit + integration tests cover all ACs;
existing 200 unit + 5 smoke tests preserved.

Co-authored-by: Cursor <cursoragent@cursor.com>
This commit is contained in:
Oleksandr Bezdieniezhnykh
2026-05-11 06:21:59 +03:00
parent 5ba58b6c8d
commit 687d6bdd5b
21 changed files with 884 additions and 48 deletions
@@ -0,0 +1,45 @@
# Product Implementation Completeness Gate — cycle 1
**Date**: 2026-05-11
**Cycle**: 1
**Tasks evaluated**: AZ-484
**Verdict**: PASS
## Per-Task Classification
### AZ-484 — Multi-source tile storage schema (source + captured_at) — **PASS**
**Evidence checked**:
| Promise from spec | Production evidence |
|--------------------|---------------------|
| Migration 013 transactional, with column adds, backfill, index swap | `SatelliteProvider.DataAccess/Migrations/013_AddTileSourceAndCapturedAt.sql` (BEGIN/COMMIT, ALTER ADD COLUMN, UPDATE backfill, ALTER SET NOT NULL, DROP INDEX, CREATE UNIQUE INDEX) |
| `TileSource` enum in Common.Enums | `SatelliteProvider.Common/Enums/TileSource.cs` (`{ GoogleMaps, Uav }`) |
| `TileEntity` exposes `Source` + `CapturedAt` | `SatelliteProvider.DataAccess/Models/TileEntity.cs` |
| Repository read selection is most-recent across sources, deterministic | `TileRepository.GetByTileCoordinatesAsync` + `GetTilesByRegionAsync` (DISTINCT ON with `(captured_at DESC, updated_at DESC, id DESC)` tie-break) |
| Per-source UPSERT semantics on insert | `TileRepository.InsertAsync` (`ON CONFLICT (latitude, longitude, tile_zoom, tile_size_meters, source) DO UPDATE`) |
| `UpdateAsync` includes the new fields | `TileRepository.UpdateAsync` SET clause |
| Google Maps download path stamps `Source` + `CapturedAt` | `TileService.BuildTileEntity` |
| Snake_case wire format for `TileSource` | `TileSourceTypeHandler` (registered in `DapperEnumTypeHandlers.RegisterAll`) |
| Architecture Vision amended | `_docs/02_document/architecture.md` (Architecture Vision principles + System Context) |
| Glossary amended | `_docs/02_document/glossary.md` (`Tile Source`, `Captured At`; Layer 1 / Layer 2 disambiguation) |
| Module-layout amended | `_docs/02_document/module-layout.md` (Common Public API list) |
| Contract `tile-storage.md` v1.0.0 frozen | `_docs/02_document/contracts/data-access/tile-storage.md` Status: `frozen` |
**Unresolved markers** (`TODO`, `placeholder`, `NotImplemented`, etc.) under owned files (`SatelliteProvider.Common/Enums/TileSource.cs`, `SatelliteProvider.DataAccess/Migrations/013_AddTileSourceAndCapturedAt.sql`, `SatelliteProvider.DataAccess/TypeHandlers/TileSourceTypeHandler.cs`): none found.
**Named runtime dependencies**: AZ-484 introduces no new external dependency. It uses the existing Dapper / Npgsql / DbUp stack already integrated. The new `TileSourceTypeHandler` is wired into `DapperEnumTypeHandlers.RegisterAll`, which is invoked at API startup as part of DI registration.
**Internal vs external**: every promised capability is an internal product capability and is implemented in production code. No promise is blocked on an external prerequisite. The deferred AZ-485 (UAV upload endpoint) is explicitly out of scope for this task.
**Tests exercise real implementation path**:
- Unit: `BuildTileEntity_SetsGoogleMapsSourceAndUtcCapturedAt_AZ484_AC5` calls the real `TileService.DownloadAndStoreSingleTileAsync` path.
- Integration (migration): the AC-1..AC-4 tests run against the real Postgres container, asserting the live schema (5-column unique index, dropped legacy 4-column index) and the SQL semantics of the repository methods.
## Cycle Verdict
All product tasks (1/1) classified PASS. Proceeding to Final Test Run handoff (autodev Step 11).
## Remediation Tasks Created
None.