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

Trainingsmodule und Kombinationsübungen — Spezifikation (Entwurf)

Status: Entwurf zur fachlichen und technischen Abstimmung · Stand: 2026-05-12 (Code 0.8.110, siehe backend/version.py)
Zweck: Rahmen für Umsetzung, Integration in Planung/Rahmenprogramm und Durchführung im assistierten Training (Coaching-Modus). Dieses Dokument ist nicht implementierungsbindend, bis die markierten offenen Entscheidungen geschlossen und der Status angehoben wurde.

Abgleich mit Code (Drift vermeiden):

• Kanonische Archetyp-IDs: fest in backend/routers/exercises.py (COMBINATION_ARCHETYPE_IDS); fachliche Tabelle und UI-Labels in frontend/src/constants/combinationArchetypes.js — die fachliche Master-Zuordnung Name↔ID steht in functional/Shinkan Trainingsmodule Kombinationsuebungen Spezifikation V2.md § 10.2.1. Administrierbare Archetypen (DB/UI) gibt es nicht; Erweiterungen nur per Code-Release — Fachspez § 10.6.
• Planungs-Override: planning_method_profile (Migration 057) speichert einen Snapshot; Merge mit Katalogprofil erfolgt im Frontend (frontend/src/utils/comboPlanningMethodProfile.js — effectiveComboMethodProfile), nicht als serverseitiger Join. Payload-Sanitisierung vor PUT; Backend speichert JSONB zuverlässig (Json()).
• Coaching: Stufe A — Slots, Kandidaten, Archetyp-Hilfstext, Label für globale Eckdaten (describeGlobalComboProfile in combinationMethodProfileUi.js), visuelle Klammer (CombinationPlanBracket) in Peek/Run; Stufen B/C (archetypgesteuerte Zeitleiste/Takt) offen — Fachspez § 10.4, § 10.6, Anhang A.
• Umsetzungsplan: working/TRAINING_MODULES_IMPLEMENTATION_PLAN.md (Phase 2/4 „teilweise“; Pakete 4e–4g für Admin, Vorbelegung, Validierung).

Verwandte Dokumente:

Dokument	Bezug
TRAINING_FRAMEWORK_SPEC.md	Rahmen-Bibliothek, Slot-Blueprint, Kopiersemantik (from-framework-slot)
functional/PARALLEL_TRAINING_STREAMS_CONCEPT.md, technical/PARALLEL_TRAINING_STREAMS_SPEC.md	Parallele Teilstrecken innerhalb einer Einheit; Kombi-Übungen weiter nutzbar pro Stream für Stationsrotation
DATABASE_SCHEMA.md	Aktueller Stand training_units, Sektionen, Items
functional/DOMAIN_MODEL.md	Domänenbegriffe (bei Bedarf zu erweitern)
EXERCISES_* (Katalog)	Einzelübungen, Varianten
ACCESS_LAYER_AND_GOVERNANCE_PLAN.md	Sichtbarkeit, Mandant, Rollen bei neuen Bibliotheks-Entitäten

---

1. Zielbild und Abgrenzung

1.1 Problem

Die Trainingsplanung unterstützt Einheiten mit Sektionen und einzelnen Übungen (inkl. Notizen) sowie Rahmenprogramme mit Blueprint-Einheiten pro Slot. Es fehlen:

• Wiederverwendbare Übungsfolgen („Trainingsmodule“), die sich wie Bausteine in eine Einheit einfügen lassen (ganze Sektion oder Block innerhalb einer Sektion), inkl. kopierbasierter Integration analog zum Rahmen.
• Strukturierte Kombinationsformen (z. B. Zirkel mit Stationstausch, Parcour), bei denen mehrere Einzelübungen Slots oder Rollen einnehmen und die Trainingsmethode den Ablauf (Rotation, parallele Stationen, Zeitmodell) bestimmt.
• Ein durchgängiges Konzept für den Coaching- bzw. Assistenzmodus, in dem derselbe Plan je nach Archetyp unterschiedlich gesteuert wird (Beispiel Zirkel: Erklärphase vs. parallele Nutzung aller Stationen).

1.2 Nicht-Ziele (für erste Ausbaustufe)

• Individuelles Athleten-Tracking oder Leistungsmessung pro Person (außerhalb Shinkan-MVP, siehe Produktabgrenzung).
• Automatische Synchronisation zwischen Bibliotheksexemplar und bereits geplanten historischen Einheiten (bewusst: Kopie statt Live-Spiegel, konsistent mit Rahmen-Konzept).

1.3 Zwei Bausteine (fachliche Trennung)

