shinkan-jinkendo/docs/jinkendo-family/design-principles/EXERCISE_CATALOG_DESIGN_PRINCIPLES.md

Exercise Catalog – Designprinzipien (Extraktion)

Status: Analyse / Arbeitspapier
Stand: 2026-07-04
Geltungsbereich: Modul „Exercise Catalog“ — Kernobjekt Übung, Varianten, Graphen, Kombination

Serie: Designprinzipien für Produktfamilie · Shinkan Dokument 7 von 15
Mitai-Vergleich: — (domänenspezifisch)

Kernkomponenten:

Bereich	Pfade
API	backend/routers/exercises.py, exercise_progression_graphs.py
Rich-Text	backend/exercise_rich_text.py
KI	backend/exercise_ai.py
Frontend	frontend/src/pages/Exercises*.jsx, Tab-Formular
Specs	EXERCISES_ARCHITECTURE.md, EXERCISES_API_SPEC.md, Kombinations-Spec

---

Modul

Exercise Catalog

Shinkans Kernobjekt: Übungen mit mehrdimensionaler Einordnung (Skills, Fokus, Stile), Varianten, Progressionsgraphen, Kombinationsübungen (method_archetype, Stationen), Governance und Medien-Anbindung.

---

Designprinzipien

1. Übung als zentrales Aggregate Root

Prinzip	Varianten, Medien, Skills, Graph-Knoten hängen an exercises.id — Owner/Governance auf Eltern-Übung.
Begründung	Eine Freigabe- und Lösch-Semantik; Varianten ohne eigenen Owner.
Quelle	FACHLICHE_NUTZERFUNKTIONEN.md §4.1, §4.7
Tragfähigkeit	hoch
Einschränkung	Große Monolith-Router/Seiten — Refaktor-Roadmap.

2. Tab-Formular statt Scroll-Monolith

Prinzip	Register: Stammdaten · Anleitung · Einordnung · Kombination · Varianten · Medien — Varianten/Medien erst nach erstem Save.
Begründung	UX für komplexe Objekte; klare Abhängigkeiten (IDs für Medien/Varianten).
Quelle	Nutzerfunktionen §4.1
Tragfähigkeit	hoch (UI-Muster)
Einschränkung	Frontend-God-Page-Schuld dokumentiert.

3. Mehrdimensionale Filter-SSoT

Prinzip	Suche/Filter über Skills, Fokus, Stil, Zielgruppe, Status, Freigabelevel — Backend-Query + gespeicherte Präferenzen.
Begründung	Trainer finden Inhalte in großen Vereins-Katalogen.
Quelle	SEARCH_FILTER_SPEC.md; exercises.py
Tragfähigkeit	hoch
Einschränkung	Performance schwere Listen — Baseline/Roadmap.

4. Varianten mit Voraussetzungskette

Prinzip	exercise_variants mit Reihenfolge, optional prerequisite_variant_id.
Begründung	Didaktische Abstufung innerhalb einer Übung.
Quelle	Migration 030; Planung nutzt Varianten-ID pro Eintrag
Tragfähigkeit	hoch
Einschränkung	—

5. Progressionsgraph als gerichtete Übungs-Beziehungen

Prinzip	Knoten = Übungen/Varianten; Kanten = „weiter“-Beziehungen; eigener Router + UI in Übungswelt.
Begründung	Didaktik und Planungs-KI nutzen denselben Graph.
Quelle	exercise_progression_graphs.py; PLANNING_PROGRESSION_GRAPH_KI.md
Tragfähigkeit	hoch
Einschränkung	Graph-Editor-Komplexität; KI-Artefakte separat.

6. Kombinationsübungen als Sonderform im gleichen Katalog

Prinzip	exercise_type=combination mit Stationen, method_archetype, optionalem method_profile.
Begründung	In Planung wie normale Übung; Coach zeigt Stations-Layer.
Quelle	Migration 056/057; Kombinations-Spec V2
Tragfähigkeit	mittel
Einschränkung	Archetyp-Stufen B/C noch ausbaubar.

7. Governance integriert (nicht separates CMS)

Prinzip	visibility, status (draft/review/…), Access-Layer-Lösch/Transition-Regeln.
Begründung	Trainer-Workflow ohne externes Freigabe-Tool.
Quelle	club_tenancy.py; Content Change Requests → Posteingang
Tragfähigkeit	hoch
Einschränkung	Formales Review-Workflow noch leichtgewichtig.

8. Rich-Text-Felder mit Inline-Medien

Prinzip	Einheitliche Platzhalter/Render für summary, goal, execution, …
Begründung	Medienreicher Inhalt ohne iframe-Split.
Quelle	exercise_rich_text.py
Tragfähigkeit	hoch
Einschränkung	—

---

Nicht übernehmen

1. Varianten mit eigenem Owner/Freigabe — widerspricht Domänenmodell.
2. Übungsliste ohne Tenant-Filter — Access-Layer-Pflicht.
3. KI-generierte Übungen ohne Governance-Felder — immer draft/private Default.
4. Progressionsgraph-Logik im Frontend allein — Server validiert Kanten.

---

Verwandte Dokumentation

• EXERCISES_ARCHITECTURE.md
• MEDIA_ASSETS_DESIGN_PRINCIPLES.md
• SKILL_SCORING_DESIGN_PRINCIPLES.md
• DESIGN_PRINCIPLES_INDEX.md