rinkplanner/docs/architecture.md

313 lines
16 KiB
Markdown
Raw Normal View 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` |
### 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.