rinkplanner/docs/architecture.md
torsten d44a4e1e2f feat: Tablet- und Web-Bedienung härten
- Oberfläche in CSS-Pixeln layouten (stretch disabled,
  content_scale_factor = Bildschirm-Skalierung), damit 56-px-Ziele auf
  Tablets auch 56 CSS-Pixel groß sind
- Kompakte Werkzeugleiste unter 1280 px, umbruchfähige Timing-Leiste;
  1024 px (iPad-Landscape) und 1400 px (Tab S9+) geprüft
- Chrome-Guard gegen synthetische Maus-Events vor/nach Touch-Gesten
- Web-Export-Preset und tools/export_web.sh (single-threaded)
- Kurven-Cache und Linien-Fastpath: Stresstest mit 480 Segmenten von
  ca. 48 ms auf ca. 7-10 ms pro Redraw
- Neue Suiten für Touch/Layout und Performance, Tablet-Testanleitung in
  docs/web-test.md
2026-10-30 09:37:14 +01:00

312 lines
16 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters

This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

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