shinkan-jinkendo/.claude/docs/functional/DOMAIN_MODEL.md

# Shinkan Jinkendo - Fachliches Domänenmodell

**Version:** 0.4.6  
**Stand:** 2026-05-14 (Fachlicher Nutzerüberblick: `docs/FACHLICHE_NUTZERFUNKTIONEN.md`)  
**Basis:** `shinkan_anforderungsdokument_entwurf.md` + Fähigkeitsmatrix

---

## Übersicht

Dieses Dokument beschreibt die **fachliche Datenstruktur** von Shinkan Jinkendo.

**Zuständig für technische Umsetzung:** siehe `DATABASE_SCHEMA.md`

---

## Fachliche Kernprinzipien

### 1. Globaler Fähigkeitskatalog (§8.3)

**Prinzip:** Fähigkeiten werden NICHT pro Modell dupliziert.

**Beispiele:**
- Distanzgefühl (in Karate UND Selbstverteidigung)
- Stabiler Stand (in Karate UND Gewaltschutz)
- Aufmerksamkeit (in verschiedenen Zielgruppenmodellen)

**Konsequenz:** Ein globaler Katalog, aber kontextabhängige Ausprägung über Reifegradmodelle.

**🆕 Hierarchische Struktur (ab Migration 022):**
```
Haupt-Kategorie (KARATE / ALLGEMEINE)
  └─ Unter-Kategorie (Kihon, Kumite, Kondition, etc.)
      └─ Fähigkeit
          └─ Level-Definitionen (1-5)
```

**🆕 Fokusbereich-Zuordnung (ab Migration 022):**
- **Karate-spezifisch** (`focus_areas: ["karate"]`)
  - Beispiele: Kata Ablauf, Kihon, Bunkai, Dachi Waza
  - Nur relevant für Karate-Training
  
- **Universal** (`focus_areas: ["universal"]`)
  - Beispiele: Maximalkraft, Konzentration, Deeskalation, Flexibilität
  - Relevant für ALLE Trainingsbereiche (Karate, Selbstverteidigung, Gewaltschutz)

**Später möglich:** Mehrfachzuordnung
- `["karate", "selbstverteidigung"]` - Fähigkeit in beiden Bereichen relevant
- `["karate", "gewaltschutz"]` - etc.

### 2. Mehrfachzuordnung von Übungen (§10.7)

**Prinzip:** Eine Übung kann mehreren Bereichen GLEICHZEITIG zugeordnet sein.

**Beispiel:** Distanzübung
- Karate ✓
- Selbstverteidigung ✓  
- Gewaltschutz ✓

**Technische Umsetzung:** M:N-Beziehungen mit optionalem `is_primary`-Flag bei **Fokusbereichen, Stilrichtungen, Trainingsstilen und Zielgruppen** — nicht bei `exercise_skills` (dort nur Intensität `niedrig|mittel|hoch`).

### 3. Hierarchischer Kontext (§8.1)

**Fachliche Grundstruktur (ab Migration 009 - M:N):**
```
Fokusbereich (Sportart/Bereich)
  └─ Stil
      └─ Zielgruppen (M:N Zuordnung, wiederverwendbar)
```

**🔄 ÄNDERUNG:** Zielgruppen sind global und können mehreren Stilen zugeordnet sein!

**Beispiel-Architektur (vereinfacht):**
```
Global definierte Zielgruppen:
├─ Breitensportler
├─ Leistungssportler
├─ Kinder
├─ Erwachsene
└─ Senioren

Zuordnungen (M:N):
Karate → Shotokan → [Breitensportler, Leistungssportler, Kinder]
Karate → Goju-Ryu → [Breitensportler, Erwachsene]
Karate → Wado-Ryu → [Leistungssportler]

Selbstverteidigung → [Erwachsene, Kinder, Senioren]
Gewaltschutz → [Kinder, Senioren]
```

**Admin-UI Darstellung:**
- **Tree-View (Tab "Hierarchie"):** Zeigt Fokusbereich → Stil → zugeordnete Zielgruppen
- **Matrix (Tab "Zuordnungen"):** Checkbox-Matrix: Stile × Zielgruppen
- **Global (Tab "Zielgruppen"):** Verwaltung aller Zielgruppen unabhängig von Stilen

