satellite-provider/_docs/03_implementation/batch_20_report.md

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)