# Shinkan Jinkendo - Fachliches Domänenmodell

**Version:** 0.4.0  
**Stand:** 2026-04-27 (Migration 023: Skills Complete Import)  
**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 `is_primary` Flag.

### 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:**
- is_primary (Haupt- oder Nebenfähigkeit)
- intensity (niedrig/mittel/hoch)
- required_level (Voraussetzung, 1-5)
- target_level (Ziel-Level, 1-5)

**🆕 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

---

## 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)
- [ ] Skill-Filter in Übungssuche integrieren
- [ ] Reifegradmodelle definieren (Kombination Fokusbereich + Stil + Zielgruppe)
- [ ] KI-Unterstützung für Trainingsplanung (basierend auf Fähigkeiten-Level)

---

**Letzte Aktualisierung:** 2026-04-27  
**Verantwortlich:** Claude Code  
**Review:** Pending