**Bedeutung für Reifegradmodelle:**

Jede Kombination (Fokusbereich + Stil + Zielgruppe) kann ein eigenes Reifegradmodell haben:
- Karate / Shotokan / Breitensport → Modell A
- Karate / Shotokan / Leistungssport → Modell B
- Selbstverteidigung / Erwachsene → Modell C

---

## Fachliche Dimensionen

### Dimension 1: Fokusbereich (Sportart/Bereich)

**Definition:** Oberste fachliche Kategorisierung der Trainingsinhalte.

**Beispiele:**
- Karate
- Selbstverteidigung
- Gewaltschutz

**Eigenschaften:**
- Name, Kürzel, Beschreibung
- Farbe (für UI)
- Icon (Emoji oder Icon-Name)
- Status (aktiv/archiviert)

**Verwaltung:**
- Admin-Level: Systemadmin, Vereinsadmin
- CRUD: Voll administrierbar
- Löschen: Nur wenn keine abhängigen Stile oder Übungen

### Dimension 2: Trainingsstil

**Definition:** Spezialisierung innerhalb eines Fokusbereichs.

**Beispiele:**
- Shotokan (unter Karate)
- Goju-Ryu (unter Karate)
- Wado-Ryu (unter Karate)

**Hierarchie:**
- Gehört zu genau EINEM Fokusbereich
- Kann optional Sub-Stile haben (parent_style_id)

**Eigenschaften:**
- Name, Kürzel, Beschreibung
- Fokusbereich-Zuordnung
- Optionale Hierarchie (z.B. Kyokushin → Kyokushin IKO)
- Status

**Verwaltung:**
- Admin-Level: Systemadmin, Vereinsadmin
- CRUD: Voll administrierbar
- Verschieben: Zwischen Fokusbereichen möglich
- Löschen: Nur wenn keine Zielgruppen oder Übungen zugeordnet

### Dimension 3: Zielgruppe

**Definition:** Globale Trainingsempfänger-Gruppe, die MEHREREN Stilen zugeordnet werden kann (M:N).

**🔄 ÄNDERUNG ab Migration 009:** Zielgruppen sind NICHT mehr hierarchisch an Stile gebunden!

**Beispiele:**
- Breitensportler (kann in Shotokan, Goju-Ryu, Wado-Ryu gültig sein)
- Leistungssportler (kann in verschiedenen Stilen genutzt werden)
- Kinder (6-12 Jahre) (stilunabhängig)
- Jugendliche (13-17 Jahre)
- Erwachsene
- Frauen
- Senioren
- Gemischt

**Architektur (ab Migration 009):**
- ✅ **Global unabhängig:** Keine direkte FK zu `training_style_id`
- ✅ **M:N Zuordnung:** Über Junction-Tabelle `training_style_target_groups`
- ✅ **Wiederverwendbar:** Eine Zielgruppe kann mehreren Stilen zugeordnet sein
- ✅ **Primary Flag:** `is_primary` kennzeichnet Hauptzuordnung

**Eigenschaften:**
- Name, Beschreibung
- Optionale Altersangabe (min_age, max_age)
- Status
- **KEINE direkte Stil-Zuordnung mehr!**

**Verwaltung:**
- Admin-Level: Systemadmin, Vereinsadmin, Spartenadmin
- CRUD: Voll administrierbar (global)
- Zuordnungen: Über M:N Matrix im Admin-UI
- Löschen: Nur wenn keine Übungen UND keine Stil-Zuordnungen

**Admin-UI:**
- Tab "Zielgruppen": Global verwalten (ohne Stil-Dropdown)
- Tab "Hierarchie": Tree-View (Fokusbereich → Stil → zugeordnete Zielgruppen)
- Tab "Zuordnungen": Checkbox-Matrix für M:N Assignments

### Dimension 4: Altersgruppen (separate Dimension!)

**Definition:** Grobe Alterseinstufung UNABHÄNGIG von Zielgruppe.

