- FTP/FTPS-Client (USER/PASS, AUTH TLS + PROT P, EPSV/PASV, MLSD, SIZE, RETR, STOR, DELE, MKD, RNFR/RNTO) ohne externe Bibliothek - Sync-Vergleich pro Kürdatei mit lokalem Sync-Stand: hochladen, herunterladen, überspringen; beidseitige Änderungen bleiben als Kopie mit Server-Zeitstempel erhalten, die lokale Fassung wird nie verworfen - Sync-Einstellungen (Host, Port, Benutzer, Passwort, Verzeichnis, FTPS, Zertifikatsprüfung) unter user://sync.cfg, nicht im Repository - Sync läuft im Thread, Fortschritt in der Statusleiste, Zusammenfassung im Dialog; geöffnete Kür wird nur unverändert neu geladen - Atomare Ersetzung über .part/.bak, Uploads über .uploading + Umbenennen - Tests für Vergleichsregeln, Konfliktnamen, PASV/EPSV/MDTM, Sync-Stand und Einstellungs-Dialog; zusätzlich E2E gegen den echten FTP-Server - docs/sync.md mit Einrichtung, Verhalten und Grenzen
17 KiB
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, Label |
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 – Beschriftungen sind Freitext am Segment.
Jedes Segment kann ein label tragen (max. 40 Zeichen, getrimmt). Es wird im
aktiven Abschnitt neben dem Segmentmittelpunkt gezeichnet, in Präsentation und
Export für alle sichtbaren Abschnitte. Der globale Schalter „Labels“ blendet
alle Beschriftungen in der Ansicht aus; Exporte enthalten sie immer.
D6 – 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.
D7 – 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).RinkCanvaszeichnet 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:
WhiteboardControllerhä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 perclamp_point()auf die Eisfläche begrenzt. - Bogen-Vorlage:
ArcGeometryerzeugt einen Kreisbogen mit 40 % der Sehnenlänge als Pfeilhöhe und liefert eine gesampelteCurve2D-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_ratioundarc_bulge_leftamPathSegmentgespeichert, 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_orderwird 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_modelegt 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
Curve2Dnach Bogenlänge (get_baked_length()/sample_baked()), nicht nach Control-Point-Index. - Phase-1-Code importiert nichts aus
prototype/und enthält keineNode3D-Abhängigkeiten.
5. Rendering und Plattformen
Gesetzt in rinkplanner/project.godot:
| Plattform | Renderer |
|---|---|
| Desktop (Linux/Windows/macOS) | forward_plus |
| Android | mobile |
Ziele sind ausschließlich native Builds; einen Web-Export gibt es nicht
mehr. Details und Befehle: docs/builds.md.
UI-Skalierung (Touch-first)
window/stretch/mode="disabled": Die Oberfläche wird in realen Fensterpixeln
gelayoutet. Zusätzlich setzt der Controller Window.content_scale_factor auf
die Bildschirm-Skalierung (DisplayServer.screen_get_scale()). Auf dem
Tablet (DPR ≈ 2,6) entspricht eine Layout-Einheit damit 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
HFlowContainerund bricht bei Bedarf um, statt seitlich abgeschnitten zu werden. - Geprüfte Landschaftsbreiten: 1024 px (kleine Tablets) 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 unteruser://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.tresund wird beim Start automatisch wiederhergestellt. Der Dirty-State wird im Fenstertitel als*angezeigt. Beim Verlassen wird zusätzlich gespeichert. - Builds: Linux, Windows, macOS und Android über
tools/export_*.sh; Presets inrinkplanner/export_presets.cfg. Android nutzt das Template-Export-Verfahren ohne Gradle-Projekt,arm64-v8a,minSdk 24,targetSdk 36, Landscape und Immersive Mode. Details indocs/builds.md. - Lokale Daten:
user://liegt pro Plattform getrennt (Linux~/.local/share/godot/app_userdata/Rinkplanner/, Android im app-internen Speicher). - Kontosync: manueller FTP-/FTPS-Abgleich der
.tres-Dateien überFtpClient,SyncPlanundRoutineSync; Details indocs/sync.md. Zugangsdaten liegen inuser://sync.cfg, der letzte gemeinsame Stand inuser://sync_state.cfg. Konflikte werden als Kopie mit Server-Zeitstempel behalten.
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: 149 Assertions für Controller-Verdrahtung, Segmenterzeugung, Linien-/Bogenpfade, Klemmen an der Bande, Auswahl, Griff- und Richtungs-/Kanten-Bearbeitung, Segmentlöschung, Section-Verwaltung, Ghosting-Zustand, Segment-Labels inklusive Dialog und Sichtbarkeits-Schalter, Speichern/Laden, Schema-Prüfung, Dirty-State, Navigationsmodus und den Maus-Drag-Pfad.
- History: 53 Assertions für Undo/Redo von Segmenten, Kanten, Labels, 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: 19 Assertions für SVG-Struktur, Titel-Escaping, Segment-Labels, 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).
- Sync: 31 Assertions für Vergleichsregeln, Konfliktnamen, Zeitstempel, PASV/EPSV/MDTM-Parsing, Sync-Stand und die Einstellungs-Verdrahtung. Der FTP-Client wurde zusätzlich gegen den echten Zielserver geprüft (Upload, Download, Konflikt, Aufräumen).
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
- Eckenradius: 8,5 m ist als Default gesetzt. ISU- und IIHF-Regelwerk können abweichen; der Wert gehört später in die Regelkonfiguration.
- Element-Instanzen: Aktuell verweist
PathSegment.element_idauf ein Element. Ob Sprünge/Pirouetten eigene Instanzen mit Position und Zeit brauchen, wird mit dem Regelmodell entschieden. - 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.
- 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.
- 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.
- Segment-Verknüpfung: Beim Verschieben eines Endpunkts werden Nachbarsegmente nicht automatisch mitgezogen. Ob Pfade später als zusammenhängende Kette editiert werden, ist offen.
- 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.
- Persistenz-Backups: Autosave nutzt genau einen Slot. Ob zusätzlich rotierende Backups oder Versionen pro Speichervorgang nötig sind, zeigt sich im Praxisbetrieb.
- Dateinamen: Die Normalisierung ersetzt Leerzeichen und entfernt Pfadzeichen, transliteriert aber keine Umlaute. Für Windows und den geplanten FTP-Sync ist zu prüfen, ob eine ASCII-Normalisierung robuster ist.
- 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. - 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.
- Playback-Komfort: Loop, Scrubbing während des Abspielens und Audio-Synchronisation sind bewusst noch nicht enthalten.