azaion/satellite-provider
1
0
Fork 0
mirror of https://github.com/azaion/satellite-provider.git synced 2026-06-21 17:31:15 +00:00
Code Issues Packages Projects Releases Wiki Activity
Files
c74a2339aac449ec7ca86b4f18166ef66f0f981e
satellite-provider/_docs/02_document/ripple_log_cycle5.md
T
Oleksandr Bezdieniezhnykh 61612044fb [AZ-503] [AZ-504] Cycle 5 Steps 11-15 sync 
Wrap up cycle 5 verification + documentation:
- Steps 10/11 wrap-up reports (implementation_completeness +
  implementation_report) for the AZ-503-foundation + AZ-504 batch.
- Step 12 test-spec sync: AZ-503-foundation/AZ-504 ACs appended;
  AZ-505 deferred ACs recorded.
- Step 13 update-docs: architecture, data-model, glossary, module-
  layout, uav-tile-upload contract (v1.1.0), DataAccess + Services
  + Tests module docs synced; new common_uuidv5.md module doc.
- Step 14 security audit: PASS_WITH_WARNINGS; 0 new Critical/High;
  2 new Low informational (F1 flightId provenance, F2 pgcrypto
  deploy gap).
- Step 15 performance test: PASS_WITH_INFRA_WARNINGS; PT-08
  passed twice (AZ-504 fix verified); PT-01/02 failed due to
  recurring local Docker/colima DNS cold-start (not an app
  regression). Cycle-3 perf-harness leftover stays OPEN with
  replay #5 documented.
- Autodev state moved to Step 16 (Deploy).

Co-authored-by: Cursor <cursoragent@cursor.com>
2026-05-12 18:01:27 +03:00