**Katalog:**
- Minis (3-5 Jahre)
- Kinder (6-9 Jahre)
- Schüler (10-12 Jahre)
- Teenager (13-17 Jahre)
- Erwachsene (18+)

**Abgrenzung zu Zielgruppe:**
- Altersgruppe = didaktische Einstufung
- Zielgruppe = fachlicher Kontext

**Beispiel:**
- Übung kann für "Kinder" + "Schüler" geeignet sein (Altersgruppen)
- Und gleichzeitig zu Zielgruppe "Karate Breitensport Kinder" gehören

---

## Fähigkeiten-Domäne (§8.3, erweitert ab Migration 022+023)

### Fähigkeiten-Hierarchie

**🆕 3-Ebenen-Struktur (ab Migration 022):**

```
Haupt-Kategorie (2 Stück)
├─ KARATE Fähigkeiten
│   ├─ Kihon (Unterkategorie)
│   │   ├─ Dachi Waza (Fähigkeit, Level 1-5)
│   │   ├─ Uke Waza
│   │   └─ ...
│   ├─ Kumite
│   ├─ Kata
│   └─ Selbstverteidigung
│
└─ ALLGEMEINE sportliche Fähigkeiten
    ├─ Koordination (Unterkategorie)
    │   ├─ Orientierung (Fähigkeit, Level 1-5)
    │   └─ ...
    ├─ Kondition
    ├─ Kognition
    ├─ Soziale Fähigkeiten
    └─ Psychische Fähigkeiten
```

### Haupt-Kategorien

**1. KARATE Fähigkeiten** (`focus_areas: ["karate"]`)
- **Anzahl:** 32 Skills
- **Bedeutung:** Karate-spezifische Techniken und Fähigkeiten
- **Verwendung:** Nur für Karate-Training relevant
- **Unterkategorien:** Kihon, Kumite, Kata, Selbstverteidigung

**2. ALLGEMEINE sportliche Fähigkeiten** (`focus_areas: ["universal"]`)
- **Anzahl:** 37 Skills
- **Bedeutung:** Universelle sportliche und mentale Fähigkeiten
- **Verwendung:** Für ALLE Trainingsbereiche einsetzbar
- **Unterkategorien:** Koordination, Kondition, Kognition, Soziale Fähigkeiten, Psychische Fähigkeiten

### Unterkategorien

#### KARATE Fähigkeiten

**Kihon (Grundtechniken) - 10 Skills:**
- Dachi Waza (Standtechniken)
- Uke Waza (Blocktechniken)
- Zuki Waza (Stoßtechniken)
- Uchi Waza (Schlagtechniken)
- Geri Waza (Tritttechniken)
- Nage Waza (Wurftechniken)
- Nukite Waza (Fingerstichtechniken)
- Ken Waza (Fausttechniken)
- Hüfteinsatz
- Kime (Fokussierung)

**Kumite (Kampf) - 10 Skills:**
- Beinarbeit
- Distanzkontrolle
- Angriff
- Abwehr Konter
- Präzision
- Antizipation
- Timing
- Taktik
- Fokus
- Mentale Stärke

**Kata (Formen) - 8 Skills:**
- Technik Kombination
- Kata Ablauf
- Bunkai (Anwendung)
- Oyo (Variation)
- Henka (Veränderung)
- Kakushi (Versteckte Techniken)
- Kata Atmung
- Kata Rhythmus

**Selbstverteidigung - 4 Skills:**
- Gefahrenbewustsein
- Selbstbehauptung
- Selbstschutz
- Gefahrenabwehr

#### ALLGEMEINE sportliche Fähigkeiten

**Koordination - 7 Skills:**
- Orientierung
- Differenzierung
- Kopplung
- Gleichgewicht
- Rhythmisierung
- Reaktion
- Umstellung

