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

Batch Report

Batch: 19 Tasks: AZ-370 (C17 — status / point-type enums + AC RT2 update) Date: 2026-05-11 Run: 03-code-quality-refactoring Cycle: 1 Commit: 23ab057

Task Results

Task	Status	Files Modified	Tests	AC Coverage	Issues
AZ-370_refactor_status_pointtype_enums	Done	22 src + 6 doc + 1 task = 29 files	171 unit + 5 smoke pass	4/4 covered	None

Changes

New files

• SatelliteProvider.Common/Enums/RegionStatus.cs — Queued, Processing, Completed, Failed.
• SatelliteProvider.Common/Enums/RoutePointType.cs — Start, End, Action, Intermediate.
• SatelliteProvider.DataAccess/TypeHandlers/EnumStringTypeHandler.cs — generic SqlMapper.TypeHandler<T> (lowercase write, case-insensitive read, defined-value check) plus the idempotent DapperEnumTypeHandlers.RegisterAll() startup registrar.
• SatelliteProvider.Common/DTO/RegionStatusResponse.cs — renamed from RegionStatus.cs to free the RegionStatus name for the new enum (file rename via git, content updated to type Status as RegionStatus).
• SatelliteProvider.Tests/EnumStringTypeHandlerTests.cs — 24 theory cases + 4 fact tests covering Set/Parse, full round-trip per enum value, null/DBNull/empty/undefined rejection, idempotent registration.
• SatelliteProvider.Tests/AcceptanceCriteriaRT2Tests.cs — locates _docs/00_problem/acceptance_criteria.md from the test runtime and asserts RT2 lists all four point types (covers AC-3).

Modified production code

• SatelliteProvider.DataAccess/SatelliteProvider.DataAccess.csproj — added <ProjectReference> to Common (no cycle: Common does not reference DataAccess).
• SatelliteProvider.DataAccess/Models/RegionEntity.cs — Status now typed RegionStatus.
• SatelliteProvider.DataAccess/Models/RoutePointEntity.cs — PointType now typed RoutePointType.
• SatelliteProvider.DataAccess/Repositories/IRegionRepository.cs, RegionRepository.cs — GetByStatusAsync parameter typed RegionStatus (no callers in production today; updated for type safety in case it is wired in later).
• SatelliteProvider.Common/Interfaces/IRegionService.cs — return types now RegionStatusResponse.
• SatelliteProvider.Services.RegionProcessing/RegionService.cs — five string literals replaced with enum members (Queued/Processing/Completed/Failed); two user-visible string formats (idempotent log message and summary file Status: line) kept lowercase via explicit .ToString().ToLowerInvariant() to preserve behavior.
• SatelliteProvider.Services.RouteManagement/RouteProcessingService.cs — three region-status comparisons converted (completed, failed, queued/processing).
• SatelliteProvider.Services.RouteManagement/RoutePointGraphBuilder.cs — four point-type assignments converted.
• SatelliteProvider.Common/DTO/RoutePointDto.cs — PointType now typed RoutePointType.
• SatelliteProvider.Api/Program.cs — calls DapperEnumTypeHandlers.RegisterAll() once after DI builder construction; adds JsonStringEnumConverter(JsonNamingPolicy.CamelCase) to the http JSON options so the API JSON wire keeps emitting lowercase strings ("queued"/"completed"/"start"/...).

Modified tests

• RegionServiceTests.cs — entity initializers and capturedStatuses lists retyped from string to RegionStatus; FluentAssertions expectations switched to enum members.
• RouteServiceTests.cs — RoutePointEntity initializers and PointType comparisons converted to RoutePointType members; mock setup for IRegionService.RequestRegionAsync now returns new RegionStatusResponse { Status = RegionStatus.Queued }.
• RouteResponseMapperTests.cs — DTO/entity initializers and assertions converted.
• RoutePointGraphBuilderTests.cs — assertions converted.

Modified docs

• _docs/00_problem/acceptance_criteria.md (AC-3 source of truth) — RT2 row now reads "start" for first waypoint, "end" for last waypoint, "action" for middle waypoints, "intermediate" for generated points.
• Stale-after-rename references updated in _docs/02_document/00_discovery.md, _docs/02_document/04_verification_log.md, _docs/02_document/components/01_common/description.md, _docs/02_document/modules/common_interfaces.md, _docs/02_document/modules/services_region.md.

