[AZ-809] Strict validation for POST /api/satellite/route

Third concrete child of AZ-795 (cycle 8 batch 3). FluentValidation +
[JsonRequired] + UnmappedMemberHandling.Disallow combine to reject every
malformed payload at the API boundary with RFC 7807 ValidationProblemDetails.

Validators (SatelliteProvider.Api/Validators/, all new)
- CreateRouteRequestValidator: id non-empty, name/description length,
  regionSizeMeters/zoomLevel ranges, points count [2, 500], cross-field
  createTilesZip => requestMaps. Chains RoutePointValidator (per-point)
  and GeofencePolygonValidator (per-polygon, guarded by When(Geofences != null)).
  OverridePropertyName("geofences.polygons") on the geofences chain so
  FluentValidation's default leaf-only key policy doesn't drop the parent
  path on deep expressions like req.Geofences!.Polygons.
- RoutePointValidator: lat/lon ranges; OverridePropertyName("lat"/"lon")
  chained AFTER InclusiveBetween (the extension is defined on
  IRuleBuilderOptions<T, TProperty>, so the generic type is only
  inferable after the first concrete rule) so error keys match the
  wire format (`points[i].lat`) rather than the C# property name
  (`points[i].latitude`).
- GeofencePolygonValidator: per-corner range checks via private nested
  GeoCornerValidator; cross-field NW.Lat > SE.Lat and NW.Lon < SE.Lon
  invariants emit at errors["geofences.polygons[i].northWest"].

DTOs (SatelliteProvider.Common/DTO/, [JsonRequired] additions only)
- CreateRouteRequest: id, name, regionSizeMeters, zoomLevel, points,
  requestMaps, createTilesZip
- RoutePoint: Latitude, Longitude
- GeofencePolygon: NorthWest, SouthEast; Geofences: Polygons
- GeoPoint: Lat, Lon

Tests
- Unit: 26 methods total — 16 in CreateRouteRequestValidatorTests, 6 in
  GeofencePolygonValidatorTests, 4 in RoutePointValidatorTests. Each
  RuleFor/RuleForEach chain has at least one positive + one negative case.
- Integration: CreateRouteValidationTests.cs — 16 methods (happy + 15
  failure modes) wired into smoke + full suites. Covers empty body,
  missing/zero id, empty name, out-of-range regionSizeMeters/zoomLevel,
  points count < 2, per-point lat/lon out-of-range, geofence invariants,
  missing requestMaps, cross-field createTilesZip, unknown root field,
  nested type mismatch.
- Manual probe: scripts/probe_route_validation.sh curl-exercises every
  failure mode end-to-end + happy path.

Docs
- New contract _docs/02_document/contracts/api/route-creation.md v1.0.0
  with nested DTO chain, invariants, per-field test cases table, and
  advisories on the legacy service-layer RouteValidator + the
  input/output RoutePoint vs RoutePointDto naming asymmetry.
- system-flows.md F4 sequence diagram extended with the validation-filter
  branch; preconditions + error scenarios reference the new contract.
- modules/api_program.md: CreateRoute handler section added; Api/Validators
  bumped to AZ-808/AZ-809/AZ-811.
- modules/common_dtos.md: DTO descriptions updated with [JsonRequired]
  annotations and constraint summaries.
- tests/blackbox-tests.md BT-06/BT-N03/BT-N04/BT-N05 align with the new
  wire format and named error keys.
- tests/security-tests.md SEC-04 references GlobalExceptionHandler's
  JsonException branch + AZ-353 correlationId.
- _docs/03_implementation/batch_03_cycle8_report.md + reviews/batch_03_cycle8_review.md
  (PASS_WITH_NOTES — F1 Low: OverridePropertyName documented inline,
  F2 + F3 Info: pre-existing advisories for follow-up).

Smoke green (mode=smoke, exit 0). AZ-809 transitioned to In Testing on Jira.
Task file moved to _docs/02_tasks/done/.

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

_docs/02_document/system-flows.md

@@ -177,12 +177,13 @@ sequenceDiagram
 
 ### Description
 
