# Refactor: decompose RouteProcessingService god-class into 6 collaborators

**Task**: AZ-364_refactor_decompose_routeprocessing_service
**Name**: Split RouteProcessingService into orchestrator + 6 collaborators
**Description**: Extract `RouteRegionMatcher`, `RouteCsvWriter`, `RouteSummaryWriter`, `RouteImageRenderer`, `TilesZipBuilder`, `RegionFileCleaner` from `RouteProcessingService`. The hosted service becomes a thin orchestrator. Folds in C08 (replace `IServiceProvider` with `IRegionService`).
**Complexity**: 5 points
**Dependencies**: AZ-366 (C13 — shared Haversine), AZ-367 (C14 — shared stitcher); folds in AZ-360 (C08)
**Component**: Services.RouteManagement
**Tracker**: AZ-364
**Epic**: AZ-350

## Problem

`SatelliteProvider.Services.RouteManagement/RouteProcessingService.cs` (~750 LOC) is a single `BackgroundService` that does queue polling, region matching, CSV parsing, summary writing, image stitching, geofence-rectangle drawing, route-cross drawing, ZIP creation, and per-region cleanup. The file even hosts a public `TileInfo` POCO at the bottom. Six+ responsibilities; the file is hard to navigate, hard to test, and any change touches multiple concerns.

## Outcome

- `RouteProcessingService` becomes a thin orchestrator that polls the queue and dispatches to collaborators.
- Six new collaborator classes, each with a single responsibility, each unit-testable without a queue.
- `TileInfo` lives in its own file under `Services.RouteManagement` (or `Common/DTO`).
- `IRegionService` is injected directly (folds in C08).
- Same `BackgroundService` lifecycle, same DB writes, same output files (CSV, summary, stitched image, ZIP).
- 37 unit + 5 smoke tests stay green; route image output identical for existing scenarios.

## Scope

### Included
- Extract:
  - `RouteRegionMatcher` (pure: route points + completed regions → ordered region list).
  - `RouteCsvWriter` (writes route_<id>_ready.csv from `IEnumerable<TileInfo>`).
  - `RouteSummaryWriter` (writes route_<id>_summary.txt; includes the StringBuilder block).
  - `RouteImageRenderer` (image stitching + cross/border drawing).
  - `TilesZipBuilder` (ZIP archive creation; resolves entry names).
  - `RegionFileCleaner` (deletes per-region CSV/summary/stitched files).
- Move `TileInfo` to its own file.
- Inject `IRegionService` directly (delete `IServiceProvider` field and the two scope blocks).
- Add unit tests for each collaborator in isolation.

### Excluded
- Changing the queue mechanism.
- Changing the `BackgroundService` lifecycle.
- Changing output file formats (CSV header, summary structure, ZIP layout).

## Acceptance Criteria

**AC-1: Single-responsibility collaborators**
Given the post-refactor source
When inspected
Then each new collaborator class has one public entry point and is independently unit-testable.

**AC-2: Same outputs for existing scenarios**
Given the existing route smoke tests (BasicRouteTests, ExtendedRouteTests)
When they run against the post-refactor code
Then the produced CSV, summary, stitched image, and ZIP files are identical (byte-for-byte for CSV/summary; pixel-for-pixel for the image).

**AC-3: No IServiceProvider in RouteProcessingService**
Given the post-refactor source
When grepping `RouteProcessingService.cs` for `IServiceProvider`
Then zero matches.

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

## Constraints

- Same `BackgroundService` registration (no DI lifetime changes for the hosted service).
- Output file paths and contents preserved.
- Architecture Vision (`architecture.md` H2) honored — collaborators stay inside `Services.RouteManagement`.

## Risks & Mitigation

**Risk 1: image output diff after stitcher refactor**
- *Risk*: a subtle pixel diff in the stitched image may break the integration test image comparisons.
- *Mitigation*: drive C14 (shared stitcher) first; this task plugs into the result.

**Risk 2: hidden state shared across the 6 concerns**
- *Risk*: the god class may share state in ways that don't surface until extracted.
- *Mitigation*: extract one collaborator at a time, run tests between each extraction.

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