mirror of
https://github.com/azaion/satellite-provider.git
synced 2026-06-22 03:31:14 +00:00
[AZ-284] Autodev baseline + testability refactor
Phase A baseline outputs from /autodev (Steps 1-5): - Problem & solution docs (_docs/00_problem, _docs/01_solution) - Codebase documentation (_docs/02_document) incl. architecture, module-layout, glossary, system-flows, baseline compliance scan - Test specs (blackbox, performance, resilience, security, resource, traceability matrix) - Test task decomposition (_docs/02_tasks/todo): AZ-285..AZ-290 - Testability refactor (_docs/04_refactoring/01-testability-refactoring): - TC-01 Move DownloadedTileInfoV2 + new ExistingTileInfo to Common.DTO - TC-02 Replace dead ISatelliteDownloader API with real signatures - TC-03 GoogleMapsDownloaderV2 implements ISatelliteDownloader - TC-04 TileService depends on ISatelliteDownloader (mockable) - TC-05 DI + endpoints use ISatelliteDownloader - Test runner scripts (scripts/run-tests.sh, run-performance-tests.sh) - Autodev state pointer (_docs/_autodev_state.md) Prepares the codebase for AZ-285..AZ-290 unit/integration test work. Co-authored-by: Cursor <cursoragent@cursor.com>
This commit is contained in:
@@ -0,0 +1,90 @@
|
||||
# Common (Foundation)
|
||||
|
||||
## 1. High-Level Overview
|
||||
|
||||
**Purpose**: Shared foundation layer containing configuration POCOs, data transfer objects, service interface contracts, and geographic computation utilities used by all other components.
|
||||
|
||||
**Architectural Pattern**: Shared Kernel / Contracts Library
|
||||
|
||||
**Upstream dependencies**: None (leaf)
|
||||
|
||||
**Downstream consumers**: DataAccess, TileDownloader, RegionProcessing, RouteManagement, WebApi, Tests
|
||||
|
||||
## 2. Internal Interfaces
|
||||
|
||||
This component defines the service contracts that other components implement:
|
||||
|
||||
### Interface: ITileService
|
||||
| Method | Input | Output | Async | Error Types |
|
||||
|--------|-------|--------|-------|-------------|
|
||||
| `DownloadAndStoreTilesAsync` | lat, lon, sizeMeters, zoomLevel, CancellationToken | `List<TileMetadata>` | Yes | Exception |
|
||||
| `GetTileAsync` | Guid id | `TileMetadata?` | Yes | Exception |
|
||||
| `GetTilesByRegionAsync` | lat, lon, sizeMeters, zoomLevel | `IEnumerable<TileMetadata>` | Yes | Exception |
|
||||
|
||||
### Interface: IRegionService
|
||||
| Method | Input | Output | Async | Error Types |
|
||||
|--------|-------|--------|-------|-------------|
|
||||
| `RequestRegionAsync` | id, lat, lon, sizeMeters, zoomLevel, stitchTiles | `RegionStatus` | Yes | Exception |
|
||||
| `GetRegionStatusAsync` | Guid id | `RegionStatus?` | Yes | Exception |
|
||||
| `ProcessRegionAsync` | Guid id, CancellationToken | void | Yes | RateLimitException, HttpRequestException, TimeoutException |
|
||||
|
||||
### Interface: IRouteService
|
||||
| Method | Input | Output | Async | Error Types |
|
||||
|--------|-------|--------|-------|-------------|
|
||||
| `CreateRouteAsync` | `CreateRouteRequest` | `RouteResponse` | Yes | ArgumentException |
|
||||
| `GetRouteAsync` | Guid id | `RouteResponse?` | Yes | Exception |
|
||||
|
||||
### Interface: IRegionRequestQueue
|
||||
| Method | Input | Output | Async | Error Types |
|
||||
|--------|-------|--------|-------|-------------|
|
||||
| `EnqueueAsync` | `RegionRequest`, CancellationToken | void | Yes | OperationCanceledException |
|
||||
| `DequeueAsync` | CancellationToken | `RegionRequest?` | Yes | OperationCanceledException |
|
||||
|
||||
### Static: GeoUtils
|
||||
| Method | Input | Output | Async | Error Types |
|
||||
|--------|-------|--------|-------|-------------|
|
||||
| `WorldToTilePos` | GeoPoint, zoom | (x, y) | No | - |
|
||||
| `TileToWorldPos` | x, y, zoom | GeoPoint | No | - |
|
||||
| `CalculateIntermediatePoints` | start, end, maxSpacing | `List<GeoPoint>` | No | - |
|
||||
| `CalculateDistance` | p1, p2 | double (meters) | No | - |
|
||||
| `GetBoundingBox` | center, radiusM | (minLat, maxLat, minLon, maxLon) | No | - |
|
||||
| `DirectionTo` (ext) | p1, p2 | Direction | No | - |
|
||||
| `GoDirection` (ext) | start, direction | GeoPoint | No | - |
|
||||
|
||||
## 3. External API Specification
|
||||
|
||||
N/A — internal-only component.
|
||||
|
||||
## 4. Data Access Patterns
|
||||
|
||||
N/A — no data access.
|
||||
|
||||
## 5. Implementation Details
|
||||
|
||||
**State Management**: Stateless (pure data types and static utilities)
|
||||
|
||||
**Key Dependencies**: None (no NuGet packages)
|
||||
|
||||
**Algorithmic Complexity**: GeoUtils uses Haversine formula (O(1) per calculation). `CalculateIntermediatePoints` is O(n) where n = ceil(distance / maxSpacing).
|
||||
|
||||
## 6. Extensions and Helpers
|
||||
|
||||
| Helper | Purpose | Used By |
|
||||
|--------|---------|---------|
|
||||
| GeoUtils | Coordinate conversions, distance/bearing math, point interpolation | TileDownloader, RegionProcessing, RouteManagement, WebApi |
|
||||
|
||||
## 7. Caveats & Edge Cases
|
||||
|
||||
- `GeoPoint` equality uses a tolerance of 0.00005° (~5.5m), which may cause false positives for closely-spaced tiles at high zoom levels
|
||||
- `DatabaseConfig` is defined but never wired via DI — connection string is read directly from `IConfiguration`
|
||||
- `ISatelliteDownloader` interface exists but is not implemented by `GoogleMapsDownloaderV2` (legacy artifact)
|
||||
|
||||
## 8. Dependency Graph
|
||||
|
||||
**Must be implemented after**: nothing
|
||||
**Can be implemented in parallel with**: DataAccess
|
||||
**Blocks**: TileDownloader, RegionProcessing, RouteManagement, WebApi
|
||||
|
||||
## 9. Logging Strategy
|
||||
|
||||
N/A — no logging in this component.
|
||||
Reference in New Issue
Block a user