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

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:

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:

   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:

   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