DTO rename rationale

The task spec explicitly names the new enum RegionStatus. The pre-refactor DTO at Common/DTO/RegionStatus.cs collided with that name in the same project. Three options were considered:

1. Rename the DTO to RegionStatusResponse — chosen. The integration tests already used this exact name for the same wire shape, and the DTO is genuinely a response object (Id + Status + file paths + timestamps + counters). No JSON wire-format change.
2. Use a different enum name (e.g., RegionLifecycleStatus) — rejected because the task spec and the parent change-list (C17) explicitly call out the enum name.
3. Use namespace-qualified references at conflict sites — rejected because it spreads conflict noise across multiple consumer files.

The rename is mechanically a file move + identifier swap with no behavior change; affected stale doc references were updated in this same batch as adjacent hygiene per coderule.mdc.

AC Test Coverage

AC	Covered by
AC-1 (compare/write sites use enums)	All RegionServiceTests, RouteServiceTests, RoutePointGraphBuilderTests, RouteResponseMapperTests cases now compare against enum members; the production sites are exercised through these. Repo-wide grep confirms no remaining bare-string status/point-type literals in production code (only inside test fixtures that intentionally probe the type handler).
AC-2 (DB round-trip preserves values)	EnumStringTypeHandlerTests.RoundTrip_RegionStatus_PreservesValue_AZ370_AC2 (4 cases) + RoundTrip_RoutePointType_PreservesValue_AZ370_AC2 (4 cases). SetValue_*_WritesLowercaseString_AZ370_AC1 tests pin the on-the-wire format byte-for-byte.
AC-3 (AC RT2 lists all 4 point types)	AcceptanceCriteriaRT2Tests.RT2_LinesAllFourPointTypes_AZ370_AC3 reads the markdown at runtime and asserts all four quoted strings appear on the RT2 row.
AC-4 (tests stay green)	scripts/run-tests.sh --smoke reports 171/171 unit + 5/5 smoke.

Test Run

Suite	Result	Count
Unit (SatelliteProvider.Tests)	All passed	171 (was 141; +30 new tests for the type handler and the AC RT2 doc check)
Smoke integration (Docker)	All passed	5 scenarios (Tile by lat/lon, Region 200m@z18, Simple Route, Route+TilesZip, Migration 012 dedupe + AZ-362 idempotency + Security + Stub/error contracts)

Code Review Verdict: PASS

Inline review covered:

• Architecture: Enums in foundation layer; type handler in DataAccess; DataAccess→Common project ref added (no cycle). DTO rename forced by spec, fully propagated.
• Behavior preservation: DB string format (lowercase, identical to prior literals); JSON wire format (JsonStringEnumConverter with CamelCase policy emits the same lowercase strings for these single-word members — proven by passing integration tests that still parse Status as string); log + summary file format (explicit .ToLowerInvariant()).
• AC coverage: 4/4, all wired to dedicated tests.
• Code quality: Single-responsibility enums/handler/registrar; argument validation in Parse (rejects null/DBNull/empty/unknown); idempotent registrar via Interlocked.Exchange; no narrative comments; A/A/A test pattern.
• Cross-batch consistency: ProcessingConfig/MapConfig (batch 18), the route-management collaborator pattern (batch 17), and 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 counter resets — the next cumulative review fires after batch 21. Phase 4 continues with the remaining 9 tasks in todo/:

• AZ-372 — C18 format/analyzers/coverage (3 SP)
• AZ-373 — C19 clarify maps_version naming (3 SP)
• AZ-374 — C20 typed HttpClient for Google Maps (3 SP)
• AZ-375 — C21 on-existing-tile lookup (2 SP)
• AZ-376 — C22 delete unused FindExistingTile (2 SP)
• AZ-377 — C23 consolidate Earth radius constants (2 SP)
• AZ-378 — C24 repo logger fields (2 SP)
• AZ-379 — C25 repo SELECT column-list (2 SP)
• AZ-380 — C26 delete unused polygon-diagonal helper (2 SP)