mirror of https://github.com/azaion/satellite-provider.git synced 2026-06-21 20:51:14 +00:00

Files

T

Oleksandr Bezdieniezhnykh 23ab05766d [AZ-370] Refactor C17: status / point-type enums + AC RT2 update

Replaces bare strings with two enums in Common/Enums/:
  RegionStatus { Queued, Processing, Completed, Failed }
  RoutePointType { Start, End, Action, Intermediate }

Adds a Dapper EnumStringTypeHandler<T> (DataAccess/TypeHandlers/)
that round-trips enums to/from lowercase strings, registered once
at startup via DapperEnumTypeHandlers.RegisterAll(). DataAccess now
references Common (project ref) so entities can carry the enum types.

Sites converted: RegionService (5), RouteProcessingService (3),
RoutePointGraphBuilder (4), entity Status/PointType columns. Log
message and summary file format preserved via .ToLowerInvariant().

API JSON contract preserved by adding JsonStringEnumConverter with
JsonNamingPolicy.CamelCase to the http JSON options — single-word
enum members serialize to the same lowercase strings as before.

DTO renamed: Common.DTO.RegionStatus -> RegionStatusResponse to
free the RegionStatus name for the new enum (forced by the task's
explicit enum name); the renamed DTO has no public-API impact at
the JSON wire level. Stale doc references updated.

AC RT2 in _docs/00_problem/acceptance_criteria.md now lists all 4
point types (start/end/action/intermediate).

Tests: 171 / 171 unit + 5 / 5 smoke green (was 141 + 5; +30 new tests
covering type handler round-trip, set/parse, unknown-value rejection,
idempotent registration, and the AC RT2 doc check).

Co-authored-by: Cursor <cursoragent@cursor.com>

2026-05-11 03:55:22 +03:00

3.8 KiB

Raw Blame History

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	`RegionStatusResponse`	Yes	Exception
`GetRegionStatusAsync`	Guid id	`RegionStatusResponse?`	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.

3.8 KiB Raw Blame History