rinkplanner/docs/architecture.md
torsten 43da04b3cc feat: Segment-Timing mit Profilen und Kalibrierung hinzufügen
- Timing-Leiste mit gekoppelter Dauer-/Tempo-Bearbeitung
- Level-Presets Adult Bronze bis Elite, Default Adult Gold 4,3 m/s
- Kalibrierdialog Strecke/Zeit und Standard-Reset
- PathSegment speichert Geschwindigkeit oder Dauer als maßgebliche Größe
- Schema-Version 2 mit Migration alter Dateien
- Tests auf 400 Assertions erweitert
2026-10-30 08:48:12 +01:00

14 KiB
Raw Blame History

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

Die Designauflösung ist 1920 × 1200 mit canvas_items / expand; die Oberfläche skaliert mit, das Rink-Koordinatensystem bleibt in Metern.

Touch-Ziele: mindestens 48 × 48 px. Für Desktop-Tests kann temporär input_devices/pointing/emulate_touch_from_mouse=true aktiviert werden; standardmäßig bleibt es aus.

6. Export und Persistenz

  • SVG wird direkt aus dem Modell serialisiert (Kurven als Pfade), nicht aus einem Screenshot. Damit bleibt der Export auflösungsunabhängig.
  • PNG entsteht über einen Viewport-Render in hoher Auflösung.
  • 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. Die Persistenz funktioniert dort über user://; ein echter Browser-/Tablet-Test steht noch aus.

7. Tests

Headless, ohne Editor und ohne Display:

./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.

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.