D:\QGis\MyPlugins\roll\Refactoring_roadmap.txt

**Refactoring Roadmap**

Updated for the current codebase on 2026-06-06.

This version intentionally removes long historical chronology and keeps only current priorities, execution order, and concrete exit criteria.

**Current Snapshot**

Codebase reality (high level):
1. Core persistence/state/service boundaries are already in place and should be preserved.
2. The largest remaining structural hotspots are still UI-bound seams, especially layout-to-3D bridging and parameter/property complexity.
3. CFP behavior has changed recently and is now part of the active baseline:
- CFP frequency list is not editable in Settings.
- Defaults come from config/runtime path.
- Property-pane frequency list is normalized, sorted ascending, and displayed space-separated.
- XML persists frequencies as semicolon-separated (for example: 10;20;30;40).
- Incoherent plane mode now consumes actual frequency values.
- Coherent and incoherent plane maps are normalized for plotting.
- CFP plane completion logs include normFactor for both coherent and incoherent runs.
- A persisted CFP Settings switch controls whether source/receiver 3x3 diagnostics run.
- 3x3 diagnostics now run for Templates, Geometry Tables, and SPS plane paths through the same switch.
- 3x3 diagnostics summary wording is mathematically explicit and renderer-safe.
- Template/Geometry 3x3 parity is expected when support is identical; differences are expected when geometry support is edited or clipped.

**What To Keep Stable**

Do not reopen these unless required by a specific bug:
1. ProjectService, ProjectLoadApplier, ImportService, FilterService.
2. Session/runtime ownership (AppSettings, RuntimeState, SessionState, DocumentContextService).
3. Worker orchestration split (WorkerOperationController plus result appliers).
4. Existing geometry stable/experimental routing strategy.

**Top Refactoring Priorities**

Priority 1: Layout 2D-to-3D bridge extraction
1. Extract the payload/styling/visibility translation seam between layout 2D and 3D Subset into a dedicated bridge module.
2. Keep layout_3D.py renderer-focused and keep the first bridge API narrow.
3. Add direct bridge tests for payload shape and mapping inputs.

Priority 2: Property-panel complexity reduction
1. Reduce concentrated propagation/apply bookkeeping in PropertyPanelController.
2. Keep behavior identical; only split ownership and duplication.
3. Add small focused tests around propagation decisions and apply boundaries.

Priority 3: Parameter-surface simplification
1. Continue reducing high-coupling zones in my_parameters.py.
2. Prefer helper extraction for repeated UI-to-domain write-back and list orchestration.
3. Avoid broad rewrites; do one seam at a time with tests.

**Execution Order (Actionable)**

Sprint A: Layout bridge first
1. Create narrow bridge module for 2D-to-3D payload and styling translation.
2. Move refresh orchestration through that bridge.
3. Add bridge-level tests.
4. Stop and stabilize.

Sprint B: Property propagation seam
1. Extract one propagation sub-flow at a time from PropertyPanelController.
2. Keep applyPropertyChanges behavior stable.
3. Add focused tests for each extracted decision seam.

Sprint C: Parameter cleanup
1. Choose one cluster in my_parameters.py.
2. Extract only repeated behavior.
3. Keep constructor wiring and changed handlers behavior-identical.

**Testing Policy**

Use narrow slices, not broad suite runs by default:
1. Run targeted tests for each touched seam.
2. Keep test_project_sidecars coverage, but avoid growing it as a catch-all.
3. When adding new layout/property tests, prefer smaller, seam-specific modules.

**Done Baseline (Short Form)**

Already landed and considered baseline:
1. Service/controller extraction for persistence, import/QC, session/runtime state, worker orchestration, and major UI action routing.
2. Sidecar compatibility and project-load application boundaries.
3. CFP parameter model/persistence/property-surface integration.
4. CFP plane logging improvements, frequency handling updates, and normalization factor logging.
5. Layout 3D Subset feature with sync from 2D layout state.
6. CFP 3x3 diagnostics extension to non-template plane paths and settings integration.
7. Focused parity validation completed: identical template/geometry support gives identical 3x3 summaries.

**Explicit Non-Goals For Now**

1. Do not start broad roll_survey rewrites.
2. Do not run speculative performance optimization before the next structural seam is landed and stable.
3. Do not expand config.py cleanup into a major track.

**Exit Criteria For This Roadmap Revision**

This roadmap iteration is successful when:
1. Layout 2D-to-3D bridge is extracted and tested as an explicit seam.
2. Property-panel propagation complexity is reduced with behavior parity.
3. New tests are better distributed across focused modules rather than concentrated in one mega-bucket.
4. No regressions in CFP plane coherent/incoherent behavior, normalization, and normFactor logging.
5. No regressions in CFP 3x3 diagnostics switch behavior, summary readability, and template/geometry parity when support is identical.

**Immediate Next Step (Documentation Focus)**

Document and lock the CFP diagnostics baseline before the next refactoring seam:
1. Update user-facing docs for CFP Settings with the new 3x3 diagnostics switch and coherent/incoherent mode behavior.
2. Add a concise diagnostics interpretation section explaining ratio meaning, OFF/COH/INC legend, and support-mismatch caveat.
3. Add one reproducible parity-check recipe (templates vs geometry) for unchanged-geometry surveys.
4. After docs are merged, resume Sprint A (layout bridge extraction).