**Kondition - 15 Skills:**
- Kraftfähigkeiten: Maximalkraft, Schnellkraft, Reaktivkraft, Kraftausdauer, Muskelaufbau
- Schnelligkeitsfähigkeiten: Reaktionsschnelligkeit, Bewegungsschnelligkeit, Handlungsschnelligkeit, Schnelligkeitsausdauer
- Ausdauerfähigkeiten: Grundlagenausdauer, Aerobe Ausdauer, Anaerobe Ausdauer
- Regenerationsfähigkeiten: Regenerationsfähigkeit, Ermüdungswiderstandsfähigkeit
- Beweglichkeit: Flexibilität

**Kognition - 5 Skills:**
- Aufmerksamkeit
- Wahrnehmung
- Urteilsvermögen
- Merkfähigkeit
- Lernfähigkeit

**Psychische Fähigkeiten - 6 Skills:**
- Selbstvertrauen
- Konzentration
- Emotionale Kontrolle
- Motivation
- Stressresistenz
- Stressregulation

**Soziale Fähigkeiten - 4 Skills:**
- Deeskalation
- Selbstdisziplin
- Toleranz
- Fairness

### Level-Definitionen (Reifegradmodell)

**Konzept:** Jede Fähigkeit hat 5 Stufen mit konkreten Beschreibungen.

**Struktur (noch nicht vollständig implementiert):**
- **Level 1:** Einsteiger - Grundlegende Ausführung
- **Level 2:** Grundlagen - Kontrollierte Ausführung
- **Level 3:** Aufbau - Sichere Anwendung
- **Level 4:** Fortgeschritten - Variable Anwendung
- **Level 5:** Experte - Meisterhafte Beherrschung

**Beispiel (Dachi Waza - Standtechniken):**
- Level 1: Stabiler Stand mit Schwerpunkt und richtiger Ausrichtung
- Level 2: Korrekter Stand mit guter Balance in verschiedenen Positionen
- Level 3: Fließender Wechsel zwischen Ständen mit Kontrolle
- Level 4: Dynamische Stand-Variationen unter Belastung
- Level 5: Perfekte Stand-Technik in allen Kampfsituationen

**Datenbankstruktur:**
```sql
skill_level_definitions (
  skill_id,
  level (1-5),
  description (Text aus Fähigkeitsmatrix)
)
```

**Status:** Schema vorhanden (Migration 022), Daten noch nicht importiert (optional für spätere Phase).

---

## Übungs-Zuordnungslogik (§10)

### Primäre vs. Sekundäre Zuordnung

**Regel:** Eine Übung hat genau EINE primäre Zuordnung pro Dimension.

**Beispiel:**

**Übung:** "Maai - Distanzübung"

**Fokusbereiche:**
- Karate (primär) ✓
- Selbstverteidigung (sekundär)

**Stile:**
- Shotokan (primär) ✓
- Goju-Ryu (sekundär)
- Wado-Ryu (sekundär)

**Zielgruppen:**
- Breitensportler (primär) ✓
- Leistungssportler (sekundär)

**Altersgruppen:**
- Schüler ✓
- Teenager ✓
- Erwachsene ✓

### Fähigkeitsbezug (§10.8)

**Übung trainiert MEHRERE Fähigkeiten:**

**Beispiel:** "Kumite-Drill"

**Hauptfähigkeiten:**
- Distanzkontrolle (Kumite, target_level: 3, intensity: hoch)
- Timing (Kumite, target_level: 3, intensity: hoch)

**Nebenfähigkeiten:**
- Beinarbeit (Kumite, target_level: 2, intensity: mittel)
- Reaktion (Koordination, target_level: 2, intensity: mittel)

**Attribute pro Fähigkeitsbezug:**
- `intensity` — Nutzeneinschätzung: **niedrig | mittel | hoch** (Standard **mittel**)
- `required_level` / `target_level` — Stufen-Spanne (kanonische Slugs basis … optimierung)
- `is_primary` — Legacy-Feld; **nicht mehr in der UI**, beim Speichern immer false; Scoring ignoriert es

**🆕 Fokusbereich-Filterung:**
- Bei Übungen mit Fokusbereich "Karate" sollten primär KARATE-Fähigkeiten zugeordnet werden
- ALLGEMEINE Fähigkeiten können als Nebenfähigkeiten hinzugefügt werden
- Bei universellen Übungen (Selbstverteidigung, Gewaltschutz) bevorzugt ALLGEMEINE Fähigkeiten

