From 1ca8c80d7bc53788e706a7d8b3e3b02e34c09f7b Mon Sep 17 00:00:00 2001 From: Oleksandr Bezdieniezhnykh Date: Mon, 11 May 2026 04:05:45 +0300 Subject: [PATCH] [AZ-373] Add batch 20 report; autodev state batch 20 complete Co-authored-by: Cursor --- _docs/03_implementation/batch_20_report.md | 99 ++++++++++++++++++++++ _docs/_autodev_state.md | 2 +- 2 files changed, 100 insertions(+), 1 deletion(-) create mode 100644 _docs/03_implementation/batch_20_report.md diff --git a/_docs/03_implementation/batch_20_report.md b/_docs/03_implementation/batch_20_report.md new file mode 100644 index 0000000..2cf12f0 --- /dev/null +++ b/_docs/03_implementation/batch_20_report.md @@ -0,0 +1,99 @@ +# Batch Report + +**Batch**: 20 +**Tasks**: AZ-373 (C20 — clarify or drop MapsVersion field; option (a) selected) +**Date**: 2026-05-11 +**Run**: `03-code-quality-refactoring` +**Cycle**: 1 + +## Task Results + +| Task | Status | Files Modified | Tests | AC Coverage | Issues | +|------|--------|----------------|-------|-------------|--------| +| AZ-373_refactor_clarify_mapsversion | Done | 7 src/test + 3 doc + 1 task = 11 files | 174 unit + 5 smoke pass | 3/3 covered | None | + +## Decision Recorded + +Option (a) — **drop `MapsVersion` from new writes**. `tiles.maps_version` column retained (`coderule.mdc` forbids unprompted column drops). Pre-existing rows keep their `"downloaded_YYYY-MM-DD"` labels for forensic lookup; new rows write `NULL`. The field is removed from the API contract (`DownloadTileResponse`) and the internal DTO (`TileMetadata`) so it no longer appears in JSON responses. + +Rationale for picking (a) over (b): the recommended default in the task spec; `MapsVersion` carries no operational signal — the value was a creation-date label, which is already redundant with `CreatedAt`. Removing it eliminates the dual-source confusion called out by C20. + +## Changes + +### Modified production code + +- `SatelliteProvider.Services.TileDownloader/TileService.cs` + - `BuildTileEntity`: replaced `MapsVersion = $"downloaded_{now:yyyy-MM-dd}"` with `MapsVersion = null`. + - `MapToMetadata`: removed `MapsVersion = entity.MapsVersion` projection (the DTO no longer carries that property). +- `SatelliteProvider.Common/DTO/DownloadTileResponse.cs` — `MapsVersion` property removed. +- `SatelliteProvider.Common/DTO/TileMetadata.cs` — `MapsVersion` property removed. +- `SatelliteProvider.Api/Program.cs` — removed the `MapsVersion = tile.MapsVersion` line in the `DownloadTileResponse` constructor inside `GetTileByLatLon`. + +### Unchanged (deliberate) + +- `SatelliteProvider.DataAccess/Models/TileEntity.cs` — `MapsVersion` property retained because the column still exists; Dapper maps both directions. +- `SatelliteProvider.DataAccess/Repositories/TileRepository.cs` — `maps_version as MapsVersion` in all four SELECTs and `@MapsVersion` in INSERT/UPDATE kept; binds to `null` for new rows. +- `SatelliteProvider.DataAccess/Migrations/001_CreateTilesTable.sql` — `maps_version VARCHAR(50)` (nullable) untouched. + +### Modified tests + +- `SatelliteProvider.Tests/TileServiceTests.cs` — 3 new tests: + - `BuildTileEntity_DoesNotPopulateMapsVersion_AZ373_AC1` — captures the persisted `TileEntity` and asserts `MapsVersion == null`. + - `DownloadTileResponse_DoesNotExposeMapsVersion_AZ373_AC2` — reflection check that the property is absent. + - `TileMetadata_DoesNotExposeMapsVersion_AZ373_AC1` — reflection check. +- `SatelliteProvider.IntegrationTests/Models.cs` — `MapsVersion` removed from the local wire-shape record. +- `SatelliteProvider.IntegrationTests/TileTests.cs` — removed the `Console.WriteLine($" Maps Version: …")` line. + +### Modified docs + +- `_docs/02_document/modules/common_dtos.md` — `TileMetadata` bullet now lists `Version (int?), FilePath (string)` (no `MapsVersion`). +- `_docs/02_document/modules/services_tile_service.md` — Internal Logic and `DownloadAndStoreTilesAsync` description refreshed for AZ-357 + AZ-371 + AZ-373 (adjacent hygiene within the same file). +- `_docs/02_document/data_model.md` — `maps_version` column comment now reads "Legacy free-form provider tag; post-AZ-373 new rows write NULL". + +## Wire-shape impact + +- JSON for `/api/satellite/tiles/latlon` no longer contains the `mapsVersion` property. Tolerant JSON consumers are unaffected. Strict consumers were already aware of the upcoming change via AZ-357's release notes; the integration test that previously printed the field has been updated. +- OpenAPI schema regenerates automatically from the DTO (Swashbuckle) — no manual spec edit required. + +## AC Test Coverage + +| AC | Covered by | +|----|------------| +| AC-1 (semantics explicit — option a: no new writes) | `BuildTileEntity_DoesNotPopulateMapsVersion_AZ373_AC1`, `TileMetadata_DoesNotExposeMapsVersion_AZ373_AC1` | +| AC-2 (HTTP shape decision recorded — field removed) | `DownloadTileResponse_DoesNotExposeMapsVersion_AZ373_AC2` | +| AC-3 (tests stay green) | `scripts/run-tests.sh --smoke` reports 174 unit + 5 smoke. | + +## Test Run + +| Suite | Result | Count | +|-------|--------|-------| +| Unit (`SatelliteProvider.Tests`) | All passed | 174 (was 171; +3 new tests for AC-1 / AC-2) | +| Smoke integration (Docker) | All passed | 5 scenarios | + +## Code Review Verdict: PASS + +Inline review covered: + +- **Architecture**: No layer violations. DTO change confined to `Common/DTO`; persistence layer untouched aside from the implicit `null` write; `WebApi` updated as the direct consumer. Module-layout ownership respected. +- **Behavior preservation**: DB column kept and nullable; existing rows untouched; SQL binds `@MapsVersion` to `null` for new rows. Single observable JSON wire change: `mapsVersion` field is gone from `/api/satellite/tiles/latlon` responses (intentional per AC-2). +- **AC coverage**: 3/3, all wired to dedicated tests. +- **Code quality**: SRP preserved; no narrative comments; A/A/A test pattern; no suppressed errors; argument validation unaffected. +- **Cross-batch consistency**: extends the AZ-357 (drop `Version` concept) theme; AZ-370 (enums, batch 19), AZ-371 (config, batch 18), AZ-364/AZ-360 (RouteProcessingService decomposition, batch 17), and AZ-367 (TileGridStitcher, batch 16) are untouched and still healthy. + +**Findings**: None. + +## Auto-Fix Attempts: 0 +## Stuck Agents: None + +## Next Batch + +Auto-chain to next batch per `/implement` Step 14. Cumulative K=3 review fires after batch 21 (covering batches 19–21). Phase 4 continues with the remaining 8 tasks in `todo/`: + +- `AZ-374` — C21 typed HttpClient for Google Maps (2 SP) +- `AZ-375` — C22 O(N) existing-tile lookup (2 SP, needs AZ-371 ✓) +- `AZ-376` — C23 delete unused FindExistingTileAsync (1 SP) +- `AZ-377` — C24 consolidate Earth-geometry constants (2 SP, needs AZ-371 ✓) +- `AZ-378` — C25 repo `_logger` fields (1 SP) +- `AZ-379` — C26 repo SELECT column-list constants (2 SP) +- `AZ-380` — C27 delete `CalculatePolygonDiagonalDistance` (1 SP) +- `AZ-372` — C19 dotnet format + analyzers + Coverlet (3 SP) diff --git a/_docs/_autodev_state.md b/_docs/_autodev_state.md index 243a18f..d49aaae 100644 --- a/_docs/_autodev_state.md +++ b/_docs/_autodev_state.md @@ -8,7 +8,7 @@ status: in_progress sub_step: phase: 4 name: execution - detail: "batch 19 (AZ-370) complete; K=3 review fires after batch 21" + detail: "batch 20 (AZ-373) complete; K=3 cumulative review fires after batch 21" retry_count: 0 cycle: 1 tracker: jira