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

Batch 13 Report — Refactor 03 Phase 3 (continued)

Date: 2026-05-10 Epic: AZ-350 (03-code-quality-refactoring) Status: ✅ Complete, pushed

Scope (1 task / 2 SP)

ID	C-ID	Title	Points	Component
AZ-368	C15	Extract shared TileCsvWriter	2	Common + Services.RegionProcessing + Services.RouteManagement

Second task of Phase 3. Pairs with AZ-366 (batch 12 — Haversine consolidation) as the foundational extracts that the bigger C11 / C12 decompositions later in Phase 3 will reuse.

Changes

Production

• NEW SatelliteProvider.Common/Utils/TileCsvWriter.cs
  • public sealed class TileCsvWriter with one instance method WriteAsync(string filePath, IEnumerable<TileCsvRow> rows, CancellationToken ct = default). Owns the CSV format end-to-end: header constant, ordering rule, F6 numeric format, and StreamWriter lifecycle. Stateless — callers can new TileCsvWriter() at use sites without DI bloat.
  • public sealed record TileCsvRow(double Latitude, double Longitude, string FilePath) — minimal contract bridging the existing region (TileMetadata) and route (TileInfo) DTOs without forcing them to share a base type.
  • Instance-based rather than static, per coderule.mdc (file I/O is a side effect; static reserved for pure compute).
• MODIFIED SatelliteProvider.Services.RegionProcessing/RegionService.cs (GenerateCsvFileAsync)
  • Replaced ~10 lines of inline StreamWriter + ordering + format code with a 2-line projection (tiles.Select(...) → TileCsvRow) and a delegated WriteAsync call.
  • Method became private static (no longer references instance state).
• MODIFIED SatelliteProvider.Services.RouteManagement/RouteProcessingService.cs (GenerateRouteCsvAsync)
  • Same pattern: project TileInfo → TileCsvRow, delegate to TileCsvWriter. Existing _logger.LogInformation("Route CSV generated: ... with {Count} tiles", ...) preserved (uses the row count from the projected list, identical to pre-refactor count).

Tests

• NEW SatelliteProvider.Tests/TileCsvWriterTests.cs — 7 unit tests:
  • WriteAsync_WritesHeaderAndRows_AZ368_AC1 — happy path: header line + 2 rows.
  • WriteAsync_OrdersByLatitudeDescThenLongitudeAsc_AZ368 — verifies the OrderByDescending(Latitude).ThenBy(Longitude) rule applies inside the writer (so callers don't need to pre-sort).
  • WriteAsync_EmptyRows_WritesHeaderOnly_AZ368 — defines behavior for empty input.
  • WriteAsync_FormatsNumericValuesWithF6Precision_AZ368_AC2 — F6 trims excess precision (0.1234567890 → 0.123457) and pads short values (1.0 → 1.000000).
  • WriteAsync_ProducesByteForByteOutputMatchingOldInlineWriter_AZ368_AC2 — this is the AC-2 keystone. Writes the same input via both the new TileCsvWriter and the inlined-original logic side by side, then asserts File.ReadAllBytesAsync(new) == File.ReadAllBytesAsync(old). Catches any silent format drift the structural refactor might introduce.
  • WriteAsync_NullPath_ThrowsArgumentNullException_AZ368 and WriteAsync_NullRows_ThrowsArgumentNullException_AZ368 — null-input contract.
  • Fixture uses a Path.Combine(Path.GetTempPath(), $"tilecsv_tests_{Guid.NewGuid():N}") directory cleaned up in Dispose(). Every test runs against a fresh real file (no I/O mocking — matches the coderule.mdc "Make test environment as close as possible to production" line).

Verification

• Unit tests: 84 / 84 passing (was 77 → +7 new TileCsvWriterTests).
• Integration smoke + full suite: green. Container exits 0. The route-tile workflow generates the same route_<id>_ready.csv (117 tiles in the smoke run); the region pipeline generates the same region_<id>_ready.csv. Both consumed by the existing extended-route CSV verification step which would have flagged any header / row / encoding drift.
• AC-2 verification (byte-for-byte): explicit unit test compares two real files written from identical input via both code paths. Bytes equal. No drift.

Acceptance criteria coverage

AC	Evidence
AC-1 Region and route paths both use TileCsvWriter	RegionService.GenerateCsvFileAsync and RouteProcessingService.GenerateRouteCsvAsync both contain a single await new TileCsvWriter().WriteAsync(...) call after a 1-line projection from their respective DTOs to TileCsvRow. Grep for latitude,longitude,file_path returns matches only in TileCsvWriter.Header constant and the new test.
AC-2 Output bytes are byte-for-byte identical	Unit test WriteAsync_ProducesByteForByteOutputMatchingOldInlineWriter_AZ368_AC2 compares full file bytes between new and inlined-original code paths — equal. End-to-end integration suite re-generated route + region CSVs across multiple test scenarios with no consumer test failures.
AC-3 37 unit + 5 smoke tests green	84 unit + 5 smoke + 3 stub-contract + 2 idempotent-POST + 2 migration integration green.

Behavior preservation notes

• Header text: latitude,longitude,file_path — identical to both pre-refactor inline writers. Now lives in TileCsvWriter.Header constant; future change is a one-line edit at one site.
• Ordering rule: OrderByDescending(Latitude).ThenBy(Longitude) — moved inside the writer (was duplicated in both call sites). Callers no longer need to pre-sort.
• Numeric format: F6 (six-digit decimal). Unchanged.
• StreamWriter lifecycle: await using var writer = new StreamWriter(filePath) + WriteLineAsync(ReadOnlyMemory<char>, CancellationToken). The pre-refactor used using var writer + WriteLineAsync(string). The new overloads (which accept the cancellation token) are part of the same StreamWriter API contract — same UTF-8 no-BOM encoding, same \n line terminator on Linux containers, same buffer flushing semantics. Byte-for-byte equivalence verified by the explicit unit test.
• Cancellation: the writer now respects CancellationToken mid-loop (calls cancellationToken.ThrowIfCancellationRequested() before each row). The pre-refactor inline code did not. This is a strict behavior improvement — long region tile dumps can now respond to cancellation. No test asserts on cancellation behavior, but this matches every other async API in the codebase.

Up next

• Batch 14: AZ-369 (C16, move inline DTOs from Program.cs to Common/DTO/, 2 SP) — last small foundational extract before the bigger Phase 3 work (C12 / C11 decompositions). After C16, Program.cs will be a thin endpoint wirer with no DTO definitions.
• Cumulative review next fires after batches 13+14+15 (K=3 trigger).