# Refactor: clarify or drop MapsVersion field

**Task**: AZ-373_refactor_clarify_mapsversion
**Name**: Decide MapsVersion semantics post-C06
**Description**: Either drop `MapsVersion` from new tile rows (option a) or document it as a free-form provider-tag and keep it for forensics (option b). Decide alongside C06.
**Complexity**: 2 points
**Dependencies**: AZ-357 (C06)
**Component**: Services.TileDownloader + DataAccess + Common
**Tracker**: AZ-373
**Epic**: AZ-350

## Problem

`SatelliteProvider.Services.TileDownloader/TileService.cs:154` writes `MapsVersion = $"downloaded_{now:yyyy-MM-dd}"` — the field name says "version" but the value is a creation-date label. The actual cache-key version is the `Version` integer (currently the year). C06 removes `Version` from the cache-key logic; `MapsVersion` is now doubly confusing.

## Outcome

- `MapsVersion` semantics are explicit (either removed from new writes or documented).
- `tiles.maps_version` DB column is preserved (per `coderule.mdc` — no column drops without explicit confirmation).
- 37 unit + 5 smoke tests stay green.

## Scope

### Included
- Decide between (a) drop from new writes and stop emitting it in `DownloadTileResponse`, or (b) keep as a forensic free-form provider-tag with documentation in `TileMetadata.cs` and the OpenAPI spec.
- Implement the chosen option.
- Update `_docs/02_document/components/<owner>.md` to reflect the decision.

### Excluded
- Dropping the `tiles.maps_version` column (deferred per `coderule.mdc`).
- Renaming the column.

## Acceptance Criteria

**AC-1: Semantics are explicit**
Given the post-refactor source and docs
When inspected
Then `MapsVersion` is either no longer written by new code (option a) or documented as a free-form provider-tag (option b).

**AC-2: HTTP shape decision recorded**
Given the chosen option
When `DownloadTileResponse` is inspected
Then either the field is removed (option a) with the OpenAPI spec updated, or the field stays with documentation (option b).

**AC-3: Tests stay green**
Given the post-refactor build
When `scripts/run-tests.sh --smoke` runs
Then all 37 unit + 5 smoke scenarios pass.

## Constraints

- DB column kept either way.
- No rename.

## Risks & Mitigation

**Risk 1: option choice needs implementation discretion**
- *Risk*: this task documents both options; the implementer must pick one.
- *Mitigation*: default to option (a) — drop from writes, keep column; this is the simpler path. If a downstream consumer relies on the field, fall back to option (b).

Full change entry: `_docs/04_refactoring/03-code-quality-refactoring/list-of-changes.md` (C20).
