chore: initial import

2026-07-24 21:37:03 +02:00
commit 6b4ed9bc36
111 changed files with 95131 additions and 0 deletions
@@ -0,0 +1,62 @@
+# Domänenmodell
+
+## Vertragsversionen
+
+- Plan: `schema_version = 3`
+- Trainingsvertrag: `contract_version = 2`
+- Ergebnisschema: Version 2
+- Tracker: `version = 7`
+- Ergebnisdaten: `version = 2`
+
+## Identitäten
+
+Dauerhaft stabil sind `plan_id`, Phasen-ID, Tages-ID, Rotations-ID, Übungsplatzierungs-ID, Bewegungs-`exercise_id`, `progression_id`, Progressions-ID und Stufen-ID. `legacy_id` wie `d1-r0-e0` dient ausschließlich der Migration alter Sessions. Neue Sessionitems werden mit der stabilen Übungsplatzierungs-ID gespeichert.
+
+## Planlebenszyklus
+
+Eine Plandatei besitzt `config` als veröffentlichte Fassung und `draft` als bearbeitbaren Entwurf. `revision` schützt Bearbeitungen, `published_revision` kennzeichnet die vom Tracker gelesene Fassung. Entwurf speichern und veröffentlichen sind getrennte Operationen.
+
+## Planstruktur
+
+Plan → Phasen, Tage, Progressionen, Übungsbibliothek und Trainingsformat.
+
+Tag → Warm-up, Rotationen, Cooldown, Stretch.
+
+Rotation → stabile ID, Bezeichnung, Übungen.
+
+Übungsplatzierung → `id`, `legacy_id`, `exercise_id`, `progression_id`, Name, Hinweise, Standard-`result_schema`.
+
+Progression → stabile ID/Key, Name, geordnete Stufen.
+
+Progressionsstufe → ID, Name, optionale Phase, Bewegungscluster, Analysefaktor und optional überschreibendes `result_schema`.
+
+## Ergebnisschema
+
+Auflösungsreihenfolge:
+
+1. manuelle Sessionanpassung,
+2. Schema der gewählten Progressionsstufe,
+3. Standardschema der Übung,
+4. automatische Fallback-Erkennung.
+
+Felder: `mode` (`reps`, `seconds`, `minutes`, `none`, im Plan zusätzlich `auto`), `weight_mode` (`none`, `optional`, `required`), `laterality` (`bilateral`, `unilateral`), `sides_mode` (`same`, `separate`) sowie optional eine feste Satzanzahl.
+
+## Tracker
+
+Tracker → Profil, Sessions, Wochenstatus, Revision und Planbezug.
+
+Session-Key: `wNN-dNN`. Sessionstatus: `planned`, `in_progress`, `stopped`, `completed`.
+
+Sessionitemstatus: `planned`, `completed`, `partial`, `skipped`. `done` bleibt als Kompatibilitätsfeld erhalten und ist bei `completed` oder `partial` wahr.
+
+`result_data` speichert eine Messart, gemeinsame oder getrennte Satzwerte und höchstens ein gemeinsames Gewicht. Unterschiedliche Gewichte pro Satz, RIR, RPE und Technikrating gehören bewusst nicht zum Vertrag.
+
+## Analyse
+
+`analysis_state` ist persistent und kann `idle`, `running`, `done` oder `error` sein. Der Cache enthält höchstens eine Analyse je Woche und genau eine Gesamtanalyse. Neuberechnung überschreibt dieselbe Datei. Es gibt keine Historie.
+
+`analysis_catalog` kennzeichnet Wochen als `missing`, `stale` oder `current`; die Gesamtanalyse zusätzlich als `needs_weeks`.
+
+## Vorschläge
+
+Analysen erzeugen höchstens drei strukturierte Vorschläge. Ziel-IDs verbinden Vorschläge mit Übungen, Progressionen und Stufen. Die App darf Status ändern und zum Ziel navigieren, aber niemals automatisch den Plan mutieren.