mirror of
https://github.com/azaion/satellite-provider.git
synced 2026-06-21 11:31:14 +00:00
Oleksandr Bezdieniezhnykh
bc04ba7f99
Step 12 (Test-Spec Sync): adds BT-27 for the AZ-796 9-rule validation surface and 12 cycle-7 AC rows + Coverage Summary update to traceability-matrix.md. Step 13 (Update Docs): module-layout + module docs for the new SatelliteProvider.Api/Validators namespace + GlobalExceptionHandler + updated TileInventory DTO; tests_unit + tests_integration document the new InventoryRequestValidatorTests (16 unit tests covering all 9 rules) + TileInventoryValidationTests (16 integration tests) + ProblemDetailsAssertions support; glossary entries for Validation Problem Details / FluentValidation / Unmapped Member Handling; system-flows F8 (Tile Inventory Bulk Lookup) expanded with deserializer + validator gates and a 13-row Validation Surface table; data_parameters § Tile Inventory documents the v2 input schema + constraints; ripple_log_cycle7 captures the doc-side ripple decisions. Step 14 (Security Audit): 5-phase audit ran; verdict PASS_WITH_WARNINGS (3 Low findings — D-AZ795-1 FluentValidation 12.0.0 -> 12.1.1 recommended bump, F-AZ795-1 JsonException.Message leak in 400 detail, F-AZ795-2 BadHttpRequestException.Message leak). No Critical / High; auth runs before validation (confirmed in Program.cs); two NuGet additions (FluentValidation 12.0.0 + .DependencyInjectionExtensions 12.0.0) both CVE-clean. Per-phase reports plus consolidated security_report_cycle7.md. Step 15 (Performance Test): docker compose stack used for perf run, scripts/run-performance-tests.sh exited 0 with 8/8 scenarios PASS (second consecutive clean exit-0); added PT-09 cycle-7 smoke probe (v2 z/x/y schema, 2500-tile all-miss batch) measuring min=27ms median=44ms p95=73ms max=86ms (13.7x under AZ-505 AC-4 1000ms budget). PT-07/08 improvements traced to the cycle-6 TLS handshake-overhead identification, not application-side change. Co-authored-by: Cursor <cursoragent@cursor.com>
104 lines
5.0 KiB
Markdown
104 lines
5.0 KiB
Markdown
# 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 | 1–20 | Google Maps zoom level |
|
||
|
||
### API Request: Tile Inventory — `POST /api/satellite/tiles/inventory` (AZ-505; renamed AZ-794, strict-validated AZ-796 — cycle 7)
|
||
|
||
Exactly one of `tiles` OR `locationHashes` must be populated and non-empty. Strict input validation enforced by `InventoryRequestValidator` + `System.Text.Json` (`UnmappedMemberHandling.Disallow`); failures return HTTP 400 + `ValidationProblemDetails` per `_docs/02_document/contracts/api/error-shape.md` v1.0.0.
|
||
|
||
| Parameter | Type | Required | Constraints | Description |
|
||
|-----------|------|----------|-------------|-------------|
|
||
| tiles | array | XOR (vs `locationHashes`) | 1 ≤ count ≤ 5000 | Form A: coords-by-value batch |
|
||
| tiles[].z | int | yes (`[JsonRequired]`) | 0–22 (slippy zoom range) | Slippy zoom level (renamed from `tileZoom` by AZ-794) |
|
||
| tiles[].x | int | yes (`[JsonRequired]`) | 0 ≤ x < 2^z | Slippy x at that zoom (renamed from `tileX` by AZ-794) |
|
||
| tiles[].y | int | yes (`[JsonRequired]`) | 0 ≤ y < 2^z | Slippy y at that zoom (renamed from `tileY` by AZ-794) |
|
||
| locationHashes | array | XOR (vs `tiles`) | 1 ≤ count ≤ 5000 | Form B: hashes-by-reference batch (UUIDv5 of `"{z}/{x}/{y}"`) |
|
||
|
||
### 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 | 1–20 | 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 | 1–20 | 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**: ~50–100 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 |
|