[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
2026-05-10 04:44:08 +03:00
parent 25a644a9bf
commit b0fffa6d42
68 changed files with 4192 additions and 11 deletions
+101
View File
@@ -0,0 +1,101 @@
# Module: Common/DTO
## Purpose
Data transfer objects used across all layers — API requests/responses, inter-service communication, and queue messages.
## Public Interface
### GeoPoint
Geographic coordinate with tolerance-based equality.
- `Lat` (double): latitude, JSON property `"lat"`
- `Lon` (double): longitude, JSON property `"lon"`
- Constructor: `GeoPoint()`, `GeoPoint(double lat, double lon)`
- Equality: two points are equal if both coordinates differ by less than `0.00005` (PRECISION_TOLERANCE)
- Operator overloads: `==`, `!=`
### Direction
Result of a directional calculation between two points.
- `Distance` (double): distance in meters
- `Azimuth` (double): bearing in degrees (0360)
### SatTile
Represents a single map tile with its spatial bounds.
- `X`, `Y` (int): tile coordinates in the slippy map scheme
- `Zoom` (int): zoom level
- `LeftTop`, `BottomRight` (GeoPoint): computed bounding box corners (via `GeoUtils.TileToWorldPos`)
- `Url` (string): download URL
- `FileName → string`: formatted as `{X}.{Y}.{Zoom}.jpg`
### TileMetadata
Metadata about a stored tile (mirrors `TileEntity` but without DB-specific concerns).
- `Id` (Guid), `TileZoom`, `TileX`, `TileY` (int), `Latitude`, `Longitude` (double)
- `TileSizeMeters` (double), `TileSizePixels` (int), `ImageType` (string)
- `MapsVersion` (string?), `Version` (int), `FilePath` (string)
- `CreatedAt`, `UpdatedAt` (DateTime)
### RegionRequest
Queue message for async region processing.
- `Id` (Guid), `Latitude`, `Longitude` (double), `SizeMeters` (double)
- `ZoomLevel` (int), `StitchTiles` (bool)
### RegionStatus
Response DTO for region status queries.
- `Id` (Guid), `Status` (string), `CsvFilePath`, `SummaryFilePath` (string?)
- `TilesDownloaded`, `TilesReused` (int), `CreatedAt`, `UpdatedAt` (DateTime)
### RoutePoint
Input point in a route creation request.
- `Latitude` (double, JSON: `"lat"`), `Longitude` (double, JSON: `"lon"`)
### RoutePointDto
Output point in a route response (includes computed fields).
- `Latitude`, `Longitude` (double), `PointType` (string: "start"/"end"/"action"/"intermediate")
- `SequenceNumber`, `SegmentIndex` (int), `DistanceFromPrevious` (double?)
### CreateRouteRequest
API request body for route creation.
- `Id` (Guid), `Name` (string), `Description` (string?)
- `RegionSizeMeters` (double), `ZoomLevel` (int)
- `Points` (List\<RoutePoint\>), `Geofences` (Geofences?)
- `RequestMaps` (bool), `CreateTilesZip` (bool)
### RouteResponse
API response for route queries.
- All fields from the route entity plus `Points` (List\<RoutePointDto\>)
- `MapsReady` (bool), `TilesZipPath` (string?)
### GeofencePolygon
Axis-aligned bounding box defined by NW and SE corners.
- `NorthWest` (GeoPoint?), `SouthEast` (GeoPoint?)
### Geofences
Container for multiple geofence polygons.
- `Polygons` (List\<GeofencePolygon\>)
## Internal Logic
- `GeoPoint` uses a precision tolerance of `0.00005` degrees (~5.5 meters) for equality comparison.
- `SatTile` eagerly computes its bounding box corners on construction by calling `GeoUtils.TileToWorldPos`.
## Dependencies
- `GeoPoint`, `Direction` — no imports
- `SatTile``SatelliteProvider.Common.Utils.GeoUtils`
- All others — no internal dependencies (or only `System.Text.Json.Serialization`)
## Consumers
- All services, repositories, and API endpoints consume these DTOs
- `RegionRequest` is the message type for `IRegionRequestQueue`
## Data Models
These ARE the data models (DTOs). They map closely to the database entities but are decoupled from the persistence layer.
## Configuration
None consumed directly.
## External Integrations
None.
## Security
None.
## Tests
No dedicated DTO tests.