mirror of
https://github.com/azaion/satellite-provider.git
synced 2026-06-22 09:31:15 +00:00
[AZ-808] [AZ-809] [AZ-810] [AZ-811] [AZ-812] Cycle 8 docs sync
Phase 13 of autodev existing-code flow — document skill in task
mode. Targeted updates to system-level docs that the per-batch
implementation commits did not already cover. Per-module docs
(api_program.md, common_dtos.md, system-flows.md F1/F2/F4) and
the 4 new contract docs (region-request.md, route-creation.md,
tile-latlon.md, uav-tile-upload.md v1.2.0) were already updated
during Step 10 batch commits and were verified-clean here.
architecture.md
- Bump contracts inventory line to mention uav-tile-upload.md v1.2.0
(was v1.1.0) and add the four cycle-8 contracts (region-request,
route-creation, tile-latlon, error-shape) so the contract index
in architecture.md is no longer stale relative to the implemented
endpoints.
- Add new architectural principle "Strict wire-format validation
at the API edge (AZ-795 epic, completed across cycles 7-8)" to
the Architectural Principles list. Describes the two-layer
enforcement (deserializer + FluentValidation), the three approved
per-endpoint paths (WithValidation<T> for JSON bodies,
UavUploadValidationFilter for multipart, RejectUnknownQueryParams
EndpointFilter + WithValidation<TQuery> for query strings), and
the no-handler-without-validation rule.
ripple_log_cycle8.md
- New cycle-8 ripple log following the cycle-7 template. Documents
every directly-changed source file, the importer scan results,
doc refresh decisions, and the no-ripple component list.
- Records the AZ-795 epic posture: cycle 8 closes the per-endpoint
rollout. Every public-facing JSON, multipart, and query-param
endpoint now goes through one of the three approved paths. The
exempt endpoints (GET region/{id}, GET route/{id}, GET tiles/mgrs
stub, GET tiles/{z}/{x}/{y}) are listed with justification.
State
- Advance autodev to Step 14 (Security Audit), sub_step phase 0
awaiting-choice.
No production code change; no test code change.
Co-authored-by: Cursor <cursoragent@cursor.com>
This commit is contained in:
@@ -24,6 +24,7 @@ The three Layer-3 service components are compile-time siblings: each only refere
|
||||
- Cross-repo deterministic tile identity (AZ-503) — the `TileNamespace` UUID `5b8d0c2e-7f1a-4d3b-9c5e-1f3a8e7d2b6c` and the canonical name format are shared with the sibling workspace `gps-denied-onboard` (`components/c6_tile_cache/_uuid.py:TILE_NAMESPACE`). Both sides MUST produce byte-identical UUIDv5 output so an onboard-cached tile and a server-cached tile for the same `(z, x, y, source, flight_id)` are recognized as the same artifact without a round-trip. Changing the namespace constant on either side is a coordinated cross-repo break. (`inferred-from: Uuidv5.cs, AZ-503 task spec § Constraints`)
|
||||
- Fire-and-forget async processing with status polling (`inferred-from: queue + background service + status endpoint`)
|
||||
- JWT-validated callers only — every HTTP endpoint requires a valid HS256-signed Bearer token, validated locally against a shared `JWT_SECRET` per the suite-level auth contract (`suite/_docs/10_auth.md`). Issuer/audience are intentionally not validated yet; signature + lifetime + ≥32-byte key are. Per-endpoint permission claims (e.g. `permissions: ["GPS"]` on the UAV upload) layer on top of this baseline.
|
||||
- Strict wire-format validation at the API edge (AZ-795 epic, completed across cycles 7-8) — every public-facing endpoint runs every incoming payload through two collaborating layers BEFORE the handler sees it: (a) `JsonSerializerOptions.UnmappedMemberHandling.Disallow` + `[JsonRequired]` on every non-optional DTO axis at the System.Text.Json deserializer; (b) per-endpoint FluentValidation `IValidator<T>` wired via `WithValidation<T>()` (JSON bodies) or `UavUploadValidationFilter` (multipart) or `RejectUnknownQueryParamsEndpointFilter` + `GetTileByLatLonQueryValidator` (query params). Both layers produce identically-shaped RFC 7807 `ValidationProblemDetails` per `error-shape.md` v1.0.0, so callers see one error contract regardless of which layer fired. The principle is: **no payload reaches a handler unless every field is present, every type matches, every range is honored, and no unknown field was silently dropped.** This closes the silent-coercion footgun class (e.g. missing `id` → zero-Guid → untracked region/route; typo `?latitude=` → `lat=0`; misnamed `{"Latitude":...}` → `lat=0`) that pre-cycle-7 produced misleading 200-OK responses. Adding a new public endpoint requires either a `WithValidation<T>()` chain (JSON), a `UavUploadValidationFilter`-style multipart filter, or an `RejectUnknownQueryParamsEndpointFilter` + query validator (query string) — there is no other approved path.
|
||||
|
||||
**Authentication & Authorization** (AZ-487):
|
||||
- Validation library: `Microsoft.AspNetCore.Authentication.JwtBearer` 10.0.7 (matches `Microsoft.AspNetCore.OpenApi` 10.0.7; AZ-496 bumped both packages from 8.0.21 → 8.0.25 in cycle 3 to close the cycle-1 D1 + cycle-2 D3 supply-chain findings, then AZ-500 bumped both 8.0.25 → 10.0.7 in cycle 4 as part of the .NET 8 → .NET 10 migration). The `TokenValidationParameters` shape is unchanged across the JwtBearer 8 → 10 jump — AZ-487/AZ-494 integration tests are the gate and all pass on .NET 10.
|
||||
@@ -39,7 +40,7 @@ The three Layer-3 service components are compile-time siblings: each only refere
|
||||
- *Google Maps* — `TileService.DownloadAndStoreTilesAsync` / `DownloadAndStoreSingleTileAsync` stamp `source='google_maps'`, `flight_id=NULL`, and a deterministic UUIDv5 `id` on every persisted row; tile JPEGs live under `{StorageConfig.TilesDirectory}/{zoom}/...` per the legacy grandfathered layout. `content_sha256` is computed from the on-disk JPEG body.
|
||||
- *UAV* — `POST /api/satellite/upload` (AZ-488; per-flight key extended by AZ-503) accepts a multipart batch of UAV-captured tiles, runs each item through a 5-rule quality gate (`UavTileQualityGate`), and persists accepted items via `ITileRepository.InsertAsync` with `source='uav'`, `flight_id = metadata.flightId` (or NULL for anonymous uploads), and a deterministic UUIDv5 `id`. UAV JPEGs live under `{StorageConfig.TilesDirectory}/uav/{flight_id or 'none'}/{zoom}/{x}/{y}.jpg`, so `rm -rf ./tiles/uav/{flight_id}/` removes one flight's evidence without touching other flights at overlapping cells. Requires the `GPS` permission claim on top of the JWT baseline.
|
||||
|
||||
The N-source storage contract is authoritative in `_docs/02_document/contracts/data-access/tile-storage.md` (v2.0.0 — bumped jointly by AZ-503-foundation and AZ-505 in cycle 6 to capture the identity columns, `tiles_leaflet_path` covering index, and `location_hash`-keyed leaflet read rule). The UAV upload contract is authoritative in `_docs/02_document/contracts/api/uav-tile-upload.md` (v1.1.0; AZ-503 added an optional `flightId` field to per-item metadata — backward-compatible). The bulk tile-inventory contract is authoritative in `_docs/02_document/contracts/api/tile-inventory.md` (v1.0.0; AZ-505). Anything that reads or writes `tiles` MUST follow those contracts rather than re-deriving the rules from prose here.
|
||||
The N-source storage contract is authoritative in `_docs/02_document/contracts/data-access/tile-storage.md` (v2.0.0 — bumped jointly by AZ-503-foundation and AZ-505 in cycle 6 to capture the identity columns, `tiles_leaflet_path` covering index, and `location_hash`-keyed leaflet read rule). The UAV upload contract is authoritative in `_docs/02_document/contracts/api/uav-tile-upload.md` (v1.2.0; AZ-503 added an optional `flightId` field to per-item metadata in v1.1.0, AZ-810 cycle 8 added the strict metadata-validation section in v1.2.0). The bulk tile-inventory contract is authoritative in `_docs/02_document/contracts/api/tile-inventory.md` (v2.0.0; AZ-505 v1.0.0, AZ-794+AZ-796 cycle 7 bumped to v2.0.0 with the OSM `z/x/y` rename + strict validation rules). The four wire-format contracts added in cycle 8 are authoritative for their respective endpoints: `_docs/02_document/contracts/api/region-request.md` v1.0.0 (`POST /api/satellite/request`, AZ-808+AZ-812), `_docs/02_document/contracts/api/route-creation.md` v1.0.0 (`POST /api/satellite/route`, AZ-809), `_docs/02_document/contracts/api/tile-latlon.md` v1.0.0 (`GET /api/satellite/tiles/latlon`, AZ-811), and `_docs/02_document/contracts/api/error-shape.md` v1.0.0 (the cross-endpoint RFC 7807 `ValidationProblemDetails` envelope shared by every validating endpoint, AZ-795 cycle 7). Anything that reads or writes `tiles` MUST follow those contracts rather than re-deriving the rules from prose here.
|
||||
|
||||
**Drift signals**:
|
||||
- `geofence_polygons` mentioned in AGENTS.md as a routes table column but does not exist in schema or entity — documentation drift
|
||||
|
||||
Reference in New Issue
Block a user