64 lines
7.2 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# Cycle 5 — Documentation Ripple Log
**Cycle**: 5 (AZ-504 perf-script pipefail fix + AZ-503-foundation UUIDv5 tile identity)
**Generated by**: `/document` skill (task mode) during autodev Step 13
**Resolution method**: `Grep --type cs` against every new or changed symbol introduced by the two tasks. C# `using`-based import analysis on `Uuidv5`, `TileEntity` (new properties), `UavTileMetadata.FlightId`, `TileRepository.InsertAsync` (changed UPSERT key). No static-analyzer (NDepend, etc.) was used — the surface is small and the literal usage scan is exhaustive.
## Directly-changed source files (cycle 5)
- `scripts/run-performance-tests.sh` (AZ-504, lines 416–417) — wrapped `grep -o` counters in `{ … || true; }` to survive zero-match cases under `set -o pipefail`. Pure shell; no C# importers.
- `SatelliteProvider.Common/Utils/Uuidv5.cs` (AZ-503, **new**) — pure-C# UUIDv5 generator + `TileNamespace` constant.
- `SatelliteProvider.Common/DTO/UavTileMetadata.cs` (AZ-503, modified) — added optional `Guid? FlightId` property.
- `SatelliteProvider.DataAccess/Migrations/014_AddTileIdentityColumns.sql` (AZ-503, **new**) — adds `flight_id`, `location_hash`, `content_sha256`, `legacy_id`; backfills `location_hash`; supersedes the AZ-484 unique index with `idx_tiles_unique_identity`.
- `SatelliteProvider.DataAccess/Models/TileEntity.cs` (AZ-503, modified) — 4 new properties (`FlightId`, `LocationHash`, `ContentSha256`, `LegacyId`).
- `SatelliteProvider.DataAccess/Repositories/TileRepository.cs` (AZ-503, modified) — `InsertAsync` UPSERT now uses the integer-only + flight-aware conflict key; `id` not overwritten on conflict; `UpdateAsync` writes all four new columns.
- `SatelliteProvider.Services.TileDownloader/TileService.cs` (AZ-503, modified) — `BuildTileEntity` computes deterministic `Id`, `LocationHash`, `ContentSha256`; `FlightId` always null for Google Maps.
- `SatelliteProvider.Services.TileDownloader/UavTileUploadHandler.cs` (AZ-503, modified) — `PersistAsync` reads `metadata.FlightId`, computes deterministic identity fields, writes file to `./tiles/uav/{flight_id or 'none'}/{z}/{x}/{y}.jpg`.
- `SatelliteProvider.IntegrationTests/SatelliteProvider.IntegrationTests.csproj` (AZ-503, modified) — added `ProjectReference` to `SatelliteProvider.Common` so seed SQL can call `Uuidv5.Create`.
- `SatelliteProvider.IntegrationTests/UavUploadTests.cs` (AZ-503, modified seeder + 2 new tests).
- `SatelliteProvider.IntegrationTests/MigrationTests.cs` (AZ-503, 3 new assertions; renamed AZ-484 supersession test).
- `SatelliteProvider.Tests/Uuidv5Tests.cs` (AZ-503, **new** — 10 Python-parity reference vectors).
- `SatelliteProvider.Tests/UavTileFilePathTests.cs` (AZ-503, **new** — per-flight on-disk path).
- `SatelliteProvider.Tests/UavTileUploadHandlerTests.cs` (AZ-503, 2 new tests added; existing tests unchanged).
## Importer scan results
| Symbol | Importer count | Importer files | Component touched |
|--------|----------------|----------------|-------------------|
| `SatelliteProvider.Common.Utils.Uuidv5` / `Uuidv5.Create` / `Uuidv5.TileNamespace` | 5 | `TileService.cs`, `UavTileUploadHandler.cs`, `Uuidv5Tests.cs`, `MigrationTests.cs`, `UavUploadTests.cs` | TileDownloader (production), Tests (unit + integration) |
| `UavTileMetadata.FlightId` (new field) | 2 | `UavTileUploadHandler.cs` (read), `UavUploadTests.cs` (serializer payload) | TileDownloader, Tests (integration) |
| `TileEntity.FlightId` / `LocationHash` / `ContentSha256` / `LegacyId` (new columns) | 3 | `TileRepository.cs`, `TileService.cs`, `UavTileUploadHandler.cs` | DataAccess, TileDownloader |
| `TileRepository.InsertAsync` (changed UPSERT conflict key) | 4 | `TileService.cs`, `UavTileUploadHandler.cs`, `RegionService.cs`, `TileServiceTests.cs` (via mock) | TileDownloader, RegionProcessing, Tests (unit) |
| `pgcrypto` extension (new DB dependency from migration 014) | 1 | `014_AddTileIdentityColumns.sql` (in-migration temp PL/pgSQL only) | DataAccess (migration-only; runtime code does not depend on pgcrypto) |
## Doc refresh decisions
All importers land inside components that already received targeted updates during Step 10 (Implement) and this Step 13:
- **Common** — created `_docs/02_document/modules/common_uuidv5.md` (new utility module doc). Updated `_docs/02_document/modules/common_dtos.md` `UavTileMetadata` section to document `FlightId` + the `null`-vs-flight semantics.
- **DataAccess** — updated `_docs/02_document/modules/dataaccess_models.md` (4 new `TileEntity` properties) and `_docs/02_document/modules/dataaccess_tile_repository.md` (new UPSERT semantics; `id`-not-overwritten invariant). Updated `_docs/02_document/components/02_data_access/description.md` (data-access patterns table, caveats — replaced AZ-484 5-col index entry with AZ-503 6-col integer-only index; documented deterministic identity).
- **TileDownloader** — updated `_docs/02_document/modules/services_tile_service.md` (`BuildTileEntity` deterministic identity; SHA-256 dependency; new module dependencies on `Uuidv5` and `SHA256`).
- **TileDownloader / `UavTileUploadHandler`** — no dedicated module doc exists for this handler; its surface is already covered by `api_program.md` and the `uav-tile-upload.md` contract. Both updated below.
System-level docs also updated this pass:
- `architecture.md` — extended the append-by-source bullet to append-by-source-and-flight (AZ-503), added a cross-repo deterministic-id principle, refreshed ADR-004 (file-storage layout) and the multi-source-producers section to mention `flightId` and the deterministic `id`.
- `data_model.md` — added the 4 new `tiles` columns, the new index `idx_tiles_unique_identity`, the new index `idx_tiles_location_hash`, the new UPSERT contract semantics, and migration 014 in the migration history.
- `contracts/api/uav-tile-upload.md` — minor version bump v1.0.0 → v1.1.0: added optional `flightId` field, documented per-flight on-disk path, documented deterministic `tileId`. Backward-compatible by design.
- `tests/blackbox-tests.md` and `tests/traceability-matrix.md` — updated during Step 12 (Test-Spec Sync) with BT-19 … BT-22 + per-AC trace rows.
## No-ripple components
These components were NOT touched by cycle-5 changes and require no doc update:
- **RegionProcessing** — `RegionService` consumes `ITileRepository.InsertAsync`/`GetTilesByRegionAsync` unchanged. Region read path uses the AZ-484 selection rule which AZ-503 preserved.
- **RouteManagement** — no imports against cycle-5 symbols; route processing reads tiles only via the unchanged region read path.
- **WebApi (`Program.cs`)** — endpoint contract surface unchanged on the wire (the optional `flightId` field is transparent at the routing level; deserialization is owned by `UavTileBatchMetadataPayload` / `UavTileMetadata` in Common). No `api_program.md` edits needed for AZ-503.
## Parse-failure / heuristic notes
None — every symbol resolved via direct `Grep`. No fallback heuristic was needed.
## AZ-504 ripple
`scripts/run-performance-tests.sh` is a shell harness with no code-side importers. Its docs are owned by the test-spec sync layer (`tests/traceability-matrix.md` AC-1..AC-4 rows, updated during Step 12) and the `_docs/02_tasks/done/AZ-504_*.md` task spec. No module-doc ripple.
Reference in New Issue View Git Blame Copy Permalink