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

Files

T

Oleksandr Bezdieniezhnykh bc04ba7f99 [AZ-794] [AZ-795] [AZ-796] Cycle 7 Steps 12-15 sync (test-spec / docs / security / perf)

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>

2026-05-22 11:24:27 +03:00

5.0 KiB

Raw Blame History

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

5.0 KiB Raw Blame History Unescape Escape