# Rinkplanner – Architektur & Entscheidungen (Phase 1) Stand: 2026-10-30 Grundlage: `rinkplanner/rinkplanner_definition_agent_guidelines.md` Übergeordnete Reihenfolge: `docs/roadmap.md` ## 1. Leitentscheidung Phase 1 ist eine eigenständige 2D-Anwendung. Sie muss ohne 3D-Renderer, ohne `Node3D` und ohne Blender-Assets lauffähig sein. Der bisherige 3D-Test ist ein Machbarkeitsnachweis und liegt isoliert unter `rinkplanner/prototype/3d_test/`. Er ist nicht Teil der Phase-1-Runtime und wird nicht weiterentwickelt. Phase 2 konsumiert später dasselbe Datenmodell über eine eigene Präsentationsschicht. ## 2. Repository-Layout ``` /home/torsten/repos/rinkplanner/ # Repo-Root ├── docs/ # Architektur, ADRs, Regelwerk-Doku ├── tools/ # Host-Helfer (Tests, Export, CI) └── rinkplanner/ # Godot-Projekt (res://) ├── project.godot ├── src/ │ ├── core/model/ # reine Daten-Resources │ └── core/rules/ # ISU-Regeln (folgt) ├── whiteboard/ # Phase 1: view / ctrl / io (folgt) ├── scenes/ # dünne Szenen, die Views zusammensetzen ├── assets/ ├── tests/ # headless GDScript-Tests └── prototype/3d_test/ # alter 3D-Test, eingefroren ``` `docs/` und `tools/` liegen bewusst außerhalb von `res://`. Sie werden von Godot nicht importiert und enthalten keine Laufzeitabhängigkeiten. ## 3. Datenmodell (Model) ``` Routine ├── rink: RinkDimensions └── sections: Array[RoutineSection] └── segments: Array[PathSegment] └── curve: Curve2D ``` Implementiert in `rinkplanner/src/core/model/`: | Klasse | Verantwortung | | :--- | :--- | | `Routine` | Wurzelaggregat, Validierung, Gesamtdauer/-länge, Section-Lookup | | `RoutineSection` | chronologischer Block, Ghosting-Einheit, Segmentliste | | `PathSegment` | durchgehender Pfad mit Richtung, Kante, Dauer, Element-Marker | | `RinkDimensions` | Maße, Koordinaten, Punkte-/Kurvenprüfung | ### Entscheidungen **D1 – Segment statt Section als Träger von Richtung und Kante.** Ein `RoutineSection` kann viele Kanten- und Richtungswechsel enthalten. Deshalb liegen `direction` und `edge` auf `PathSegment`, nicht auf der Section. **D2 – Zeit ist die Autorengröße, Geschwindigkeit wird abgeleitet.** `PathSegment.duration_seconds` wird gepflegt. Die Strecke kommt aus der Kurve; `get_speed_mps()` berechnet daraus die Geschwindigkeit. Das hält die Dot-Simulation deterministisch und vermeidet widersprüchliche Metadaten. **D3 – Marker sind gültige Segmente.** Ein Segment mit Länge braucht eine positive Dauer. Ein reiner Element-Marker (Länge 0, z. B. Sprungpunkt) darf Dauer 0 haben und wird über `is_marker()` erkannt. **D4 – Koordinaten in Metern, Ursprung in der Rinkmitte.** +X verläuft entlang der langen Achse (−30 m … +30 m), +Y entlang der kurzen Achse (−15 m … +15 m). Nur die View rechnet in Pixel um. Gespeicherte Daten sind damit auflösungsunabhängig. **D5 – IDs sind Pflicht und global eindeutig.** `routine_id`, `section_id` und `segment_id` werden validiert. Die ID-Erzeugung gehört in den Controller, nicht ins Modell. **D6 – Validierung liefert Fehlertexte.** `validate() -> PackedStringArray` ist die primäre API; `is_valid()` ist nur eine Abkürzung. So kann die UI Fehler konkret anzeigen. ## 4. View- und Controller-Grenzen - **View** (`Node2D`/`Control`) liest das Modell und zeichnet. Sie verändert keine Modelldaten und enthält keine Fachlogik. - **Meter→Pixel** läuft ausschließlich über `CanvasTransform` (reine Mathematik, headless testbar). `RinkCanvas` zeichnet Rink, Mittellinie und Mittelkreis und behandelt Pan/Zoom (Maus, Touch, Pinch). - **Controller** übersetzt Touch-/Maus-Eingaben in Modelloperationen (Segment anlegen, Kante umschalten, Section wechseln, Playback steuern). - **Zeichenwerkzeuge:** `WhiteboardController` hält eine Draft-Routine mit einer Section. Die Toolbar bietet Auswählen, Linie, Bogen links und Bogen rechts; Richtung (vorwärts/rückwärts) und Kante (innen/außen) gelten für das nächste Segment. Neue Segmente starten mit dem gewählten Timing-Profil (Default Adult Gold, 4,3 m/s); Züge über die Bande werden per `clamp_point()` auf die Eisfläche begrenzt. - **Bogen-Vorlage:** `ArcGeometry` erzeugt einen Kreisbogen mit 40 % der Sehnenlänge als Pfeilhöhe und liefert eine gesampelte `Curve2D`-Polyline. Liegt der Bogen außerhalb des Rinks, wird die Pfeilhöhe schrittweise reduziert; die gerade Sehne ist der letzte Fallback. Die Bogen-Seite ist relativ zur Ziehrichtung (Start → Ende) definiert. - **Auswahl und Bearbeitung:** Im Modus „Auswählen“ pickt ein Tipp auf das aktive Segment. Start- und Endpunkt haben weiße Griffe, Bögen zusätzlich einen orangen Bogen-Griff. Endpunkt-Griffe verschieben die Kurve, der Bogen-Griff ändert Tiefe und Seite. Richtung und Kante lassen sich über die Toolbar auch nachträglich ändern; die Buttons spiegeln dabei den Zustand des ausgewählten Segments. Ohne Auswahl gelten sie für das nächste Segment. „Segment löschen“ in der Statusleiste ist nur bei Auswahl aktiv; zusätzlich löschen Entf und Backspace das ausgewählte Segment. Ghost-Sections sind nicht interaktiv. Die Bogenparameter werden als `template`, `arc_depth_ratio` und `arc_bulge_left` am `PathSegment` gespeichert, damit die Kurve nach dem Editieren neu aufgebaut werden kann. - **Section-Verwaltung:** Ein Panel rechts zeigt die chronologische Abschnittsliste. Neue Sections werden angelegt, umbenannt, gelöscht und hoch-/runtergeschoben; `sequence_order` wird nach jeder Änderung durchnummeriert, die Section-IDs bleiben stabil. Die aktive Section wird voll gezeichnet, alle anderen mit 20 % Deckkraft geghostet. Beim Wechsel wird eine eventuelle Segmentauswahl verworfen. - **Dokument-Lifecycle:** Das Datei-Menü bietet Neu, Öffnen, Speichern und Speichern unter. Ein Dirty-State markiert ungespeicherte Änderungen im Fenstertitel; Neu/Öffnen fragen vor dem Verwerfen. Autosave und Restore laufen unabhängig davon im Hintergrund. - **Undo/Redo:** Snapshot-Historie mit maximal 50 Einträgen über Segment-, Griff-, Richtungs-/Kanten- und Section-Änderungen. Die Historie stellt die aktive Section wieder her, nicht die Zoom-/Pan-Ansicht. Strg+Z, Strg+Shift+Z und Strg+Y; die Toolbar-Buttons sind am jeweiligen Ende der Historie deaktiviert. Öffnen und Neu starten eine neue Historie. - **Playback:** Ein Marker durchläuft alle Sections und Segmente kontinuierlich per Bogenlängen-Sampling (`sample_baked()`). Die Blickrichtung folgt der Kurventangente; bei Rückwärts-Segmenten wird sie um 180° gedreht, sodass die Bewegung entlang des Pfades und die Körperrichtung getrennt sichtbar sind. Während des Playbacks wird die aktuelle Section hervorgehoben, ohne die Bearbeitungs-Section zu wechseln. Steuerung: Play/Pause, Reset, Timeline-Scrubbing und Geschwindigkeit 0,25×–2,0×. Die Dauer kommt aus dem Segment-Timing (Default Adult Gold, 4,3 m/s). Nicht verbundene Segmente führen zu einem Sprung des Markers an den Start des nächsten Segments. - **Geschwindigkeitsannahmen:** Die belastbaren Referenzwerte, Level-Profile und Kalibrierung stehen in `docs/speed-assumptions.md`. - **Segment-Timing:** Die Timing-Leiste zeigt Dauer und Tempo des ausgewählten Segments. Beide Werte sind gekoppelt; `PathSegment.timing_mode` legt fest, welche Größe bei Geometrieänderungen erhalten bleibt. Level-Presets (Adult Bronze bis Elite), `±`-Schritte, „Standard“ (Adult Gold, 4,3 m/s) und ein Kalibrierdialog (Strecke/Zeit → m/s) sind umgesetzt. - **Darstellung:** vorwärts durchgezogen, rückwärts gestrichelt, außen rot, innen blau. Inaktive Sections werden mit 20 % Deckkraft geghostet. - **Ghosting** ist reine View-Logik: pro Section ein eigener Layer, inaktive Layer auf 20 % Deckkraft, `mouse_filter = IGNORE`. - **Playback** samplet `Curve2D` nach Bogenlänge (`get_baked_length()` / `sample_baked()`), nicht nach Control-Point-Index. - Phase-1-Code importiert nichts aus `prototype/` und enthält keine `Node3D`-Abhängigkeiten. ## 5. Rendering und Plattformen Gesetzt in `rinkplanner/project.godot`: | Plattform | Renderer | | :--- | :--- | | Desktop | `forward_plus` | | Mobile | `mobile` | | Web (Wasm) | `gl_compatibility` | ### UI-Skalierung (Touch-first) `window/stretch/mode="disabled"`: Die Oberfläche wird in realen Fenster- bzw. CSS-Pixeln gelayoutet. Zusätzlich setzt der Controller `Window.content_scale_factor` auf die Bildschirm-Skalierung (`DisplayServer.screen_get_scale()`). Damit entspricht eine Layout-Einheit auf Tablets einem CSS-Pixel und wird trotzdem in Gerätepixeln gerendert: - Ein 56-px-Button ist auf dem Tablet wirklich 56 CSS-Pixel groß, statt durch eine feste Designauflösung kleingerechnet zu werden. - Das Rink bleibt in Metern; nur die Pixelabbildung ändert sich. - Der PNG-Export ist unabhängig davon (eigener `SubViewport`, 2560 × 1600). ### Responsive Leiste - Ab 1280 px Breite: volle Beschriftungen („Rinkplanner“, „Werkzeug“, „Rückgängig“, „Wiederholen“, „Kalibrieren“). - Unter 1280 px: kompakte Beschriftungen („Undo“, „Redo“, „Kalib.“), Titel und Werkzeug-Label entfallen, das Sections-Panel wird 260 statt 300 px breit. - Die Timing-Leiste ist ein `HFlowContainer` und bricht bei Bedarf um, statt seitlich abgeschnitten zu werden. - Geprüfte Landschaftsbreiten: 1024 px (iPad-Landscape) und 1400 px (Galaxy Tab S9+). Hochformat ist noch nicht gestaltet. ### Zeichen-Cache `RinkCanvas` cached die in Bildschirmpunkte gesampelten Kurven pro Segment. Der Cache wird verworfen, sobald sich Pan/Zoom oder die Kontrollpunkte ändern. Gerade Linien (zwei Punkte ohne Griffe) werden direkt als zwei Punkte gezeichnet. Im Stresstest (480 Segmente, 12 Sections) sinkt die mittlere Redraw-Zeit dadurch von ca. 48 ms auf ca. 7–10 ms. ### Touch-Ziele Mindestens 56 × 56 px. Für Desktop-Tests kann temporär `input_devices/pointing/emulate_touch_from_mouse=true` aktiviert werden; standardmäßig bleibt es aus. Chrome sendet zusätzlich synthetische Maus-Events: eines vor `touchstart` (wird beim Touch-Start verworfen) und ggf. eines nach `touchend` (300-ms-Guard). ## 6. Export und Persistenz - **SVG** wird direkt aus dem Modell serialisiert (Kurven als Pfade, Section-Nummern, Legende, Rink), nicht aus einem Screenshot. Damit bleibt der Export auflösungsunabhängig. - **PNG** entsteht über eine eigene Export-Szene in einem `SubViewport` (2560 × 1600) mit Titel, Section-Nummern und Legende. - **Umfang:** Gesamte Kür oder aktiver Abschnitt; Dateien landen unter `user://exports/`. - **PDF** ist nicht nativ in Godot. Erste Stufe: Browser-Druck aus SVG; eine echte PDF-Ausgabe ist ein separates Arbeitspaket. - **Persistenz** erfolgt lokal als `.tres`-Ressourcen unter `user://routines/`. `Routine.schema_version` (aktuell 2) schützt vor inkompatiblen neueren Dateien; Schema-1-Dateien werden beim Laden migriert und behalten ihre bisherige Dauer. Benannte Kürläufe werden über das Datei-Menü gespeichert und geladen; der Öffnen-Dialog nutzt 48-px-Buttons statt einer kleinen Dateiliste. - **Autosave** schreibt nach 1,5 s Inaktivität nach `user://autosave.tres` und wird beim Start automatisch wiederhergestellt. Der Dirty-State wird im Fenstertitel als `*` angezeigt. Beim Verlassen wird zusätzlich gespeichert. - **Web:** `FileAccess` schreibt in den IndexedDB-Speicher. Im echten Chrome-Touch-Test auf einem 1024-px- und einem 1400-px-Layout (DPR 2) überlebt die Kür einen Browser-Reload. - **Web-Build:** `tools/export_web.sh` exportiert nach `build/web/` (single-threaded, kein COOP/COEP nötig). Details in `docs/web-test.md`. ## 7. Tests Headless, ohne Editor und ohne Display: ```bash ./tools/test.sh ``` Aktueller Stand: - **Model:** 55 Assertions für Rink-Geometrie, Clamping, Segment-Timing, Timing-Modi, Template-Metadaten, Schema-Version, Section-Aggregation und Routine-Validierung. - **Canvas:** 90 Assertions für Meter→Pixel-Mapping, Fit/Zoom/Pan, Rink-Kontur und die reine Bogen-Geometrie. - **Whiteboard:** 129 Assertions für Controller-Verdrahtung, Segmenterzeugung, Linien-/Bogenpfade, Klemmen an der Bande, Auswahl, Griff- und Richtungs-/Kanten-Bearbeitung, Segmentlöschung, Section-Verwaltung, Ghosting-Zustand, Speichern/Laden, Schema-Prüfung, Dirty-State, Navigationsmodus und den Maus-Drag-Pfad. - **History:** 47 Assertions für Undo/Redo von Segmenten, Kanten, Sections, Zeichengesten und Griff-Bearbeitung, Toolbar-Buttons, Erhalt der Ansicht sowie das Zurücksetzen der Historie. - **Playback:** 38 Assertions für Dauer/Timeline, Vorwärts-/Rückwärts- Blickrichtung, Section-Hervorhebung, Play/Pause/Reset inklusive Button-Verdrahtung, Scrubbing und Geschwindigkeitswechsel. - **Timing:** 41 Assertions für Dauer-/Tempo-Kopplung, Level-Presets, Kalibrierung, Undo, Persistenz und Schema-1-Migration. - **Export:** 17 Assertions für SVG-Struktur, Titel-Escaping, Section-Filter, Segmentfarben/-strichelung und das Schreiben der Exportdatei. - **Touch/Tablet:** 21 Assertions für Ein-Finger-Zeichnen, Zwei-Finger-Pan, Pinch-Zoom, Tipp-Auswahl, Griff-Bearbeitung, Abbruch bei zweitem Finger, Unterdrückung synthetischer Maus-Events aus Chrome sowie das responsive Leistenlayout bei 1024 und 1400 px. - **Performance:** Stresstest mit 480 Segmenten in 12 Sections; die mittlere Redraw-Zeit muss unter 120 ms bleiben (aktuell ca. 7–10 ms). Autosave/Restore wird zusätzlich in einem isolierten `XDG_DATA_HOME` end-to-end geprüft. Visuelle Smoke-Tests laufen zusätzlich über `xvfb-run` und einen Viewport-Screenshot; sie ersetzen die headless Tests nicht. ## 8. Offene Entscheidungen 1. **Eckenradius:** 8,5 m ist als Default gesetzt. ISU- und IIHF-Regelwerk können abweichen; der Wert gehört später in die Regelkonfiguration. 2. **Element-Instanzen:** Aktuell verweist `PathSegment.element_id` auf ein Element. Ob Sprünge/Pirouetten eigene Instanzen mit Position und Zeit brauchen, wird mit dem Regelmodell entschieden. 3. **History-Grenzen:** 50 Snapshots ohne Coalescing; Undo zurück zum gespeicherten Stand setzt den Dirty-Marker nicht automatisch zurück. Für lange Sessions ist zu prüfen, ob das reicht. 4. **Section-Übergänge:** Playback läuft derzeit kontinuierlich ohne Übergangspause; Section-Startzeiten werden ausschließlich aus den Segmentdauern abgeleitet. Ob explizite Übergangszeiten nötig sind, zeigt die Praxis. 5. **Kurven und Templates:** Linie, Kreisbogen und die Bearbeitung von Start/Ende, Seite und Tiefe sind umgesetzt. Offen sind Freihand sowie weitere Templates wie Acht und Dreier. 6. **Segment-Verknüpfung:** Beim Verschieben eines Endpunkts werden Nachbarsegmente nicht automatisch mitgezogen. Ob Pfade später als zusammenhängende Kette editiert werden, ist offen. 7. **Section-Darstellung:** Die aktuelle Scrollliste funktioniert für wenige Abschnitte. Bei langen Kürprogrammen ist zu prüfen, ob eine horizontale Timeline mit Zeitproportionen die bessere Bedienung ist. 8. **Persistenz-Backups:** Autosave nutzt genau einen Slot. Ob zusätzlich rotierende Backups oder Versionen pro Speichervorgang nötig sind, zeigt sich im Praxisbetrieb. 9. **Dateinamen:** Die Normalisierung ersetzt Leerzeichen und entfernt Pfadzeichen, transliteriert aber keine Umlaute. Für Web/Windows ist zu prüfen, ob eine ASCII-Normalisierung robuster ist. 10. **Snapshot-Clone:** `_clone_routine()` kopiert die Modellfelder manuell. Neue Felder am Modell müssen dort ergänzt werden, sonst fehlen sie in Undo/Redo-Snapshots. 11. **Segment-Timing:** Dauer/Tempo, Presets, Kalibrierung und Migration sind umgesetzt. Offen sind Beschleunigung/Verzögerung innerhalb eines Segments und eine noch genauere Profilpflege aus eigenen Messungen. 12. **Playback-Komfort:** Loop, Scrubbing während des Abspielens und Audio-Synchronisation sind bewusst noch nicht enthalten.