# 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](../../../.claude/docs/technical/EXERCISES_ARCHITECTURE.md)
- [MEDIA_ASSETS_DESIGN_PRINCIPLES.md](./MEDIA_ASSETS_DESIGN_PRINCIPLES.md)
- [SKILL_SCORING_DESIGN_PRINCIPLES.md](./SKILL_SCORING_DESIGN_PRINCIPLES.md)
- [DESIGN_PRINCIPLES_INDEX.md](./DESIGN_PRINCIPLES_INDEX.md)