Die Probe aufs Exempel für die Modularisierung: `ExportPanel` liegt jetzt in `scenes/export/export_panel.tscn`, die Whiteboard-Szene instanziiert sie nur noch. Der neue `run_export_panel_tests.gd` lädt ausschließlich diese Szene und prüft die Signale — 15 Assertions ohne WhiteboardController. Damit ist zum ersten Mal ein Baustein nicht nur im Code, sondern auch in der Prüfbarkeit getrennt. Die übrigen Suiten starten weiter die volle Szene. Stolpersteine, beide dokumentiert: Kindknoten eines Szenen-Roots brauchen `parent="."`, und ein eigener Test braucht `root.size` vor `popup_centered`, sonst landen Fenster headless auf negativen Koordinaten.
247 lines
11 KiB
Markdown
247 lines
11 KiB
Markdown
# 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–11 sind es 8.154 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 ✅ |
|
||
| `ExportPanel` | Export- und Abschlussdialog (Node mit Signalen) | 130 | Szene | 9 ✅ |
|
||
| `RulesContext` | Regelsatz: Bibliothek, Paket, drei Dokumente | 80 | keine | 5 ✅ |
|
||
| `SeasonPanelModel` | Inhalt der drei Dropdowns | 120 | keine | 6 ✅ |
|
||
| `SyncSummaryText` | Text der Sync-Zusammenfassung | 60 | keine | 7 ✅ |
|
||
| Sync-Orchestrierung | Threads, OAuth, Konflikte, Küren verwalten | ~700 | Dialoge, Threads | offen |
|
||
| `HubPanel` | Kür-Hub (Login, Upload, Downloads) | ~650 | Dialoge, Threads | 8 |
|
||
| `PlaybackPose` | Position und Blickrichtung zur Zeit | 130 | keine | 8 ✅ |
|
||
| `PlaybackPanel` | Transportleiste: Play/Pause, Reset, Slider, Tempo | 110 | Szene | 10 ✅ |
|
||
| `TimelineLabelModel` | Labels der Zeitachse einsammeln | 55 | keine | 11 ✅ |
|
||
| Playback-Rest | Musik, Label-Dialog, 3D-Anbindung | ~300 | Canvas, Audio | offen |
|
||
| `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. `SeasonPanelModel` ✅
|
||
|
||
Der Inhalt der drei Dropdowns (Saison, Programm, Kategorie) liegt in
|
||
`src/whiteboard/view/season_panel_model.gd`: reine Funktionen, die
|
||
Beschriftungen und Werte bauen und die passende Auswahl zurückgeben
|
||
(`{"items": […], "selected": int}`). Der Controller füllt seine
|
||
OptionButtons nur noch über `_fill_option()` und behält die
|
||
Signalverdrahtung.
|
||
|
||
Damit sind Fälle testbar, die vorher nur über die Szene prüfbar waren:
|
||
„nicht festgelegt", unbekannte Saison, unbekannte Kategorie (bleibt als
|
||
„nicht verfügbar" sichtbar), Programmtyp.
|
||
|
||
Noch offen: die Widgets selbst als Node mit Signalen. Das ist reiner
|
||
Verdrahtungsumbau ohne Verhaltensänderung und lohnt erst, wenn Panels auch
|
||
Layout-Verantwortung übernehmen (Roadmap: „UI in logische Bereiche
|
||
gliedern").
|
||
|
||
### 7. `SyncSummaryText` ✅ (Textteil)
|
||
|
||
Der Text der Sync-Zusammenfassung liegt in
|
||
`src/whiteboard/view/sync_summary_text.gd`; der Controller setzt nur noch das
|
||
Label. Die Zusammenfassung ist damit ohne Szene prüfbar (der Sync-Test nutzt
|
||
sie direkt).
|
||
|
||
**Bewusst offen:** die Orchestrierung selbst — Thread starten und pollen,
|
||
OAuth, Konflikte aufräumen, Küren verwalten (zusammen ~700 Zeilen). Sie
|
||
braucht einen Node mit Signalen, weil Fortschritt, Dialoge und Threads
|
||
zusammenhängen, und sie ändert die Aufrufstellen in `run_sync_tests`. Das ist
|
||
ein eigener Durchgang, kein Nachtrag.
|
||
|
||
### 8. `PlaybackPose` ✅
|
||
|
||
Die Wiedergabe-Geometrie liegt in `src/whiteboard/view/playback_pose.gd`:
|
||
`compute(entries, time, previous_heading, delta, force_heading)` liefert
|
||
Segment, Position, Blickrichtung und Markergröße. Die Markenlogik (Pirouette
|
||
dreht mit der Standzeit, Sprung dreht pro Umdrehung und wandert entlang des
|
||
Sprungvektors, Laufwege folgen der Kurve) steckt vollständig dort.
|
||
|
||
Der Controller wendet das Ergebnis nur noch auf Canvas, 3D-Vorschau und
|
||
Oberfläche an. Abgesichert durch die bestehenden Wiedergabetests (121
|
||
Assertions).
|
||
|
||
**Offen:** Steuerung (Start/Pause/Reset, Geschwindigkeit), Musik und
|
||
Timeline-Labels sowie die 3D-Anbindung.
|
||
|
||
### 10. `ElementInspector`
|
||
|
||
Zuletzt: Element-Dialog, Feature-Auswahl, Fußzuordnung, Levelableitung. Der
|
||
größte UI-Block und der, an dem am meisten hängt.
|
||
|
||
## Erster Node-Schnitt (2026-11-13)
|
||
|
||
`ExportPanel` (`src/whiteboard/view/export_panel.gd`) besitzt jetzt die
|
||
beiden Exportdialoge und meldet nur die Auswahl:
|
||
|
||
```
|
||
Panel ──export_requested(pfad, format, abschnitt, danach öffnen)──▶ Controller
|
||
```
|
||
|
||
Der Controller prüft, ob die Datei existiert (`_confirm_overwrite` bleibt die
|
||
einzige Stelle dafür), schreibt über `ExportService` und ruft
|
||
`panel.show_done()`. Das Panel fasst kein Dateisystem an.
|
||
|
||
Was beim Umhängen der Szene zu beachten war:
|
||
|
||
- `parent=` in `.tscn` ist **absolut** ab Wurzel, nicht relativ zum vorigen
|
||
Knoten. Nach dem Umhängen müssen auch alle Kindknoten ihren Pfad ändern
|
||
(`ExportDialog/…` → `ExportPanel/ExportDialog/…`), sonst verschwinden sie
|
||
beim Instanziieren mit „Parent path … has vanished".
|
||
- Der neue Knoten braucht `script = ExtResource(...)` **und** eine
|
||
`ext_resource`-Zeile; ohne Skript bleibt eine typisierte `@onready`-Zuweisung
|
||
still null.
|
||
- `load_steps` in der Kopfzeile muss mitwachsen.
|
||
|
||
### 10. `PlaybackPanel` ✅
|
||
|
||
Die Transportleiste (Play/Pause, Reset, Zeitschieber, Zeitanzeige, Tempo) ist
|
||
ein Node mit Signalen: `toggle_requested`, `reset_requested`,
|
||
`seek_requested(seconds)`, `speed_requested(speed)`. Der Controller besitzt
|
||
weiter Uhr, Tempo und Audio und ruft `set_state(time, duration, playing)`.
|
||
|
||
Anders als beim Export brauchte es **kein Umhängen**: Die Widgets bleiben in
|
||
der Layout-Leiste, das Panel findet sie über `unique_name_in_owner`. Ein Node
|
||
ohne Control-Basis kann in einem HBox nicht sinnvoll Kindknoten aufnehmen.
|
||
|
||
`_update_playback_ui` und `_update_play_button` sind zu `_sync_playback_ui()`
|
||
verschmolzen; die Zeitachse (`timeline_label_lane`) bleibt beim Controller,
|
||
weil sie zu den Timeline-Labels gehört.
|
||
|
||
### 11. `TimelineLabelModel` ✅
|
||
|
||
Das Einsammeln der Timeline-Labels liegt in
|
||
`src/whiteboard/view/timeline_label_model.gd`. Es ist subtiler, als es aussieht:
|
||
Es läuft über die Abschnitte (nicht über die Wiedergabe-Einträge), damit
|
||
Marken ohne Standzeit sichtbar bleiben, und ein Segment ohne eigenes Label
|
||
erbt die Beschriftung seiner Elementgruppe — so wird eine Sequenz einmal
|
||
benannt. Abgesichert durch die Wiedergabetests, die die Labels der Zeitachse
|
||
prüfen.
|
||
|
||
**Offen:** der Label-Dialog (Anlegen/Bearbeiten/Löschen) und die Musik
|
||
(Laden, Konvertierung, Synchronisation).
|
||
|
||
### 12. `ExportPanel` als eigene Szene ✅
|
||
|
||
`scenes/export/export_panel.tscn` enthält die beiden Dialoge und das Skript;
|
||
die Whiteboard-Szene instanziiert sie nur noch. Dazu gibt es
|
||
`tests/run_export_panel_tests.gd`: Es lädt **nur** diese Szene, hängt sie an
|
||
den Root und prüft die Signale — kein WhiteboardController, keine Kür-Szene.
|
||
|
||
Das ist die Messung, um die es ging: 15 Assertions laufen ohne die 8.154
|
||
Zeilen Controller. Der Baustein ist damit nicht nur im Code getrennt.
|
||
|
||
Zwei Stolpersteine beim Auslagern einer Szene:
|
||
|
||
- Kindknoten eines Szenen-Roots nutzen `parent="."`, nicht den Root-Namen.
|
||
- Ein eigener Test braucht `root.size` vor `popup_centered`, sonst platziert
|
||
Godot die Fenster bei headless-Läufen auf negative Koordinaten.
|
||
|
||
## Nächster Durchgang: weitere Node-Schnitte
|
||
|
||
Die vier verbleibenden Blöcke (Sync-Orchestrierung, Hub, Playback-Rest,
|
||
Element-Inspector) lassen sich nicht mehr als reine Funktionen herausziehen;
|
||
sie brauchen eigene Nodes mit Signalen. Geprüft am 2026-11-13:
|
||
|
||
- **Die Dialoge hängen direkt an der Wurzel** der Szene (31 Knoten mit
|
||
`parent="."`). Ein Panel braucht sie als Kinder, also `parent="ExportPanel"`
|
||
statt `parent="."`.
|
||
- **Das ist harmlos:** Alle Dialoge nutzen `unique_name_in_owner`, `%Name`
|
||
löst szenenweit auf. Ein Umhängen bricht weder den Controller noch die
|
||
Skripte, nur den Zugriff über Pfade (den gibt es hier nicht).
|
||
- **Der Aufwand liegt bei den Tests:** `run_sync_tests` greift direkt auf Controller-Felder zu
|
||
(`controller.export_dialog`, `controller.export_done_label`,
|
||
`controller.routine_manager_dialog`, `controller.cleanup_conflicts_dialog`).
|
||
Diese Zugriffe wandern auf `controller.<panel>.<feld>`.
|
||
- **Eine geteilte Abhängigkeit:** Der Export nutzt `_confirm_overwrite()`,
|
||
das auch „Speichern unter" verwendet. Entweder bekommt das Panel einen
|
||
eigenen Bestätigungsdialog oder der Controller reicht einen Callback durch.
|
||
Diese Entscheidung sollte vor dem Umbau fallen.
|
||
|
||
Reihenfolge: erst Export (kleinster Block, ~150 Zeilen), dann Playback-Rest,
|
||
dann Sync, zuletzt Hub und Element-Inspector.
|
||
|
||
## 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.
|