mirror of
https://github.com/azaion/satellite-provider.git
synced 2026-06-21 19:51: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:
Oleksandr Bezdieniezhnykh
@@ -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.
|
||||
@@ -0,0 +1,107 @@
|
||||
# DataAccess (Persistence)
|
||||
|
||||
## 1. High-Level Overview
|
||||
|
||||
**Purpose**: Database persistence layer providing Dapper-based repositories for tiles, regions, routes, and route points, plus DbUp-driven schema migrations.
|
||||
|
||||
**Architectural Pattern**: Repository pattern with raw SQL (Dapper)
|
||||
|
||||
**Upstream dependencies**: None at project level (uses Microsoft.Extensions abstractions from NuGet)
|
||||
|
||||
**Downstream consumers**: TileDownloader (TileRepository), RegionProcessing (RegionRepository), RouteManagement (RouteRepository, RegionRepository), WebApi (TileRepository for ServeTile)
|
||||
|
||||
## 2. Internal Interfaces
|
||||
|
||||
### Interface: ITileRepository
|
||||
| Method | Input | Output | Async | Error Types |
|
||||
|--------|-------|--------|-------|-------------|
|
||||
| `GetByIdAsync` | Guid | `TileEntity?` | Yes | NpgsqlException |
|
||||
| `GetByTileCoordinatesAsync` | zoom, x, y | `TileEntity?` | Yes | NpgsqlException |
|
||||
| `FindExistingTileAsync` | lat, lon, tileSizeM, zoom, version | `TileEntity?` | Yes | NpgsqlException |
|
||||
| `GetTilesByRegionAsync` | lat, lon, sizeM, zoom | `IEnumerable<TileEntity>` | Yes | NpgsqlException |
|
||||
| `InsertAsync` | `TileEntity` | Guid | Yes | NpgsqlException |
|
||||
| `UpdateAsync` | `TileEntity` | int | Yes | NpgsqlException |
|
||||
| `DeleteAsync` | Guid | int | Yes | NpgsqlException |
|
||||
|
||||
### Interface: IRegionRepository
|
||||
| Method | Input | Output | Async | Error Types |
|
||||
|--------|-------|--------|-------|-------------|
|
||||
| `GetByIdAsync` | Guid | `RegionEntity?` | Yes | NpgsqlException |
|
||||
| `GetByStatusAsync` | string | `IEnumerable<RegionEntity>` | Yes | NpgsqlException |
|
||||
| `InsertAsync` | `RegionEntity` | Guid | Yes | NpgsqlException |
|
||||
| `UpdateAsync` | `RegionEntity` | int | Yes | NpgsqlException |
|
||||
| `DeleteAsync` | Guid | int | Yes | NpgsqlException |
|
||||
|
||||
### Interface: IRouteRepository
|
||||
| Method | Input | Output | Async | Error Types |
|
||||
|--------|-------|--------|-------|-------------|
|
||||
| `GetByIdAsync` | Guid | `RouteEntity?` | Yes | NpgsqlException |
|
||||
| `GetRoutePointsAsync` | Guid routeId | `IEnumerable<RoutePointEntity>` | Yes | NpgsqlException |
|
||||
| `InsertRouteAsync` | `RouteEntity` | Guid | Yes | NpgsqlException |
|
||||
| `InsertRoutePointsAsync` | `IEnumerable<RoutePointEntity>` | void | Yes | NpgsqlException |
|
||||
| `UpdateRouteAsync` | `RouteEntity` | int | Yes | NpgsqlException |
|
||||
| `LinkRouteToRegionAsync` | routeId, regionId, isGeofence, polygonIndex | void | Yes | NpgsqlException |
|
||||
| `GetRegionIdsByRouteAsync` | Guid routeId | `IEnumerable<Guid>` | Yes | NpgsqlException |
|
||||
| `GetGeofenceRegionIdsByRouteAsync` | Guid routeId | `IEnumerable<Guid>` | Yes | NpgsqlException |
|
||||
| `GetGeofenceRegionsByPolygonAsync` | Guid routeId | `Dictionary<int, List<Guid>>` | Yes | NpgsqlException |
|
||||
| `GetRoutesWithPendingMapsAsync` | — | `IEnumerable<RouteEntity>` | Yes | NpgsqlException |
|
||||
|
||||
### Class: DatabaseMigrator
|
||||
| Method | Input | Output | Async | Error Types |
|
||||
|--------|-------|--------|-------|-------------|
|
||||
| `RunMigrations` | — | bool | No | Exception |
|
||||
|
||||
## 4. Data Access Patterns
|
||||
|
||||
### Queries
|
||||
| Query | Frequency | Hot Path | Index Needed |
|
||||
|-------|-----------|----------|--------------|
|
||||
| GetByTileCoordinatesAsync (tile lookup) | Very High | Yes | `(tile_zoom, tile_x, tile_y)` |
|
||||
| GetTilesByRegionAsync (spatial) | High | Yes | `(latitude, longitude, tile_zoom)` |
|
||||
| InsertAsync (tile upsert) | High | Yes | Composite unique on `(lat, lon, zoom, size, version)` |
|
||||
| GetByStatusAsync (region polling) | Medium | No | `(status)` |
|
||||
| GetRoutesWithPendingMapsAsync | Low | No | `(request_maps, maps_ready)` |
|
||||
|
||||
### Storage Estimates
|
||||
| Table | Est. Row Count (1yr) | Row Size | Growth Rate |
|
||||
|-------|---------------------|----------|-------------|
|
||||
| tiles | ~100K–1M (depends on usage) | ~200B | Variable |
|
||||
| regions | ~10K–50K | ~150B | Proportional to tile requests |
|
||||
| routes | ~1K–5K | ~200B | Low |
|
||||
| route_points | ~50K–500K | ~100B | Proportional to routes |
|
||||
| route_regions | ~10K–100K | ~50B | Proportional to routes |
|
||||
|
||||
## 5. Implementation Details
|
||||
|
||||
**State Management**: Stateless — each repository creates a new Npgsql connection per method call. Npgsql handles internal connection pooling.
|
||||
|
||||
**Key Dependencies**:
|
||||
| Library | Version | Purpose |
|
||||
|---------|---------|---------|
|
||||
| Dapper | 2.1.35 | Micro-ORM for SQL queries |
|
||||
| Npgsql | 9.0.2 | PostgreSQL ADO.NET driver |
|
||||
| dbup-postgresql | 6.0.3 | Schema migration runner |
|
||||
|
||||
**Error Handling**: Exceptions propagate to callers. No retry logic at the repository level.
|
||||
|
||||
## 7. Caveats & Edge Cases
|
||||
|
||||
- Repository interfaces are defined in this project (not in Common), creating a dependency from Services to DataAccess
|
||||
- Column mapping uses SQL aliases (`tile_zoom as TileZoom`) rather than Dapper attribute mapping
|
||||
- TileRepository.InsertAsync uses an upsert pattern; concurrent inserts of the same tile won't conflict
|
||||
- No soft-delete; `DeleteAsync` is a hard delete
|
||||
|
||||
## 8. Dependency Graph
|
||||
|
||||
**Must be implemented after**: nothing (parallel with Common)
|
||||
**Can be implemented in parallel with**: Common
|
||||
**Blocks**: TileDownloader, RegionProcessing, RouteManagement, WebApi
|
||||
|
||||
## 9. Logging Strategy
|
||||
|
||||
| Log Level | When | Example |
|
||||
|-----------|------|---------|
|
||||
| INFO | Migration start/complete | `Starting database migrations...` |
|
||||
| ERROR | Migration failure | `Database migration failed` |
|
||||
|
||||
Structured logging via `ILogger<T>`. Logger injected but rarely used in repositories.
|
||||
@@ -0,0 +1,74 @@
|
||||
# TileDownloader
|
||||
|
||||
## 1. High-Level Overview
|
||||
|
||||
**Purpose**: Acquires satellite imagery tiles from Google Maps, stores them on disk, and persists metadata to the database. Handles session tokens, concurrent downloads, retry logic, and tile deduplication.
|
||||
|
||||
**Architectural Pattern**: Service + Gateway (wraps external API with retry/throttling)
|
||||
|
||||
**Upstream dependencies**: Common (DTOs, GeoUtils, configs), DataAccess (TileEntity, ITileRepository)
|
||||
|
||||
**Downstream consumers**: RegionProcessing (via ITileService), WebApi (GoogleMapsDownloaderV2 directly for single-tile endpoints)
|
||||
|
||||
## 2. Internal Interfaces
|
||||
|
||||
### Class: GoogleMapsDownloaderV2
|
||||
| Method | Input | Output | Async | Error Types |
|
||||
|--------|-------|--------|-------|-------------|
|
||||
| `DownloadSingleTileAsync` | lat, lon, zoomLevel, CancellationToken | `DownloadedTileInfoV2` | Yes | ArgumentException, RateLimitException, HttpRequestException |
|
||||
| `GetTilesWithMetadataAsync` | center, radiusM, zoom, existingTiles, CancellationToken | `List<DownloadedTileInfoV2>` | Yes | ArgumentException, RateLimitException, HttpRequestException |
|
||||
|
||||
### Service: TileService (implements ITileService)
|
||||
| Method | Input | Output | Async | Error Types |
|
||||
|--------|-------|--------|-------|-------------|
|
||||
| `DownloadAndStoreTilesAsync` | lat, lon, sizeM, zoom, CancellationToken | `List<TileMetadata>` | Yes | propagated from downloader |
|
||||
| `GetTileAsync` | Guid | `TileMetadata?` | Yes | NpgsqlException |
|
||||
| `GetTilesByRegionAsync` | lat, lon, sizeM, zoom | `IEnumerable<TileMetadata>` | Yes | NpgsqlException |
|
||||
|
||||
## 4. Data Access Patterns
|
||||
|
||||
### Caching Strategy
|
||||
| Data | Cache Type | TTL | Invalidation |
|
||||
|------|-----------|-----|-------------|
|
||||
| Tile bytes | In-memory (IMemoryCache, WebApi layer) | 1h absolute, 30min sliding | None (manual restart) |
|
||||
| Tile metadata | Database | Until year rollover | Version-based (current year) |
|
||||
| Active downloads | ConcurrentDictionary | Duration of download | Removed on completion |
|
||||
|
||||
## 5. Implementation Details
|
||||
|
||||
**Algorithmic Complexity**: Tile grid calculation is O(w×h) where w×h is the number of tiles covering the bounding box.
|
||||
|
||||
**State Management**: `_activeDownloads` (ConcurrentDictionary) prevents duplicate concurrent downloads. `_downloadSemaphore` limits parallelism.
|
||||
|
||||
**Key Dependencies**:
|
||||
| Library | Version | Purpose |
|
||||
|---------|---------|---------|
|
||||
| Newtonsoft.Json | 13.0.4 | Serialize session creation request body |
|
||||
| IHttpClientFactory | built-in | Create HttpClient instances per request |
|
||||
|
||||
**Error Handling**:
|
||||
- Exponential backoff retry for 429 (rate limit) and 5xx errors: 1s → 2s → 4s → 8s → 16s, max 30s, 5 retries
|
||||
- Immediate throw for 401/403 (auth errors) and cancellation
|
||||
- `RateLimitException` thrown after exhausting retries on 429
|
||||
|
||||
## 7. Caveats & Edge Cases
|
||||
|
||||
- `GoogleMapsDownloaderV2` is registered as a concrete singleton (not behind an interface), creating tight coupling in `TileService` and `Program.cs`
|
||||
- User-Agent header spoofs Chrome — could be rejected if Google changes detection
|
||||
- Allowed zoom levels hardcoded to [15,16,17,18,19] — throws for others
|
||||
- Session token rotation threshold (100 tiles) is an educated guess; Google's actual limit is not documented
|
||||
- Static `_activeDownloads` dictionary means deduplication is process-wide, surviving service scope boundaries
|
||||
|
||||
## 8. Dependency Graph
|
||||
|
||||
**Must be implemented after**: Common, DataAccess
|
||||
**Can be implemented in parallel with**: nothing (needs both foundations)
|
||||
**Blocks**: RegionProcessing
|
||||
|
||||
## 9. Logging Strategy
|
||||
|
||||
| Log Level | When | Example |
|
||||
|-----------|------|---------|
|
||||
| ERROR | Download failure, session token failure | `Tile download failed. Tile: (X, Y), Status: {StatusCode}` |
|
||||
| WARN | Rate limiting retry | `Rate limited (429). Waiting {Delay}s before retry` |
|
||||
| INFO | — | (no INFO-level logs in this component) |
|
||||
@@ -0,0 +1,71 @@
|
||||
# RegionProcessing
|
||||
|
||||
## 1. High-Level Overview
|
||||
|
||||
**Purpose**: Manages the lifecycle of geographic region tile requests — from API submission through a bounded queue to background processing that downloads tiles, generates CSV/summary files, and optionally stitches tiles into composite images.
|
||||
|
||||
**Architectural Pattern**: Producer-Consumer with Background Workers
|
||||
|
||||
**Upstream dependencies**: Common (DTOs, interfaces, configs, GeoUtils), DataAccess (RegionRepository), TileDownloader (ITileService)
|
||||
|
||||
**Downstream consumers**: RouteManagement (creates regions for route points and geofences), WebApi (RequestRegion/GetRegionStatus endpoints)
|
||||
|
||||
## 2. Internal Interfaces
|
||||
|
||||
### Service: RegionService (implements IRegionService)
|
||||
See Common component for interface definition. Key implementation details:
|
||||
- `RequestRegionAsync`: creates DB record, enqueues to bounded channel
|
||||
- `ProcessRegionAsync`: 5-minute timeout, comprehensive error handling, generates CSV + summary + optional stitched image
|
||||
|
||||
### BackgroundService: RegionProcessingService
|
||||
- `ExecuteAsync`: spawns N parallel workers (configurable via `MaxConcurrentRegions`) with staggered startup
|
||||
|
||||
### Queue: RegionRequestQueue (implements IRegionRequestQueue)
|
||||
- Bounded `Channel<RegionRequest>` with `BoundedChannelFullMode.Wait`
|
||||
|
||||
## 4. Data Access Patterns
|
||||
|
||||
### Queries
|
||||
| Query | Frequency | Hot Path | Index Needed |
|
||||
|-------|-----------|----------|--------------|
|
||||
| Region GetByIdAsync | Very High (per processing) | Yes | PK |
|
||||
| Region UpdateAsync (status transitions) | High | Yes | PK |
|
||||
| Region InsertAsync | Medium | No | — |
|
||||
|
||||
## 5. Implementation Details
|
||||
|
||||
**State Management**: Region status tracked in database (queued → processing → completed/failed). Queue state is in-memory (Channel<T>).
|
||||
|
||||
**Key Dependencies**:
|
||||
| Library | Version | Purpose |
|
||||
|---------|---------|---------|
|
||||
| SixLabors.ImageSharp | 3.1.11 | Tile stitching into composite JPEG |
|
||||
| System.Threading.Channels | built-in | Bounded async queue |
|
||||
|
||||
**Error Handling**:
|
||||
- 5-minute processing timeout per region
|
||||
- Separate catch blocks for: timeout, external cancellation, rate limiting, HTTP errors, generic errors
|
||||
- All failures produce a summary file with error details and set status to "failed"
|
||||
|
||||
## 7. Caveats & Edge Cases
|
||||
|
||||
- Queue is in-memory: pending requests are lost on process restart (no persistence)
|
||||
- 5-minute timeout is hardcoded, not configurable
|
||||
- Stitching crosshair is drawn with a fixed 10-pixel arm length (±5 pixels)
|
||||
- Region status "queued" in code vs "pending" mentioned in some API documentation
|
||||
- `RegionProcessingService` workers have random startup delay (100–500ms) to avoid thundering herd on queue
|
||||
|
||||
## 8. Dependency Graph
|
||||
|
||||
**Must be implemented after**: Common, DataAccess, TileDownloader
|
||||
**Can be implemented in parallel with**: nothing at this layer
|
||||
**Blocks**: RouteManagement (uses IRegionService to create regions)
|
||||
|
||||
## 9. Logging Strategy
|
||||
|
||||
| Log Level | When | Example |
|
||||
|-----------|------|---------|
|
||||
| ERROR | Processing failure | `Failed to process region {RegionId}` |
|
||||
| ERROR | Rate limit exceeded | `Rate limit exceeded for region {RegionId}` |
|
||||
| WARN | Region not found, missing tile file | `Region {RegionId} not found in database` |
|
||||
| INFO | Service start/stop, queue creation | `Region Processing Service started with {N} workers` |
|
||||
@@ -0,0 +1,75 @@
|
||||
# RouteManagement
|
||||
|
||||
## 1. High-Level Overview
|
||||
|
||||
**Purpose**: Creates routes from user-defined waypoints, calculates intermediate points along the path, manages geofence regions, and generates consolidated route maps (stitched images, CSVs, summaries, ZIP archives) from completed region tile data.
|
||||
|
||||
**Architectural Pattern**: Service + Background Poller
|
||||
|
||||
**Upstream dependencies**: Common (DTOs, GeoUtils, configs), DataAccess (RouteRepository, RegionRepository), RegionProcessing (IRegionService for region creation)
|
||||
|
||||
**Downstream consumers**: WebApi (CreateRoute/GetRoute endpoints)
|
||||
|
||||
## 2. Internal Interfaces
|
||||
|
||||
### Service: RouteService (implements IRouteService)
|
||||
See Common component for interface definition. Key implementation details:
|
||||
- `CreateRouteAsync`: validates, interpolates points every ≤200m, persists, creates geofence grid regions
|
||||
- `GetRouteAsync`: reads route + points from DB
|
||||
|
||||
### BackgroundService: RouteProcessingService
|
||||
- `ExecuteAsync`: polls every 5 seconds for routes with `request_maps=true AND maps_ready=false`
|
||||
- `ProcessRouteSequentiallyAsync`: checks region completion, retries failed regions, generates maps when ready
|
||||
|
||||
## 4. Data Access Patterns
|
||||
|
||||
### Queries
|
||||
| Query | Frequency | Hot Path | Index Needed |
|
||||
|-------|-----------|----------|--------------|
|
||||
| GetRoutesWithPendingMapsAsync (polling) | Every 5s | No | `(request_maps, maps_ready)` |
|
||||
| GetRoutePointsAsync | Per route processing | Yes | `(route_id, sequence_number)` |
|
||||
| GetRegionIdsByRouteAsync | Per route processing | Yes | `(route_id)` |
|
||||
| InsertRoutePointsAsync (bulk) | Per route creation | No | — |
|
||||
|
||||
## 5. Implementation Details
|
||||
|
||||
**Algorithmic Complexity**: Point interpolation is O(n×m) where n = input points and m = max intermediate points per segment. Geofence grid creation is O(latSteps × lonSteps). Route-region matching uses O(points × regions) nearest-neighbor.
|
||||
|
||||
**State Management**: Route state tracked in database (`request_maps`, `maps_ready` flags). Processing is polling-based (not queue-based like regions).
|
||||
|
||||
**Key Dependencies**:
|
||||
| Library | Version | Purpose |
|
||||
|---------|---------|---------|
|
||||
| SixLabors.ImageSharp | 3.1.11 | Route map stitching with geofence borders and route markers |
|
||||
| System.IO.Compression | built-in | ZIP archive creation for tiles |
|
||||
|
||||
**Error Handling**:
|
||||
- Route creation validates: min 2 points, size range, name required, geofence coordinate validity
|
||||
- RouteProcessingService catches exceptions per-route and continues to next
|
||||
- Failed regions are retried by creating new region requests
|
||||
- Tile coordinate extraction from filenames has a fallback returning (-1,-1) for unparseable names
|
||||
|
||||
## 7. Caveats & Edge Cases
|
||||
|
||||
- 200m max point spacing is hardcoded constant (`MAX_POINT_SPACING_METERS`)
|
||||
- Polling interval (5s) is hardcoded
|
||||
- `RouteProcessingService` resolves `IRegionService` via `IServiceProvider.CreateScope()` to avoid circular DI
|
||||
- Route map stitching extracts tile coordinates from filenames (`tile_{z}_{x}_{y}_{ts}.jpg`); format change would break stitching
|
||||
- ZIP creation runs on `Task.Run` (ThreadPool) — could consume a thread for large archives
|
||||
- `MatchRegionsToRoutePoints` uses O(n²) nearest-neighbor matching; could be slow for routes with many points
|
||||
- Region file cleanup deletes individual region CSVs/summaries after consolidation into route-level files
|
||||
- `catch` in `ExtractTileCoordinatesFromFilename` silently swallows all exceptions
|
||||
|
||||
## 8. Dependency Graph
|
||||
|
||||
**Must be implemented after**: Common, DataAccess, RegionProcessing
|
||||
**Can be implemented in parallel with**: nothing
|
||||
**Blocks**: nothing (top of the dependency chain alongside WebApi)
|
||||
|
||||
## 9. Logging Strategy
|
||||
|
||||
| Log Level | When | Example |
|
||||
|-----------|------|---------|
|
||||
| ERROR | Route processing failure | `Error processing route {RouteId}` |
|
||||
| WARN | Missing tile files, route not found, parse failures | `Tile file not found: {FilePath}` |
|
||||
| INFO | Processing complete, CSV/summary/zip generated | `Route {RouteId} maps processing completed` |
|
||||
Reference in New Issue
Block a user