Baustein	Kurzname	Einordnung	Kurzbeschreibung
Typ 1	Kombinationsübung	Übungskatalog (Sonderform einer Übung)	Eine logische Übung mit 1–n Slots; Slots können einzelne Übungen oder Pools auswählbarer Übungen tragen; Methodenprofil / Archetyp steuert später den Durchlauf.
Typ 2	Trainingsmodul	Planung / Bibliothek	Gespeicherte, wiederverwendbare Sequenz von Elementen (Einzelübungen, optional Kombinationsübungen, Notizen); Einbindung per Kopie in konkrete training_units oder in Rahmen-Slot-Blueprints.

Abgrenzung Rahmenprogramm: Das Rahmenprogramm strukturiert mehrere Einheiten (Slots) auf Programm-Ebene. Ein Trainingsmodul strukturiert typischerweise Inhalt einer Einheit oder eines Teils davon, nicht den Wochen-/Periodenrahmen.

---

2. Begriffe

Begriff	Definition
Bibliotheksexemplar	Gespeicherte Vorlage (Modul oder Kombinationsübung-Definition) mit Governance (z. B. global, Verein, privat).
Instanz in der Planung	In training_unit_section_items (und ggf. ergänzende Tabellen) materialisierter Ablauf für einen konkreten Termin bzw. eine geplante Einheit.
Slot (Typ 1)	Position innerhalb einer Kombinationsübung; kann genau eine gewählte Übung oder einen Pool (mehrere Kandidaten) referenzieren.
Methodenprofil / Archetyp	Maschinenlesbare Semantik wie trainiert wird (Zeit, Rotation, Parallelität), ergänzend zum bestehenden Katalog training_methods (Beschreibung was für eine Didaktik/Kondition gilt).
Coaching-Modus	UI- und Zustandslogik zur Durchführung einer geplanten Einheit (Timer, Phasen, Stationen).

---

3. Trainingsmethoden und Archetypen (Typ 1)

3.1 Bestehende Basis

Der Katalog training_methods (Migration 003) enthält u. a. Zirkeltraining (category u. a. zirkel, kondition). Er beschreibt die Methode inhaltlich, nicht aber Parameter wie Wechselintervalle oder parallele vs. rotierende Nutzung.

3.2 Erweiterung: Archetyp

Jede Kombinationsübung (und optional der Methodendatensatz als Default) erhält ein Feld method_archetype (Enum/Wertliste). Der Archetyp legt fest, welche Parameter am Methodenprofil relevant sind und wie der Coaching-Modus den Ablauf interpretiert.

Vorschlagsliste (erweiterbar, zu verbindlich machen):

Archetyp-ID (Vorschlag)	Beschreibung Planungslogik	Coaching (Intent)
circuit_rotate_time	n Stationen; Wechsel nach Ablaufzeit, optional globale Rundenanzahl	Rotierender oder gemeinsamer Takt; Umlauf zur nächsten Station
circuit_all_parallel	n Stationen; kein Umlauf als fachlicher Kern, alle Stationen gleichzeitig aktiv	Erklärphase (alle Inhalte vorher), dann parallel alle Stationen
sequence_linear	feste Reihenfolge; Aufbau, keine Kreisrotation	Schrittliste / Timer optional pro Schritt
station_parcour	Stationsbezogener Pfad, Reihenfolge kann variieren	Navigation / Abhaken eher als ein globaler Umlauf-Takt
pair_superset	zwei (oder wenige) Blöcke im Wechsel	Partnerlogik, gekoppelte Timer
time_domain_interval	AMRAP/EMOM-ähnliche Zeitdomäne	Globale Uhr, Runden-/Intervallzähler

3.3 Parameter des Methodenprofils

Zu präzisieren (JSON-Dokument vs. normalisierte Spalten):

• Zeit: work_seconds, rest_seconds, transition_seconds, rounds
• Organisation: station_count, rotation_direction, Flags explain_all_before_start, stations_operate_simultaneously
• ggf. intensity_profile (skalar oder Enum), nur wenn für MVP nötig

Offen: Welche Parameter sind Pflicht pro Archetyp (Validierung).

---

4. Datenmodell (Zielarchitektur, Entwurf)

4.1 Typ 2 — Trainingsmodule

Entwurfstabellen (Namen können bei Implementierung angeglichen werden):

• training_modules — Kopf: Titel, Beschreibung, Metadaten, visibility, club_id, created_by, Timestamps
• optional training_module_sections — falls ein Modul mehrere semantische Blöcke abbilden soll
• training_module_items — Reihenfolge, Verweis auf:
  • Einzelübung (exercise_id, exercise_variant_id)
  • Kombinationsübung (combination_exercise_id / exercise_id mit kind=combination)
  • Freitext-Notiz (analog note bei Einheiten)

