# Batch 14 Report — Refactor 03 Phase 3 (continued)

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

## Scope (1 task / 2 SP)

| ID | C-ID | Title | Points | Component |
|----|------|-------|--------|-----------|
| AZ-369 | C16 | Move inline DTOs out of Program.cs | 2 | Api + Common |

Third task of Phase 3. Pure SRP cleanup — no logic change, no behavior change. Final small extraction before the bigger C11 / C12 decompositions.

## Scope clarification — UploadImageRequest stays in API

The task spec asks for all six DTOs to move to `SatelliteProvider.Common/DTO/`. One of them — `UploadImageRequest` — contains `[Required] public IFormFile? Image`. `IFormFile` lives in `Microsoft.AspNetCore.Http`. Moving it to `Common` would force `<FrameworkReference Include="Microsoft.AspNetCore.App"/>` into the foundation layer, contradicting `module-layout.md`:

```
Component: Common
- Imports from: (none)
```

`UploadImageRequest` is also semantically an HTTP-form-data transport DTO consumed only by the 501-stub upload endpoint — not a cross-component shape. User chose to keep it in the API project under `SatelliteProvider.Api.DTOs` (Choose option A on the contradiction surfaced at batch start). The task spec's "Outcome: Six DTOs live in Common/DTO/" is otherwise satisfied to the maximum extent compatible with the layering invariant.

## Changes

### Production

- **NEW** `SatelliteProvider.Common/DTO/GetSatelliteTilesResponse.cs` — `public record GetSatelliteTilesResponse` with the single `List<SatelliteTile> Tiles` property. Identical shape to the inline declaration.
- **NEW** `SatelliteProvider.Common/DTO/SatelliteTile.cs` — `public record SatelliteTile` with `TileId`, `ImageData`, `Lat`, `Lon`, `ZoomLevel`. Identical shape.
- **NEW** `SatelliteProvider.Common/DTO/SaveResult.cs` — `public record SaveResult` with `Success`, `Exception`. Identical shape.
- **NEW** `SatelliteProvider.Common/DTO/DownloadTileResponse.cs` — `public record DownloadTileResponse` with all 12 fields including `Version: int?` (preserved from AZ-357). Identical shape.
- **NEW** `SatelliteProvider.Common/DTO/RequestRegionRequest.cs` — `public record RequestRegionRequest` with `[Required]` annotations preserved (`System.ComponentModel.DataAnnotations` is a BCL primitive, safe for Common). Identical shape.
- **NEW** `SatelliteProvider.Api/DTOs/UploadImageRequest.cs` — `public record UploadImageRequest` kept in the API project to avoid forcing an ASP.NET framework reference into the foundation layer. Namespace: `SatelliteProvider.Api.DTOs`. Shape preserved.
- **NEW** `SatelliteProvider.Api/Swagger/ParameterDescriptionFilter.cs` — `public class ParameterDescriptionFilter : IOperationFilter`. Namespace: `SatelliteProvider.Api.Swagger`. Same parameter-description dictionary, same `Apply` logic.
- **MODIFIED** `SatelliteProvider.Api/Program.cs`:
  - Removed inline type declarations (107 lines, lines 258-366 in the pre-refactor file).
  - Added `using SatelliteProvider.Api.DTOs;` and `using SatelliteProvider.Api.Swagger;`.
  - Removed `using System.ComponentModel.DataAnnotations;` (no longer used in the host file — only the moved DTOs referenced `[Required]`).
  - `using SatelliteProvider.Common.DTO;` already present (was used by `CreateRouteRequest`, `RegionResponse`, etc.); now also brings in the five moved DTOs.

### Tests

No test changes required. The behaviour under test is identical, and tests already exercise the DTOs by `Type`-binding through the public API (e.g. `c.MapType<UploadImageRequest>(...)`, `[FromBody] RequestRegionRequest`, `[FromForm] UploadImageRequest`). System.Text.Json does not encode namespaces in JSON output, so the on-the-wire shape is byte-for-byte equivalent.

Integration test project (`SatelliteProvider.IntegrationTests/Models.cs`) keeps its own local `DownloadTileResponse` / `RequestRegionRequest` definitions on purpose — that project has no `ProjectReference` to `Common` and replicates the wire shape locally for HTTP deserialization. Left untouched (no cross-reference introduced).

## Verification

- **Unit tests**: 84 / 84 passing (no change in count from batch 13; no test files added or removed).
- **Integration smoke + full suite**: green. Container exits 0. Tests exercised — among many others — the `/api/satellite/tiles/latlon` endpoint (deserializes `DownloadTileResponse`), the `/api/satellite/request` POST endpoint (deserializes `RequestRegionRequest`), the `/api/satellite/upload` 501 stub (operates against `UploadImageRequest` via Swagger `MapType`), and the security-test path that exercises malformed `RequestRegionRequest` JSON (still rejected with HTTP 400 via the AZ-353 global handler).
- **AC-2 verification (OpenAPI shape unchanged)**: implicit from the integration suite — every endpoint that consumes or produces one of the moved DTOs is exercised end-to-end against the deployed Swagger-backed API and continues to deserialize identically.

