162 lines
6.7 KiB
Markdown
162 lines
6.7 KiB
Markdown
|
|
# 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).
|
|||
|
|
- **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:** 36 Assertions für Rink-Geometrie, Segment-Timing,
|
|||
|
|
Section-Aggregation und Routine-Validierung.
|
|||
|
|
- **Canvas:** 67 Assertions für Meter→Pixel-Mapping, Fit/Zoom/Pan und die
|
|||
|
|
Rink-Kontur inklusive Eckradien.
|
|||
|
|
|
|||
|
|
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:** Command-Pattern im Controller oder Resource-Snapshots –
|
|||
|
|
Entscheidung vor dem ersten Zeichen-Tool.
|
|||
|
|
4. **Section-Übergänge:** Ob Sections eine explizite Startzeit erhalten oder
|
|||
|
|
ausschließlich aus Segmentdauern abgeleitet werden, klärt die
|
|||
|
|
Playback-Implementierung.
|
|||
|
|
5. **Zeichenwerkzeug:** Ob freie Kurven direkt als Bézier-Segmente oder über
|
|||
|
|
Template-Geometrie (Lobe, Bogen, Acht) entstehen, entscheidet der erste
|
|||
|
|
Tool-Prototyp. Der 3D-Prototyp ist nicht mehr die Hauptszene.
|