mirror of
https://github.com/azaion/satellite-provider.git
synced 2026-06-21 15:31:14 +00:00
Oleksandr Bezdieniezhnykh
5d84d2839e
Step 12 (Test-Spec Sync, cycle-update mode): - blackbox-tests.md: append BT-23..BT-26 for AZ-505's new observable behaviors (inventory order/shape; leaflet most-recent via location_hash; HTTP/2 multiplex over TLS+ALPN; request validation). - performance-tests.md: append PT-09 (inventory p95 ≤ 1000ms / 2500 tiles); records cycle-6 measured p95=66ms; documents promotion path to scripts/run-performance-tests.sh if budget ever tightens. - traceability-matrix.md: resolve the 5 AZ-503 deferrals (AC-5/6/9/10/12) by pointing at AZ-505 test names + add 7 AZ-505 AC rows (AC-1..AC-7) + bump totals (90 -> 94 tests, 56/56 -> 63/63 in-scope) + add cycle-6 coverage shape notes (budget relaxation rationale, voting-filter deferral note, TLS+ALPN pivot, NFR propagation). Step 13 (Update Docs, task mode): - common_dtos.md: add 5 new TileInventory DTOs. - common_interfaces.md: add ITileService.GetInventoryAsync. - services_tile_service.md: document TileService.GetInventoryAsync steps + the XOR-validation-in-handler note. - dataaccess_migrator.md: bump migration count 14 -> 15; describe migration 015 (AZ-505 leaflet covering index, lock window, INCLUDE-list trade-off). - system-flows.md: add F7 (Leaflet Tile Serving, AZ-310 + AZ-505 location_hash rewire + TLS+ALPN) and F8 (Tile Inventory Bulk Lookup) with sequence diagrams, validation surface, and AC-4 perf evidence. Update Flow Inventory + Dependencies tables accordingly. - glossary.md: add "Tile Inventory" entry pointing at the v1.0.0 contract. - ripple_log_cycle6.md: new file — exhaustive reverse-dependency analysis confirms zero stale downstream module docs. Advance autodev state from step 11 -> 14 (skipping 12+13 as completed in this commit; auto-chain through Step 14 = Security Audit optional gate). Co-authored-by: Cursor <cursoragent@cursor.com>
60 lines
3.9 KiB
Markdown
60 lines
3.9 KiB
Markdown
# Module: Common/Interfaces
|
|
|
|
## Purpose
|
|
Service contracts defining the application's core operations. Implementations live in the per-component service projects (`SatelliteProvider.Services.TileDownloader`, `SatelliteProvider.Services.RegionProcessing`, `SatelliteProvider.Services.RouteManagement`). Cross-component runtime calls between Layer-3 components flow exclusively through these interfaces — there are no compile-time `ProjectReference` entries between the three sibling service projects.
|
|
|
|
## Public Interface
|
|
|
|
### ITileService
|
|
- `DownloadAndStoreTilesAsync(double lat, double lon, double sizeMeters, int zoomLevel, CancellationToken) → Task<List<TileMetadata>>`: downloads missing tiles for a region and returns all tile metadata (existing + new)
|
|
- `GetTileAsync(Guid id) → Task<TileMetadata?>`: retrieve a single tile by ID
|
|
- `GetTilesByRegionAsync(double lat, double lon, double sizeMeters, int zoomLevel) → Task<IEnumerable<TileMetadata>>`: query tiles within a geographic region
|
|
- `GetOrDownloadTileAsync(int z, int x, int y, CancellationToken) → Task<TileBytes>`: serve a tile by Z/X/Y, hitting cache, then repository, then downloader (added in AZ-310)
|
|
- `DownloadAndStoreSingleTileAsync(double latitude, double longitude, int zoomLevel, CancellationToken) → Task<TileMetadata>`: download one tile by lat/lon and persist (added in AZ-311)
|
|
- `GetInventoryAsync(TileInventoryRequest request, CancellationToken) → Task<TileInventoryResponse>`: bulk per-cell metadata read for the `POST /api/satellite/tiles/inventory` endpoint (added AZ-505). Computes `location_hash` per request entry via `Uuidv5.LocationHashForTile` (Form A) or uses the caller-supplied hashes (Form B), delegates the read to `ITileRepository.GetTilesByLocationHashesAsync`, applies the AZ-484 / AZ-503-foundation most-recent-across-sources selection per cell, and shapes the result so `response.results.length == request entry count` in input order (see `tile-inventory.md` v1.0.0 Inv-2..Inv-6). XOR validation + entry-cap enforcement happen in the API handler, not here.
|
|
|
|
### IRegionService
|
|
- `RequestRegionAsync(Guid id, double lat, double lon, double sizeMeters, int zoomLevel, bool stitchTiles) → Task<RegionStatusResponse>`: creates a region record and enqueues for async processing
|
|
- `GetRegionStatusAsync(Guid id) → Task<RegionStatusResponse?>`: retrieves current status of a region request
|
|
- `ProcessRegionAsync(Guid id, CancellationToken) → Task`: executes tile downloading, CSV/summary generation, optional stitching
|
|
|
|
### IRouteService
|
|
- `CreateRouteAsync(CreateRouteRequest request) → Task<RouteResponse>`: validates input, calculates intermediate points, persists route + points, optionally creates geofence regions
|
|
- `GetRouteAsync(Guid id) → Task<RouteResponse?>`: retrieves route with all points
|
|
|
|
### ISatelliteDownloader
|
|
- `GetTiles(GeoPoint geoPoint, double radiusM, int zoomLevel, CancellationToken) → Task`: legacy interface for tile downloading (not directly implemented by `GoogleMapsDownloaderV2`)
|
|
|
|
### IRegionRequestQueue
|
|
- `EnqueueAsync(RegionRequest request, CancellationToken) → ValueTask`: add region request to the bounded queue
|
|
- `DequeueAsync(CancellationToken) → ValueTask<RegionRequest?>`: consume next request (blocks until available)
|
|
- `Count` (int): current queue depth
|
|
|
|
## Internal Logic
|
|
Pure interface definitions — no logic.
|
|
|
|
## Dependencies
|
|
- All interfaces reference DTOs from `SatelliteProvider.Common.DTO`
|
|
|
|
## Consumers
|
|
- `Program.cs` — DI registration of implementations
|
|
- `RegionProcessingService` — consumes `IRegionRequestQueue` and `IRegionService`
|
|
- `RouteService` — consumes `IRegionService` (for geofence region creation)
|
|
- `RouteProcessingService` — consumes `IRegionService` via service provider scope
|
|
- API endpoints — consume `ITileService`, `IRegionService`, `IRouteService`
|
|
|
|
## Data Models
|
|
None defined here.
|
|
|
|
## Configuration
|
|
None.
|
|
|
|
## External Integrations
|
|
None.
|
|
|
|
## Security
|
|
None.
|
|
|
|
## Tests
|
|
No dedicated interface tests.
|