[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
+91
View File
@@ -0,0 +1,91 @@
# Data Parameters
## Input Data
### API Request: Single Tile Download
| Parameter | Type | Required | Constraints | Description |
|-----------|------|----------|-------------|-------------|
| latitude | double | yes | -90 to 90 | Center latitude |
| longitude | double | yes | -180 to 180 | Center longitude |
| zoomLevel | int | yes | 120 | Google Maps zoom level |
### API Request: Region
| Parameter | Type | Required | Constraints | Description |
|-----------|------|----------|-------------|-------------|
| latitude | double | yes | -90 to 90 | Region center latitude |
| longitude | double | yes | -180 to 180 | Region center longitude |
| sizeMeters | double | yes | > 0 | Square region side length in meters |
| zoomLevel | int | yes | 120 | Tile zoom level |
| stitchTiles | bool | no | default: false | Whether to produce composite image |
### API Request: Route Creation
| Parameter | Type | Required | Constraints | Description |
|-----------|------|----------|-------------|-------------|
| id | UUID | yes | — | Client-generated route ID |
| name | string | yes | max 200 chars | Human-readable route name |
| description | string | no | — | Optional description |
| regionSizeMeters | double | yes | > 0 | Size of region per route point |
| zoomLevel | int | yes | 120 | Tile zoom level |
| points | array | yes | ≥ 2 waypoints | Ordered route waypoints |
| points[].lat | double | yes | -90 to 90 | Waypoint latitude |
| points[].lon | double | yes | -180 to 180 | Waypoint longitude |
| geofences | object | no | — | Optional geofence definitions |
| geofences.polygons[] | array | no | — | Rectangle boundaries |
| geofences.polygons[].northWest | GeoPoint | yes (if polygon) | valid lat/lon, non-zero | NW corner |
| geofences.polygons[].southEast | GeoPoint | yes (if polygon) | valid lat/lon, non-zero | SE corner |
| requestMaps | bool | no | default: false | Whether to download map tiles for route |
| createTilesZip | bool | no | default: false | Whether to produce ZIP archive |
## Output Data
### Tile File
- **Format**: JPEG
- **Path**: `./tiles/{zoom}/{x}/{y}.jpg`
- **Size**: ~50100 KB per tile (typical at zoom 18)
### Region Outputs
| File | Format | Path Pattern | Content |
|------|--------|-------------|---------|
| CSV manifest | CSV | `./ready/region_{id}_ready.csv` | Tile coordinates and file paths |
| Summary | TXT | `./ready/region_{id}_summary.txt` | Processing statistics |
| Stitched image | JPEG | `./ready/region_{id}_stitched.jpg` | Composite tile image |
### Route Outputs
| File | Format | Path Pattern | Content |
|------|--------|-------------|---------|
| Stitched map | JPEG | `./ready/route_{id}_stitched.jpg` | Full route composite with markers |
| Tiles ZIP | ZIP | `./ready/route_{id}_tiles.zip` | All tiles (max 50 MB) |
| CSV | CSV | `./ready/route_{id}_ready.csv` | Tile manifest |
| Summary | TXT | `./ready/route_{id}_summary.txt` | Route processing statistics |
## Configuration Parameters
### MapConfig (provider-specific; e.g., Google Maps — each provider has its own config section)
| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| ApiKey | string | — | Provider authentication token |
| TileSizePixels | int | 256 | Tile image dimension |
| MaxZoomLevel | int | 20 | Maximum allowed zoom |
| DefaultZoomLevel | int | 18 | Default when not specified |
### StorageConfig
| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| TilesDirectory | string | "./tiles" | Root tile storage path |
| ReadyDirectory | string | "./ready" | Output artifacts path |
### ProcessingConfig
| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| MaxConcurrentDownloads | int | 4 | Parallel Google Maps requests |
| MaxConcurrentRegions | int | 20 | Parallel region processing |
| QueueCapacity | int | 1000 | Max pending region requests |