rinkplanner/docs/refactor-whiteboard-controller.md
torsten 5161869ec2 refactor: Anbieterliste der Sync-Einstellungen als Modell
`SyncSettingsModel` (src/whiteboard/view/sync_settings_model.gd) baut die
Anbieterliste aus der Build-Konfiguration: Google Drive nur mit
OAuth-Zugangsdaten, Dropbox immer (damit ein Entwickler-Build die fehlende
Konfiguration zeigt statt einer leeren Liste).

Der Controller füllt sein Dropdown nur noch daraus. Test für die drei Fälle
(nur Dropbox, mit Google, ohne Zugangsdaten) und die Suche per Id.

Controller: 8.154 -> 8.142 Zeilen. Suite grün.

Kein eigener Dialog-Schnitt an dieser Stelle: Der Sync-Dialog enthält Sync
und Hub zusammen und hängt an Threads; eine Szene ohne verschobenes Verhalten
wäre nur eine Existenzprüfung.
2026-11-13 15:06:44 +01:00

12 KiB
Raw Blame History

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 Nach Etappe 13 sind es 8.142 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 ✅
SyncSettingsModel Anbieterliste der Sync-Einstellungen 40 keine 13 ✅
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.

13. SyncSettingsModel ✅

Die Anbieterliste der Sync-Einstellungen liegt in src/whiteboard/view/sync_settings_model.gd: Das Build-Konfigurationsobjekt geht rein, die auswählbaren Anbieter kommen raus. Google Drive erscheint nur mit OAuth-Zugangsdaten; Dropbox bleibt auch ohne sichtbar, damit ein Entwickler-Build die fehlende Konfiguration zeigt statt einer leeren Liste.

Warum hier kein eigener Dialog-Schnitt folgt: Der Sync-Dialog enthält Sync und Hub (rund 30 Widgets) und hängt an Threads und OAuth-Zustand. Eine eigene Szene ohne verschobenes Verhalten ergäbe einen Test, der nur prüft, dass Widgets existieren — das ist keine Aussage über Modularität.

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.