### Trainingscharakter (§10.7)

**Katalog:**
- Grundlage (Einführung, Basisvermittlung)
- Aufbau (Aufbauendes Training)
- Vertiefung (Vertiefung, Spezialisierung)
- Festigung (Wiederholung, Festigung)
- Diagnose (Leistungsdiagnose, Test)
- Wettkampf (Wettkampfvorbereitung)

**Bedeutung:**
- Wichtig für Suche
- Wichtig für Trainingsplanung
- Wichtig für KI-Unterstützung (später)

---

## Variantenlogik (§11.2)

**Prinzip:** Übung besteht aus Stammübung + optionale Varianten.

**Beispiele für Varianten:**
- Leicht / Mittel / Schwer
- Mit Partner / Ohne Partner
- Mit Hilfsmittel / Ohne Hilfsmittel
- Kindgerechte Variante
- Kurzvariante
- Fortgeschrittene Variante

**Varianten-Attribute:**
- Titel/Name
- Kurzbeschreibung
- Abweichende Durchführung
- Abweichende Dauer
- Abweichende Hilfsmittel
- Abweichender Fähigkeitsfokus
- Abweichende Zielgruppen
- Eigener Medienbezug

**Umsetzung (Trainingsplanung):** Ein Eintrag in `training_unit_exercises` kann optional eine konkrete Varianten-ID (`exercise_variant_id`, Migration 030) tragen; Bindung wird gegen die gewählte Übung validiert. Varianten werden über die Übungs-API verwaltet (`technical/EXERCISES_API_SPEC.md`).

### Progressionsgraph zwischen Übungen (Zwischenstand, CURR‑002 Stufe 1)

**Abgrenzung:** Zusätzlich zur Varianten-Reihe **innerhalb** einer Übung gibt es optional einen **Bibliotheks-Progressionsgraphen**: gerichtete Kanten zwischen **Übungen** (Knoten optional auf konkrete **Varianten** eingegrenzt). Gemeinsamer Kontainer pro Graph (`exercise_progression_graphs`); Kanten mit Typ z. B. Nachfolger oder Schwester.

**Rolle:** **unterstützend** für Planung und spätere Rahmenprogramme — keine Pflicht, jeden Trainingsablauf als Graph zu modellieren (**CURR‑013**).

**Fachliche Grenze aktuell:** Mehrere gleichwertige „Pakete“ paralleler Alternativen sind **modellierbar** (mehrere ausgehende Kanten), aber noch **nicht** über eine dedizierte „Alternativgruppe“ in der UI trivial pflegbar; siehe `technical/TRAINING_FRAMEWORK_SPEC.md` §4.

**KI-Planung (Workbench, Stand 0.8.233):** Am Graph können Trainer neben Kanten ein **`planning_roadmap`**-Artefakt (Curriculum-Stufen) und **`planning_catalog_context`** (Primärfokus, Stilrichtung, Trainingsstil, Zielgruppe aus den Katalog-Dimensionen §1) pflegen. Die Roadmap-first-Pipeline matcht Übungen pro Stufe; Didaktik und Reihenfolge kommen aus Roadmap + QS, nicht aus Technik-Hardcoding. **Geplant (H1):** Katalog-Dimensionen zusätzlich als **Prompt-Snippets** in LLM-Aufrufen (Priorität Primärfokus → Trainingsstil → Zielgruppe → Stilrichtung) — **`docs/architecture/PLANNING_CATALOG_PROMPT_SNIPPETS.md`**. Technische Details: **`docs/architecture/PLANNING_PROGRESSION_GRAPH_KI.md`**. Für **Trainingsplanung** (Einheit, Abschnitt, Rahmen-Slot) gelten dieselben Katalog- und Retrieval-Bausteine mit anderen Scopes — Phase G, siehe Roadmap **`PLANNING_KI_ROADMAP.md`**.

### Trainingsrahmen‑Vorlage (Rahmenprogramm, CURR‑002 Stufe 2 / CURR‑009)

