129 lines
4.9 KiB
Markdown
129 lines
4.9 KiB
Markdown
|
# 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)
|