Semantik: Bibliotheksbaum, keine Bindung an Kalender oder Gruppe.

4.2 Typ 1 — Kombinationsübungen

Option A (Embedding in exercises): Spalte exercise_kind = simple | combination und Kindtabellen für Slots/Pools.

Option B (Separate Kopf-Tabelle): 1:1-Beziehung zwischen exercises und combination_exercises.

Slot-Pools: mindestens M:N Pool-Kandidat pro Slot; die konkret geplante Auswahl gehört zur Instanz (geplante Einheit), nicht zwingend zum Bibliotheksexemplar.

4.3 Integration in geplante Einheiten

Heute: training_unit_section_items mit item_type in (exercise, note).

Erweiterungsoptionen (Entscheidung offen):

1. Expansion beim Einfügen: Modul wird in Items „aufgeklappt“; optional source_module_id an Items für Herkunft (Lineage-Light).
2. Block-Item: neuer item_type module_reference oder combination mit ID und eingebetteter Bearbeitungssemantik (komplexer, aber „Modul als Einheit“ editierbar).

Empfehlung zur Abstimmung: MVP oft mit Expansion + optionaler Markierung; später Block-Knoten.

Rahmenprogramm: Blueprint-training_units pro Slot nutzen dieselbe Sektions-/Item-Struktur — Module müssen dort ebenfalls einfügbar sein, wenn Rahmen und konkrete Planung konsistent bleiben sollen.

---

5. API (Skizze)

Verbindliche Pfade und Payloads folgen nach Freigabe dieses Dokuments.

Richtung	Beispielpfad / Funktion	Zweck
CRUD	GET/POST/PUT/DELETE …/training-modules	Bibliothek Trainingsmodule
Anwendung	POST …/training-units/{id}/apply-module	Modulinhalt in Sektion kopieren (tiefe Kopie)
Übungen	Erweiterung GET/POST/PUT …/exercises oder Unterressource …/exercises/{id}/combination	Kombinationsübung inkl. Slots
optional	POST …/training-units/from-module	Neue Einheit aus Modul (falls produktrelevant)

AuthZ: analog andere Bibliotheks- und Planungsobjekte; Abgleich mit ACCESS_LAYER_AND_GOVERNANCE_PLAN.md und Endpoint-Audit.

---

6. Frontend

• Bibliothek: Verwaltung Trainingsmodule (Liste, Editor, Sortierung, Vorschau).
• Übungsbereich: Editor für Kombinationsübungen (Slots, Pools, Methodenprofil/Archetyp).
• Planungs-UI: Aktion „Modul einfügen“, Ziel-Sektion und Position; Hinweis Kopie und Editierbarkeit pro Termin.

---

7. Coaching- / Assistenzmodus (Durchlauf)

7.1 Phasenmodell (konzeptionell)

• Briefing / Erklärung: insbesondere für circuit_all_parallel und Varianten mit explain_all_before_start
• Arbeitsphase(n): timer- und stationsgetrieben
• Übergänge: Pausen, Wechsel, Rundenzähler

7.2 Persistenz während Durchführung

Offen: Ob ein training_session_run (Snapshot der aufgelösten Einheit zum Startzeitpunkt) für Nachvollziehbarkeit und Offline-Fähigkeit nötig ist.

7.3 Ausbaustufen

1. Read-only Durchführungsansicht (Archetyp + Zeiten, keine komplexe State Machine)
2. Aktiver Modus mit State Machine und Archetyp-spezifischer UI
3. Optional: Offline/PWA-Verhalten

---

8. Umsetzungsphasen (Vorschlag)

Phase	Inhalt
A	Dieses Dokument verbindlich machen; Archetypen und Parameter final; Governance-Regeln
B	Typ 2: training_modules + API + „Modul in Einheit einfügen“ (Expansion)
C	Typ 1: Kombinationsübung im Katalog + Slots/Pools + Methodenprofil
D	Einbindung in Rahmen-Slot-Blueprints (Editor-Flow)
E	Coaching-Modus gemäß Archetyp

---

9. Offene Entscheidungen (Checkliste)

• Modul-Einfügung: nur Expansion vs. Block-Knoten vs. beides
• Normalisierung vs. JSON für Methodenprofil-Parameter
• Globale vs. vereinsbezogene vs. private Trainingsmodule (Governance-Matrix)
• Pflichtbinding: muss jede Kombinationsübung einen Default-Archetyp aus training_methods erben dürfen?
• Coaching: Mindestumfang MVP (nur Ansicht vs. interaktive Timer)
• Verweise in DOMAIN_MODEL.md und DATABASE_SCHEMA.md nach Implementierung pflegen

---

10. Changelog

Datum	Änderung
2026-05-12	Erstversion (Entwurf) angelegt