-Client submits a route (ordered waypoints + optional geofence polygons). The service interpolates intermediate points every ~200m and persists the full point set.
+Client submits a route (ordered waypoints + optional geofence polygons). The service interpolates intermediate points every ~200m and persists the full point set. The wire-format contract is `_docs/02_document/contracts/api/route-creation.md` v1.0.0; failure responses follow `error-shape.md` v1.0.0.
 
 ### Preconditions
 
-- At least 2 waypoints provided
-- Valid geofence polygons (if provided)
+- JWT in `Authorization: Bearer <token>` validates against the API's signing key, issuer, and audience (`.RequireAuthorization()`).
+- Request body deserializes successfully: all `[JsonRequired]` axes present (`id`, `name`, `regionSizeMeters`, `zoomLevel`, `points`, `requestMaps`, `createTilesZip`, plus per-point `lat`/`lon`, per-polygon `northWest`/`southEast`, per-corner `lat`/`lon`, `geofences.polygons` when `geofences` present); no unknown root or nested fields (`UnmappedMemberHandling.Disallow`).
+- `CreateRouteRequestValidator` rules pass: non-zero `id`, name length \[1, 200\], description length ≤ 1000, `regionSizeMeters` ∈ \[100, 10000\], `zoomLevel` ∈ \[0, 22\], `points` count ∈ \[2, 500\] with each point's lat/lon in range, per-polygon corner ranges + NW-of-SE invariants, `createTilesZip ⇒ requestMaps`.
 
 ### Sequence Diagram
 
@@ -190,26 +191,33 @@ Client submits a route (ordered waypoints + optional geofence polygons). The ser
 sequenceDiagram
     participant Client
     participant WebApi
+    participant ValidationFilter
     participant RouteService
     participant RouteRepo
     participant GeoUtils
 
-    Client->>WebApi: POST /api/satellite/route {points, geofences, options}
-    WebApi->>RouteService: CreateRoute(request)
-    RouteService->>GeoUtils: Interpolate points between waypoints
-    GeoUtils-->>RouteService: All points (original + intermediate)
-    RouteService->>RouteRepo: InsertRoute(RouteEntity)
-    RouteService->>RouteRepo: InsertPoints(RoutePointEntities)
-    RouteService-->>WebApi: RouteResponse
-    WebApi-->>Client: 200 OK {route_id, total_points, total_distance}
+    Client->>WebApi: POST /api/satellite/route {id, name, points, geofences?, ...}
+    WebApi->>ValidationFilter: .WithValidation<CreateRouteRequest>()
+    alt validation fails
+        ValidationFilter-->>Client: 400 ValidationProblemDetails (errors{path→msg})
+    else validation passes
+        WebApi->>RouteService: CreateRoute(request)
+        RouteService->>GeoUtils: Interpolate points between waypoints
+        GeoUtils-->>RouteService: All points (original + intermediate)
+        RouteService->>RouteRepo: InsertRoute(RouteEntity)
+        RouteService->>RouteRepo: InsertPoints(RoutePointEntities)
+        RouteService-->>WebApi: RouteResponse
+        WebApi-->>Client: 200 OK {id, totalPoints, totalDistanceMeters, ...}
+    end
 ```
 
 ### Error Scenarios
 
 | Error | Where | Detection | Recovery |
 |-------|-------|-----------|----------|
-| Invalid points (< 2) | Validation | Count check | Return 400 |
-| DB insert failure | Persist step | Exception | Return 500 |
+| Missing `[JsonRequired]` axis / unknown field / type mismatch | Deserializer | `JsonException` → `GlobalExceptionHandler` | Return 400 `ValidationProblemDetails` (per `error-shape.md` v1.0.0) |
+| Validator rule violation (range, count, cross-field) | `ValidationEndpointFilter<CreateRouteRequest>` | `CreateRouteRequestValidator` + nested `RoutePointValidator` / `GeofencePolygonValidator` | Return 400 with `errors{path→msg}` map |
+| DB insert failure | Persist step | Exception | Return 500 (sanitised body + correlationId per AZ-353) |
 
 ---