rinkplanner/docs/refactor-whiteboard-controller.md
torsten ef25c380c9 refactor: Regelsatz als eigenes Objekt (RulesContext)
Etappe 5 der Controller-Zerlegung. Der Regelsatz liegt jetzt in
`src/core/rules/rules_context.gd`: Er lädt die Bibliothek, merkt sich die
Voreinstellung, wendet eine Saison an und hält die drei Dokumente
(catalog, levels, adult).

- Der Controller besitzt genau eine Instanz (`_ruleset`) statt sechs
  Feldern; alle Zugriffe laufen über sie.
- `_load_default_rules` und `_apply_rules_for_season` delegieren nur noch.
- `RulesContext` ist ohne Szene testbar (Saison laden, wechseln, leeren);
  eigener Test mit 10 Assertions.

Bewusst offen: die drei Statusleisten-Widgets (Saison, Programm, Kategorie)
und ihre Sync-Funktionen. Sie sind reine UI und bekommen einen eigenen
Node-Schnitt (Etappe 6).

Controller: 8.529 -> 8.513 Zeilen (überwiegend Struktur, nicht Zeilen).
Suite grün.
2026-11-13 13:30:36 +01:00

115 lines
5 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters

This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

# WhiteboardController zerlegen
Stand: 2026-11-13
Ziel: Der Controller war mit **9.092 Zeilen und 465 Funktionen** der größte
Baustein im Projekt; die Roadmap nennt < 1.500 Zeilen pro Datei. Nach den
Etappen 1–5 sind es 8.513 Zeilen. Diese Notiz
hält die Reihenfolge fest, damit der Umbau in Etappen mit grüner Suite
passiert und nicht als Big Bang.
## Grundregeln
1. **Erst reine Logik, dann UI.** Textaufbau, Formatierung und Prüf-Logik
lassen sich ohne Szene testen und sind risikofrei zu verschieben. Dialoge
und Signale kommen zuletzt.
2. **Eine Etappe = ein Commit mit grüner Suite.** Keine Etappe ändert
Verhalten; die Tests bleiben unverändert, nur Aufrufstellen wandern.
3. **Kein Big Bang.** Der Controller bleibt Node und Scene-Einstiegspunkt.
Ausgelagert werden Aufgaben, nicht die Klasse.
4. **Zustand bleibt beim Controller.** `_routine`, `_current_path`, Auswahl
und Historie gehören weiter dorthin; ausgelagerte Bausteine bekommen die
Daten übergeben, statt sie zu besitzen.
## Zielbausteine
| Baustein | Inhalt | Zeilen (grob) | Kopplung | Etappe |
| :--- | :--- | ---: | :--- | :--- |
| `HelpContent` | Hilfetext für den ?-Dialog | 137 | keine | 1 ✅ |
| `SeasonComparisonText` | Zeilen für den Saisonvergleichs-Dialog | 175 | nur Daten | 2 ✅ |
| `ValidationReportView` | Zeilen für den Prüfdialog | 300 | nur Daten | 3 ✅ |
| `ExportService` | SVG/PDF schreiben, Pfade und Dateinamen | 90 | Dateisystem | 4 ✅ |
| `RulesContext` | Regelsatz: Bibliothek, Paket, drei Dokumente | 80 | keine | 5 ✅ |
| `SeasonPanel` | Saison-/Programm-/Kategorieauswahl (Widgets) | ~180 | Statusleiste | 6 |
| `SyncPanel` | Dropbox-Sync, Konflikte, Küren verwalten | ~900 | Dialoge, Threads | 7 |
| `HubPanel` | Kür-Hub (Login, Upload, Downloads) | ~650 | Dialoge, Threads | 8 |
| `PlaybackPanel` | Wiedergabe, Musik, Timeline-Labels | ~600 | Canvas, Audio | 9 |
| `ElementInspector` | Element-Dialog, Features, Level, Kombinationen | ~800 | Dialog, Regeln | 10 |
Danach bleibt ein Controller von grob 2.000–2.500 Zeilen: Verdrahtung,
Auswahl, Werkzeuge, Abschnitte, Undo/Redo, Statuszeile.
## Etappen
### 1. `HelpContent` ✅
Der Hilfetext ist ein reiner String. Verschoben nach
`src/whiteboard/view/help_content.gd` (`HelpContent.build()`), der Controller
setzt ihn nur noch in den Dialog. Kein Verhalten geändert.
### 2. `SeasonComparisonText` ✅
Der Text des Saisonvergleichs (Kopf, Gruppen, Summe, Befunde) liegt jetzt in
`src/whiteboard/view/season_comparison_text.gd`. `build(routine, report)`
gibt die BBCode-Zeilen zurück; der Controller setzt sie nur noch in das
Label. Kein Verhalten geändert.
### 3. `ValidationReportView` ✅
Der komplette Text des Prüfdialogs (Kopf, Saisonhinweis, Kategorie,
Basiswert, Punktschätzung, Wertung, Prüfliste, Befunde) liegt in
`src/whiteboard/view/validation_report_view.gd`. Signatur:
`build(routine, report, category, context)` mit einem kleinen Kontext für die
Anzeige-Optionen (Saison-Label, Saisonhinweis, Vergleich-Link, aufgeklappte
Details). Der Controller baut nur noch den Report und setzt das Label.
Fertig: Dialog unverändert, Whiteboard-Test grün, eigener Test für den Text.
### 4. `ExportService` ✅
`src/whiteboard/io/export_service.gd` schreibt SVG und PDF, legt den
Exportordner an, bildet Pfade und bereinigt Dateinamen. Der Controller
delegiert nur noch; `export_svg_to_path`/`export_pdf_to_path` bleiben als
schmale Einstiegspunkte, weil Tests sie direkt aufrufen.
Bewusst im Controller geblieben: der Export-Dialog und der
Abschluss-Dialog (Szene), der PNG-Export (braucht ein SubViewport) und das
Öffnen im Dateimanager.
### 5. `RulesContext` ✅
Der Regelsatz selbst ist jetzt ein eigenes Objekt
(`src/core/rules/rules_context.gd`): Es lädt die Bibliothek, merkt sich die
Voreinstellung, wendet eine Saison an und hält die drei Dokumente
(`catalog`, `levels`, `adult`). Der Controller besitzt genau eine Instanz
(`_ruleset`) und greift nur noch über sie zu; `_load_default_rules` und
`_apply_rules_for_season` sind auf je ein paar Zeilen geschrumpft.
Damit ist die Regelauflösung testbar, ohne eine Szene zu bauen.
Was noch offen bleibt: die drei Statusleisten-Widgets (Saison, Programm,
Kategorie) und ihre Sync-Funktionen. Sie sind reine UI und kommen als
eigener Node-Schnitt.
### 6. `SeasonPanel`
Saison-, Programm- und Kategorieauswahl als Widgets samt Sync-Funktionen
(`_sync_season_option`, `_setup_program_controls`, `set_season`, …).
### 7–9. Sync, Hub, Playback
Die drei Thread-/Dialog-Cluster. Sie hängen an Signalen und Fenstern; hier
lohnt es, die Bausteine als eigene Nodes mit Signalen zu schneiden, statt als
RefCounted mit Rückruf.
### 10. `ElementInspector`
Zuletzt: Element-Dialog, Feature-Auswahl, Fußzuordnung, Levelableitung. Der
größte UI-Block und der, an dem am meisten hängt.
## Was bewusst bleibt
- `_ready()` und die Signalverdrahtung der Szene.
- Undo/Redo und die Historie (arbeiten auf dem gesamten Kürzustand).
- Die Statuszeile als Zusammenfassung (`_update_status`), solange Panels sie
nicht selbst besitzen.