shinkan-jinkendo/.claude/docs/technical/TRAINING_FRAMEWORK_SPEC.md

Trainingsrahmenprogramm — Technische Spezifikation

Status: Zwischenstand dokumentiert · Stand: 2026-04-30
Bindendes Fachkonzept / Entscheide: .claude/docs/functional/TRAINING_CURRICULUM_AND_GOVERNANCE_CONCEPT.md (CURR‑001 bis CURR‑013)

Relevant für nächsten Schritt: CURR‑002 (2) Trainingsplanung / Rahmen über mehrere Einheiten — der hier dokumentierte Progressionsgraph Stufe 1 ist bewusst unterstützend, keine Pflicht für Slot-Zuordnungen (CURR‑013).

---

1. Abgrenzung zu anderen Dokumenten

Dokument	Rolle · warum nicht hier hineinmischen
EXERCISES_DATABASE_FINAL.md, EXERCISES_ARCHITECTURE.md, EXERCISES_API_SPEC.md	Übungskatalog inkl. Varianten-Progression innerhalb einer Übung (Migration 014). Kanten zwischen Übungen siehe §3.
DATABASE_SCHEMA.md	Nachgeordnete Übersicht: Migrationshistorie und Tabellenliste; Detail-DDL primär hier §3 + SQL unter backend/migrations/.
functional/DOMAIN_MODEL.md	Fachliche Begriffe; Kurzverweis auf Progressionsgraph ergänzt.
TRAINING_CURRICULUM_AND_GOVERNANCE_CONCEPT.md	Was und warum (Modus A/B, Governance, CURR‑Tabelle).

Konsequenz: Diese Datei bleibt der technische Arbeitspool für Rahmenprogramm Stufe 1–2. Abschnitt §4 beschreibt explizit den aktuellen Produktfreigabe-Umfang und bekannte Lücken (damit Trainingsplanung weiter gebaut werden kann ohne falscher Erwartung an „Alternative‑Pakete“ in der UI).

---

2. Noch auszuarbeiten (Checkliste)

• Entität(en): eigene Bibliotheks-Entität für Mehr-Slot-Rahmen (training_framework_* o. Ä., siehe CURR‑009); Abgrenzung zu training_plan_templates (C5).
• Modus A vs. B: ein Typ mit nullable group_id / plan_mode vs. zwei Objekttypen — offen (Funktionskonzept §6).
• Zielliste: ≥1 Zieleinträge pro Rahmen (CURR‑011); Felder und Optionalität.
• Slots: Reihenfolge, Notizen, direkte Übungszuordnungen (M:N oder Join-Tabelle); optionales training_plan_template_id pro Slot (CURR‑010, MVP offen).
• Progressionsgraph zwischen Übungen: persistiert, siehe §3–§4 (CURR‑002 (1), CURR‑013).
• Instanziierung (Modus B): FK/Metadaten zu training_units, Bulk vs. Verknüpfen (CURR‑012).
• Governance: training_plan_templates ohne visibility (CURR‑007, CURR‑008); neue Bibliothekstypen nach CURR‑005.
• REST gesamt Rahmenprogramm: Progressions-API ist umgesetzt; Rahmen‑Slot‑REST noch ausstehend.

---

3. Progressionsgraph Übung → Übung (implementierter Stand)

3.1 Abgrenzung

• Zwischen Übungen: gerichtete Kanten auf Ebene exercises mit optionalen Endpunkten auf konkreten exercise_variants (Knoten = „Übung“ oder „Übung · Variante“). Migrationen 032–034.
• Innerhalb einer Übung: Reihenfolge / Progressionsmetadaten der Varianten unverändert über exercise_variants (Migration 014) — nicht duplizieren.

AuthZ analog training_plan_templates: Graph nur für Admin/Superadmin oder Ersteller (created_by); Anlegen neuer Graphen mit _has_planning_role.

3.2 Migrationen & Schema (Kurz)

Mig.	Inhalt
032	exercise_progression_graphs (Name, Beschreibung, visibility, club_id, created_by); exercise_progression_edges (graph_id, von/nach Übung, edge_type VARCHAR Default next_exercise). FK CASCADE zu Graph und Übungen.
033	exercise_progression_edges.notes (freier Text / „Entwicklungsziel“ pro Kante).
034	from_exercise_variant_id, to_exercise_variant_id (nullable, FK exercise_variants, CASCADE). CHECK: gleiche Übung nur mit zwei verschiedenen Varianten. UNIQUE-Index über Graph + Endpunkte inkl. COALESCE(variant_id,0) + edge_type.

Kantentypen in Produktnutzung: next_exercise (Nachfolger), sibling (Schwester / gleiche „Entwicklungslage“, semantisch oft Paar — weiterhin eine gerichtete Kante in DB).