## Acceptance criteria coverage

| AC | Evidence |
|----|----------|
| **AC-1** `Program.cs` no longer declares any DTOs or Swagger filters | `wc -l SatelliteProvider.Api/Program.cs` = 257 lines (was 366). The file ends at `}` of `async Task<IResult> GetRoute(...)`. `grep -E '^public (record|class) ' SatelliteProvider.Api/Program.cs` returns 0 matches. |
| **AC-2** Public OpenAPI shape unchanged | DTOs moved between namespaces only; field names, types, order, and `[Required]` annotations preserved. System.Text.Json output is namespace-agnostic. Integration tests deserialize via wire shape and all pass. |
| **AC-3** 37 unit + 5 smoke tests green | 84 unit + full integration suite green. |

## Behavior preservation notes

- **JSON wire shape**: namespaces are not encoded in JSON. Renaming `global::DownloadTileResponse` → `SatelliteProvider.Common.DTO.DownloadTileResponse` does not change the wire shape.
- **OpenAPI schema names**: Swashbuckle emits schema names from the type's simple `Name` by default (not the fully-qualified name). Names remain `DownloadTileResponse`, `RequestRegionRequest`, `UploadImageRequest`, `GetSatelliteTilesResponse`, `SatelliteTile`, `SaveResult` — unchanged.
- **`c.MapType<UploadImageRequest>(...)`**: still resolves to the same type (now in `SatelliteProvider.Api.DTOs`). The Swagger schema mapping is unchanged.
- **`c.OperationFilter<ParameterDescriptionFilter>()`**: still resolves to the same filter (now in `SatelliteProvider.Api.Swagger`). The parameter-description dictionary is identical.
- **Records vs classes**: all six moved DTOs were already `record` types; preserved as `record`. The Swagger filter was a `class`; preserved as `class`.

## Architecture / SRP impact

- `Program.cs` shrunk from 366 → 257 lines (~30% reduction). It is now an endpoint wirer with no top-level type declarations — exactly the SRP win the task asked for.
- The foundation layer (`Common`) gained five DTOs and no new external dependencies. `module-layout.md`'s `Common: Imports from: (none)` invariant preserved.
- The API layer (`Api`) gained two small sub-namespaces (`Api.DTOs`, `Api.Swagger`) reflecting the natural decomposition of host-file concerns. Both folders mirror established conventions in adjacent .NET codebases.
- No cyclic dependencies introduced. The dependency graph remains a DAG.

## Per-batch code review (inline — mechanical refactor)

A standalone `/code-review` invocation was skipped for this batch because every change is a literal move (type declaration relocated to a new file with identical shape, references updated). The Step 9 review criteria reduced to:

- **Spec compliance** — all three ACs satisfied (table above).
- **Code quality** — type bodies copied verbatim; whitespace and bracing normalized to the project's convention (4-space indent, `using` directives sorted by namespace prefix). No SOLID violation introduced; the change resolves an SRP violation in `Program.cs`.
- **Security** — no new attack surface. `[Required]` annotations preserved on `RequestRegionRequest` and `UploadImageRequest`; the AZ-353 global handler continues to translate validation failures to HTTP 400 + sanitized ProblemDetails (verified by the existing security integration test that POSTs malformed JSON).
- **Performance** — net zero. Same types, same JSON serialization path.
- **Cross-task consistency** — Phase 3 stays on the "structural cleanup" axis. No drift from AZ-366 (Haversine consolidation) or AZ-368 (TileCsvWriter extraction).
- **Architecture** — `UploadImageRequest` deliberately kept in `Api/DTOs/` to preserve the `Common: Imports from: (none)` invariant. Documented above and in the scope-clarification section.

**Verdict**: PASS. No findings to track. The next cumulative review fires after batch 15 (K=3 trigger; window = batches 13+14+15).

## Up next

- **Batch 15**: candidate is **AZ-365** (C12, decompose `RouteService.CreateRouteAsync`, 5 SP) — the first of the two big Phase 3 decompositions. AZ-365's deps are clear (no blockers). Batch 15 is solo because the task is 5 SP and complex.
- **Cumulative review next** fires after batch 15 (window 13+14+15).
- **Remaining Phase 3**: AZ-377 (C24 Earth constants, depends on AZ-371), AZ-365 (C12, 5 SP), AZ-364 (C11 RouteProcessingService god-class, 5 SP, depends on AZ-366 + AZ-367), AZ-367 (C14 TileGridStitcher, 3 SP, depends on AZ-364) — note the dependency edge AZ-364 ↔ AZ-367 means AZ-367 actually unblocks AZ-364, so the practical ordering is AZ-365 → AZ-367 → AZ-364 (folds AZ-360). AZ-377 floats into Phase 4 once AZ-371 lands.