**Abgrenzung:** Eine **einzeilige** Trainingsplan‑Mikrovorlage (`training_plan_template`) strukturiert **eine** Einheit; das **Rahmenprogramm** ist eine **eigene Bibliotheksentität** mit **sortierten Session‑Slots**, **mindestens einem** formulierten **Entwicklungsziel** (Zielliste, **CURR‑011**) und einem **vollständigen Ablauf** pro Slot (**`training_unit_sections` + `training_unit_section_items`** wie bei geplanten Einheiten — **CURR‑010** inhaltlich, technisch seit **037** identisch zur Planungsstruktur). Der persistierte **Progressionsgraph** zwischen Übungen bleibt **optional** (**CURR‑013**).

**Bibliothek only (036):** Kein Kopf‑`plan_mode`/keine Kopf‑`group_id`; Zuordnung zu Gruppe und Datum erfolgt nur über **kopierte** Kalender‑`training_units` (Instanz).

**Konkretisierung (037/API):** `POST /api/training-units/from-framework-slot` legt eine geplante Einheit aus dem Slot‑Blueprint an; **`origin_framework_slot_id`** dient als Herkunftsreferenz (**Lineage light**; weiteres Feedback/Lineage‑Konzept: Konzeptpapier Schritt **E**).

### Trainingsmodul (Bibliothek)

**Abgrenzung:** Wiederverwendbare **Übungsfolge** (`training_modules` + `training_module_items`) — kein Kalendertermin, kein Rahmen-Slot. Übernahme in geplante Einheiten über Planung (`apply-training-module`).

**Governance:** wie andere Bibliotheksartefakte (`visibility`, `club_id`, `library_content_visibility_sql`).

### Gewichtetes Fähigkeiten-Profil (Planungs-Bausteine, Phase 3)

**Zweck:** Aus den verknüpften Übungen eines Planungsartefakts wird ein **Fähigkeiten-Profil** berechnet (Trainingsgewicht je Fähigkeit). Trainer vergleichen Bausteine **innerhalb desselben Typs**, um z. B. das passendste Modul für eine Ziel-Fähigkeit zu finden.

**Artefakttypen (getrennte Peer-Kontexte):**

| Typ | Vergleich |
|-----|-----------|
| `training_module` | nur sichtbare **Module** |
| `framework_program` | nur sichtbare **Rahmenprogramme** |
| `progression_graph` | nur sichtbare **Regressionspfade** |

**Metriken (Nutzer):**

- **Score / Gewicht** — absolut (Dauer × Häufigkeit × Intensität × Stufen-Spanne)
- **Prozent** — Anteil am stärksten sichtbaren Peer **desselben Typs** für diese Fähigkeit (max. 100 %)
- **★** — stärkster Peer in diesem Kontext

**UI:** Profile in Editoren; KPI-Kacheln und Filter in Listen (`/planning/framework-programs`, `/planning/training-modules`); Discovery auf der Fähigkeiten-Seite.

**Technik:** `backend/skill_scoring.py`, `routers/skill_profiles.py` — Spec **`technical/SKILL_SCORING_SPEC.md`**.

### Parallele Trainingsstreams (Breakout)

**Fachlich:** Eine Kalender‑**Einheit** kann aus **Phasen** bestehen — z. B. gemeinsamer Block, dann **beliebig viele parallele** „Teilstrecken“ (**Streams**) mit je eigenem Miniplan (Abschnitte/Übungen), erneut gemeinsamer Block. Das ist **nicht** dasselbe wie ein **Rahmenprogramm‑Slot** (Serien‑Session über Wochen): Slots strukturieren **mehrere Einheiten** in einem Programm; **Streams** strukturieren **gleichzeitige** Abläufe **innerhalb einer** Einheit.

**Sonderfall Stationen:** Rotation kann **innerhalb** einer Stream‑Planung über **Kombinationsübungen** (Methodenprofil/Archetyp) abgebildet werden; hallenweit **synchron** getaktete Rotation ist eine **erweiterte** Ausbaustufe (siehe Fachkonzept).