Listenqueries liefern Join‑Felder from_exercise_title, to_exercise_title, from_variant_name, to_variant_name.

3.3 REST (/api, Router exercise_progression_graphs.py)

Methode	Pfad	Zweck
GET	/exercise-progression-graphs	Liste (+ edges_count); Admin sieht alle, sonst nur eigene.
GET	/exercise-progression-graphs/{id}	Detail; ?include_edges=true
POST	/exercise-progression-graphs	Graph anlegen
PUT	/exercise-progression-graphs/{id}	Metadaten
DELETE	/exercise-progression-graphs/{id}	Graph + Kanten
GET	/exercise-progression-graphs/{id}/edges	Kanten; Query optional from_exercise_id, to_exercise_id
POST	/exercise-progression-graphs/{id}/edges	Einzelkante; Duplikat/Constraint → 409
POST	/exercise-progression-graphs/{id}/edges/sequence	Bulk: { steps: [{ exercise_id, variant_id? }, …], segment_notes?: [...] } — nur next_exercise, Transaktion alle oder keine Zeile
PUT	/exercise-progression-graphs/{id}/edges/{edge_id}	z. B. notes
DELETE	/exercise-progression-graphs/{id}/edges/{edge_id}	eine Kante
POST	/exercise-progression-graphs/{id}/edges/delete-batch	{ edge_ids: [...] } — z. B. gesamte sichtbare „Reihe“ löschen

3.4 Frontend (Stand Code)

• ExercisesListPage: Tabs Liste · Progressionsgraphen → ExerciseProgressionGraphPanel.
• ExerciseFormPage (nur Edit): eingeklappter Block Progressionsgraph mit Kontext „diese Übung“ + Filter „nur betroffene Kanten“.
• Panel‑Funktionen: Sequenz‑Editor (mehrere Schritte → ein Bulk‑Speichern), zusammengefasste Reihen‑Lesart für next_exercise, eigene Liste für Schwestern, Einzelkantenbereich, Tab Alle Kanten (Tabelle).
• API‑Client: frontend/src/utils/api.js (createExerciseProgressionSequence, deleteExerciseProgressionEdgesBatch, …).

---

4. Zwischenstand für Produkt / Trainingsplanung (bewusste Grenzen)

Freigabe: Der beschriebene Stand gilt als ausreichend, um mit dem Trainingsplanungsmodul und später Rahmen/Slots (CURR‑002 (2)) weiterzuarbeiten — ohne dass Pflicht zur Pflege komplexer Graph‑Strukturen entsteht (CURR‑013).

Was gut nutzbar ist

• Lineare Reihen mehrerer Übungen (bzw. Varianten‑Knoten) über Sequenz‑API bzw. Sequenz‑UI.
• Nachfolger‑Lesart als zusammenhängende Kette in der Übersicht.
• Schwester‑Kanten als eigene Liste (Alternative gleicher „Stufe“ zwischen zwei Knoten).
• Einzelkanten für Sonderfälle und Verzweigungen.

Was noch nicht „ein Knopf“ ist (bekannt)

• Parallele gleichwertige Alternativen („Paket B bestehend aus mehreren Übungen als echte Alternative zu Paket A“) sind nicht als erste‑Klass‑UX modelliert: mehrere Nachfolger aus einem Knoten sind technisch möglich (mehrere next_exercise‑Kanten), aber keine dedizierte Gruppe „Alternativ‑Set“. Pflege kann mehrzeilig und koplastisch wirken.
• Visualisierung echter Bäume (Join‑Points, mehrere ausgehende Pfeile in einem Bild) ist nur eingeschränkt über Reihen‑Zusammenfassung + Tabelle abbildbar.

Nächste sinnvolle Ausbaustufen (Backlog Graph‑UX, nicht Blocker Planung)

• Semantik alternative_group_id oder Hyperkanten (ein UX‑Schritt legt mehrere Kanten mit gemeinsamer Gruppe an).
• Komfort beim Pflegen symmetrischer Schwestern (ein Klick für zwei Richtungen / Dedupe).
• Karten-/Baum‑Layout statt nur Zeilen.

Details weiterhin Diskussionsgrundlage in TRAINING_CURRICULUM_AND_GOVERNANCE_CONCEPT.md §6 (Kantentypen).

---

5. Changelog (Dokument)

Datum	Änderung
2026-04-30	Zwischen-Doku: §3 auf Migrationen 032–034 + API sequence/delete-batch + Frontend erweitert; §4 Produktfreigabe vs. Lücken (parallele Alternativen); Changelog §5.
2026-04-30	§3: erste Fassung Migration 032 + REST‑Basis (CURR‑002 (1)).
2026-04-28	Erstanlage Stub mit Checkliste.