rinkplanner/docs/architecture.md
torsten 5face42141 fix: Richtung und Kante für ausgewählte Segmente bearbeiten
- Kanten-/Richtungsbuttons ändern das aktive Segment statt nur den Default
- Toolbar spiegelt Richtung und Kante der Auswahl
- Statusleiste zeigt Richtung und Kante des ausgewählten Segments
- Regressionstests für Toolbar-Sync und Modelländerung ergänzt
2026-10-30 07:56:24 +01:00

198 lines
9.3 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`
## 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. Die Dauer wird mit 6 m/s aus der Länge abgeleitet, 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.
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.
- **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. Auf Web schreibt
`FileAccess` in den IndexedDB-Speicher; Speichern/Laden/Autosave brauchen
deshalb eine explizite UX.
## 7. Tests
Headless, ohne Editor und ohne Display:
```bash
./tools/test.sh
```
Aktueller Stand:
- **Model:** 45 Assertions für Rink-Geometrie, Clamping, Segment-Timing,
Template-Metadaten, Section-Aggregation und Routine-Validierung.
- **Canvas:** 90 Assertions für Meter→Pixel-Mapping, Fit/Zoom/Pan,
Rink-Kontur und die reine Bogen-Geometrie.
- **Whiteboard:** 105 Assertions für Controller-Verdrahtung, Segmenterzeugung,
Linien-/Bogenpfade, Klemmen an der Bande, Auswahl, Griff- und
Richtungs-/Kanten-Bearbeitung, Undo, Section-Verwaltung, Ghosting-Zustand,
Navigationsmodus und den Maus-Drag-Pfad.
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. **Undo/Redo:** Aktuell entfernt „Rückgängig“ nur das letzte Segment.
Vollständiges Undo/Redo (Command-Pattern oder Snapshots) bleibt offen.
4. **Section-Übergänge:** Ob Sections eine explizite Startzeit erhalten oder
ausschließlich aus Segmentdauern abgeleitet werden, klärt die
Playback-Implementierung.
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.