**Umsetzung (2026-05, Migration 063, App 0.8.137 ff.):** Tabellen **`training_unit_phases`** und **`training_unit_parallel_streams`**; **`training_unit_sections`** mit **`phase_id`** und **`parallel_stream_id`** (exakt eine Zuordnung pro Sektion). **`GET /api/training-units/:id`** liefert **`phases`** (verschachtelt) und flache **`sections`**. **Coaching** und **Durchführung** nutzen dieselbe Phasenlogik im Frontend (`trainingPlanUtils.js`).

**Dokumentation:** `functional/PARALLEL_TRAINING_STREAMS_CONCEPT.md`, Umsetzung `technical/PARALLEL_TRAINING_STREAMS_SPEC.md`.

## Medien-Archiv & Übungs-Anhänge (Stand 2026-05-07)

- **`media_assets`:** Zentrale Datei-/Asset-Zeile (technisch u. a. SHA‑Dedupe, Sichtbarkeit, `club_id`, Lifecycle, Copyright, Speicherreferenz unter `library/…`). Siehe **`DATABASE_SCHEMA.md`**, **`MEDIA_ASSETS_AND_ARCHIVE_SPEC.md`**.
- **`exercise_media`:** Verknüpfung **Übung ↔ Asset** (`media_asset_id`) oder **Embed** ohne Asset; Felder wie `context` (`ablauf` \| `detail` \| `trainer_hint`), Sortierung, Primär-Medium.
- **`platform_media_storage`:** Konfiguration effektiver Medienwurzel (Superadmin, relativ zu `MEDIA_ROOT`).
- **Produkt:** Medienbibliothek **`/media`**; in der Übungsbearbeitung Upload, Entfernen der Verknüpfung, **Aus Archiv verknüpfen**; Governance **`official`** und Copyright-Regeln wie in der Norm beschrieben.
- **Inline-Verweise** in Fließtextfeldern: **`MEDIA_ASSETS_AND_ARCHIVE_SPEC.md` §11**, **`docs/HANDOVER.md`** §5.

---

## Methodenbezug (§11.5)

**Prinzip:** Genau EINE Hauptmethode, optional weitere Nebenmethoden.

**Beispiele:**
- Hauptmethode: Rollenspiel
- Nebenmethoden: Strukturierte Übung, Reflexion

**Optional später:**
- Sportmethodische Hauptmethode
- Didaktische Zusatzmethode

---

## Qualitäts- und Bearbeitungsstatus (§11.3)

### Statusstufen

**Übungsstatus:**
- Entwurf (in Arbeit)
- In Bearbeitung (aktiv gepflegt)
- Fachlich geprüft (Review OK)
- Freigegeben (produktiv nutzbar)
- Archiviert (nicht mehr aktiv)

### Sichtbarkeitsebenen (§5.5)

**Freigabeebenen:**
- Privat (nur Ersteller)
- Für bestimmte Personen (später)
- Verein (alle Vereinsmitglieder)
- Sparte (nur bestimmte Sparte)
- Allgemein/Global (alle Nutzer)
- Offiziell (Standardinhalte)

**Zusätzlich:** Thematische Einschränkungen
- Karate-Inhalte (nur Übungen mit `focus_areas: ["karate"]`)
- Selbstverteidigungs-Inhalte
- Gewaltschutz-Inhalte

---

## MediaWiki Import (ab Migration 018)

### Import-Typen

**1. Übungen** (`import_type: exercise`)
- Quelle: https://karatetrainer.net `Kategorie:Übungen`
- Import-Modus: Vollständig mit Skill-Zuordnungen
- Status: ✅ Produktiv (221 Übungen importiert)

**2. Fähigkeiten** (`import_type: skill`)
- Quelle: https://karatetrainer.net `Kategorie:Fähigkeitsbeschreibung`
- Import-Modus: DEPRECATED - Nutze Migration 023 stattdessen
- Status: ⚠️ Migration 021 fehlerhaft, ersetzt durch Migration 023

**3. Trainingsmethoden** (`import_type: method`)
- Quelle: https://karatetrainer.net `Kategorie:Methodenbeschreibung`
- Import-Modus: Vollständig
- Status: 🔲 Noch nicht implementiert

