azaion/satellite-provider
1
0
Fork 0
mirror of https://github.com/azaion/satellite-provider.git synced 2026-06-21 23:21:13 +00:00
Code Issues Packages Projects Releases Wiki Activity

[AZ-350] Refactor 03 Phase 2: roadmap + 27 task specs + safety net

Browse Source 
Adds Phase 0 (baseline metrics, .gitignore tweaks), Phase 1
(research findings, list-of-changes), and Phase 2 (refactoring
roadmap, epic AZ-350, 27 task specs AZ-351..AZ-380, dependency
table updates) for the 03-code-quality-refactoring run.

Phase 3 (Safety Net) re-verified: 40/40 unit + 5/5 smoke
integration pass; documented in test_specs/existing_coverage.md.
Coverage % gating deferred to ticket C19 (AZ-372) which adds
Coverlet + reportgenerator.

Auto-chains to Phase 4 (Execution) via /implement starting at
batch 1 (Phase 1 critical fixes).

Co-authored-by: Cursor <cursoragent@cursor.com>
This commit is contained in:
Oleksandr Bezdieniezhnykh
2026-05-10 23:26:07 +03:00
parent 524809d77d
commit ff030a9521
36 changed files with 2570 additions and 15 deletions
Download Patch File Download Diff File Expand all files Collapse all files
_docs/04_refactoring/03-code-quality-refactoring/baseline_metrics.md
+97
View File
@@ -0,0 +1,97 @@
# Phase 0 — Baseline Metrics (03-code-quality-refactoring)
**Date**: 2026-05-10
**Mode**: Automatic (user-discovered scope)
**Goal (user request)**: Assess current code, identify bad practices, produce steps to eliminate them.
## Scope
- Full codebase, all 8 production/test projects.
- No specific feature change: this is a quality-focused refactor cycle, after the recent coupling refactor (`02-coupling-refactoring`) closed all five Architecture-compliance findings.
- Behavior preservation required: smoke + unit suite must remain green.
## Refactoring Goals (Phase 0a)
These are the exit criteria that Phase 6 (Verification) will check against. They are deliberately framed in terms of *categories of bad practice* rather than fixed file-level changes — the precise list is produced by Phase 1.
1. **Code-smell inventory**: every C# source file in the production projects (`Api`, `Common`, `DataAccess`, `Services.*`) is reviewed for: error handling gaps, scope discipline (long methods / SRP violations), magic numbers, hidden side effects, async-correctness (`async void`, missing `ConfigureAwait` / `CancellationToken`), thread-safety in hosted services, and duplication across the three `Services.*` siblings.
2. **Inventory delivered as `list-of-changes.md`** with severity (Low / Medium / High), risk, and dependencies — same template used for `01-testability-refactoring` and `02-coupling-refactoring`, so the change list is directly consumable by the implement skill.
3. **Roadmap (Phase 2)** ranks the entries by ROI (impact ÷ risk×effort) and groups them into batches that fit the 2–5-point complexity policy from the user's tracker rules.
4. **No regression** in unit (37) or integration smoke (5 scenarios) suites at Phase 6 verification.
5. Open question for Phase 0 BLOCKING gate: does the user want the run to **execute** (Phases 3–7) or **stop after roadmap** (Quick Assessment, Phases 0–2 only)?
## Constraints
- **No public HTTP route changes.** `/api/satellite/tiles/latlon`, `/api/satellite/tiles/{z}/{x}/{y}`, `/api/satellite/request`, `/api/satellite/route` shapes are stable.
- **No database schema changes** (would require migration sequencing and is out of scope).
- **No DI-graph re-ordering** that would change observable startup behavior of the hosted services (`RegionProcessingService`, `RouteProcessingService`).
- **Architecture Vision** (`_docs/02_document/architecture.md` H2) is authoritative. Any proposed change that conflicts with it must be flagged, not silently accepted.
## Current Code Topology
| Project | LOC (.cs, excl. bin/obj) | Files | Notes |
|---------|--------------------------|-------|-------|
| SatelliteProvider.Api | 380 | 1 (`Program.cs`) | Minimal-API endpoints + DI wiring |
| SatelliteProvider.Common | 474 | 25 | DTOs, interfaces, configs, GeoUtils |
| SatelliteProvider.DataAccess | 614 | 11 | Repositories, Entities, Migrations |
| SatelliteProvider.Services.TileDownloader | 620 | 3 | `TileService`, `GoogleMapsDownloaderV2`, DI ext. |
| SatelliteProvider.Services.RegionProcessing | 564 | 4 | `RegionService`, hosted service, queue, DI ext. |
| SatelliteProvider.Services.RouteManagement | 1055 | 3 | `RouteService`, `RouteProcessingService`, DI ext. ← largest unit |
| SatelliteProvider.Tests | 1221 | 6 | xUnit unit tests |
| SatelliteProvider.IntegrationTests | 1434 | 10 | Console runner, integration scenarios |
Total production C# LOC: **3 707** across 47 files (Api + Common + DataAccess + 3 × Services).
Total test C# LOC: **2 655** across 16 files.
## Test Coverage Baseline (carried forward + verified)
- **Unit suite** (`SatelliteProvider.Tests`): 37 `[Fact]`/`[Theory]` annotations (FINAL_report of 02-coupling claimed 40 — small discrepancy; will reconcile in Phase 6 against `dotnet test --list-tests`).
- **Integration smoke** (`scripts/run-tests.sh --smoke`): 5 scenarios, last green run **2026-05-10**, wall-clock **111.86 s** (`_docs/03_implementation/test_run_step7.md`).
- Coverage % not measured (no Coverlet wired up; would add as a Phase 0 sub-task only if the user wants it gating verification).
## Architecture Compliance Baseline (carried forward)
`_docs/02_document/architecture_compliance_baseline.md` — **all 5 findings Resolved** by epic AZ-309. F1, F2 (High) and F3, F4 (Medium) and F5 (Low). No new architecture findings have been opened since.
## Complexity / Static-Analysis Tools
Not present in this repository:
- No Coverlet / dotCover / fine-grained coverage runner.
- No `dotnet format --verify-no-changes` gate.
- No SonarLint / Roslyn-analyzer ruleset beyond defaults.
- No cyclomatic-complexity tool wired up.
These gaps are *themselves* candidate findings for Phase 1 (tooling category).
## Functionality Inventory
| Endpoint / Hosted Service | Owner Project | Status | Smoke Coverage |
|---------------------------|---------------|--------|----------------|
| `GET /api/satellite/tiles/{z}/{x}/{y}` | Api → Services.TileDownloader | live | ✓ (TileTests.RunGetTileByLatLonTest) |
| `GET /api/satellite/tiles/latlon` | Api → Services.TileDownloader | live | ✓ |
| `GET /api/satellite/tiles/mgrs` | Api | stub (returns 501) | not exercised |
| `POST /api/satellite/request` | Api → Services.RegionProcessing | live | ✓ (RegionTests.RunRegionProcessingTest_200m_Zoom18) |
| `GET /api/satellite/region/{id}` | Api → Services.RegionProcessing | live | ✓ |
| `POST /api/satellite/route` | Api → Services.RouteManagement | live | ✓ (BasicRouteTests.RunSimpleRouteTest, ExtendedRouteTests.RunRouteWithTilesZipTest) |
| `GET /api/satellite/route/{id}` | Api → Services.RouteManagement | live | ✓ |
| `POST /api/satellite/upload` | Api | stub (returns 501) | not exercised |
| `RegionProcessingService` (BackgroundService) | Services.RegionProcessing | live | exercised via region scenarios |
| `RouteProcessingService` (BackgroundService) | Services.RouteManagement | live | exercised via route scenarios |
## Self-Verification (Phase 0)
- [x] RUN_DIR created with auto-incremented prefix `03-`.
- [x] Goals captured (5 numbered goals above).
- [x] Constraints captured (no HTTP-shape change, no schema change, no DI reorder, Architecture Vision honored).
- [x] Current topology measured by LOC and file count.
- [x] Test coverage baseline noted; coverage % flagged as not measured.
- [x] Architecture compliance baseline noted (carried from 02-coupling FINAL_report).
- [x] Functionality inventory complete (10 endpoints + 2 hosted services).
- [x] Tool gaps explicitly listed so Phase 1 can decide whether to fold them in.
## Open Question for User (BLOCKING gate)
See the Phase 0 summary presented in chat — two decisions:
1. Confirm goals and constraints above.
2. Choose: full refactor run (Phases 0–7) vs. Quick Assessment (Phases 0–2 only — produces `list-of-changes.md` + `refactoring_roadmap.md` and stops).