### Import-Tracking

**Duplikat-Erkennung:**
- Über `wiki_import_references` Tabelle
- Verknüpfung `wiki_page_id` → `local_id`
- Reimport aktualisiert bestehende Einträge

**Import-Metadaten:**
- `import_source = 'mediawiki'`
- `import_id` = Wiki-Seitentitel
- `wiki_page_id` = MediaWiki interne Page-ID

---

## Admin-Workflows

### Fokusbereich anlegen

1. Admin navigiert zu Katalogverwaltung
2. Wählt "Fokusbereiche"
3. Klickt "Neu anlegen"
4. Füllt aus: Name, Kürzel, Beschreibung, Farbe, Icon
5. Speichert
6. System validiert Eindeutigkeit (Name)
7. Fokusbereich verfügbar für Stil-Zuordnung

### Stil verschieben (zwischen Fokusbereichen)

**Szenario:** Goju-Ryu soll von "Karate" nach "Karate Traditional" verschoben werden.

**Workflow:**
1. Admin wählt Stil "Goju-Ryu"
2. Klickt "Verschieben"
3. Wählt Ziel-Fokusbereich "Karate Traditional"
4. System prüft:
   - Ziel-Fokusbereich existiert
   - Keine Namenskonflikte
5. System aktualisiert:
   - `style_directions.focus_area_id`
   - Alle abhängigen Zielgruppen bleiben erhalten
6. System loggt Änderung
7. Erfolg-Meldung

### Fokusbereich löschen (mit Schutz)

**Szenario:** "Judo" soll gelöscht werden.

**Workflow:**
1. Admin wählt "Judo"
2. Klickt "Löschen"
3. System prüft Abhängigkeiten:
   ```sql
   SELECT COUNT(*) FROM style_directions WHERE focus_area_id = :id
   SELECT COUNT(*) FROM exercise_focus_areas WHERE focus_area_id = :id
   ```
4. **Falls verwendet:**
   - Dialog: "Fokusbereich kann nicht gelöscht werden. 5 Stile und 23 Übungen sind zugeordnet."
   - Optionen:
     - "Abbrechen"
     - "Stile/Übungen umrouten" (Admin wählt Ziel)
     - "Archivieren statt löschen"
5. **Falls nicht verwendet:**
   - Bestätigung: "Wirklich löschen? (Keine Abhängigkeiten)"
   - Löschen durchführen

### Zielgruppe umrouten

**Szenario:** Alle Übungen für "Kinder" sollen zu "Schüler" umgeleitet werden.

**Workflow:**
1. Admin wählt Zielgruppe "Kinder"
2. Klickt "Umrouten"
3. Wählt Ziel: "Schüler"
4. System zeigt Vorschau:
   - "47 Übungen werden aktualisiert"
   - Liste der betroffenen Übungen (mit Scroll)
5. Admin bestätigt
6. System führt Batch-Update aus:
   ```sql
   UPDATE exercise_target_groups
   SET target_group_id = :new_id
   WHERE target_group_id = :old_id
   ```
7. Optional: Alte Zielgruppe löschen oder archivieren
8. Erfolg-Meldung mit Log-Referenz

---

## Nächste Schritte

- [ ] Level-Definitionen aus Fähigkeitsmatrix extrahieren (optional)
- [ ] Skills-Beschreibungen aus Wiki importieren (Migration 024)
- [ ] Admin-UI für Fähigkeiten-Kategorien (CRUD)
- [x] Skill-Filter in Übungssuche (SkillTreeMultiSelect + Stufen)
- [x] Gewichtetes Fähigkeiten-Profil für Planungs-Bausteine (Module, Rahmen, Pfade) — siehe `technical/SKILL_SCORING_SPEC.md`
- [ ] Reifegradmodelle definieren (Kombination Fokusbereich + Stil + Zielgruppe)
- [ ] KI-Unterstützung für Trainingsplanung (basierend auf Fähigkeiten-Level)

---

**Letzte Aktualisierung:** 2026-05-20  
**Verantwortlich:** Claude Code  
**Review:** Pending