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

Shinkan Jinkendo - Fachliches Domänenmodell

Version: 0.4.2
Stand: 2026-05-05 (Migration 035: Rahmen‑Vorlage training_framework_programs; Progressionsgraph unverändert 032–034)
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

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.

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 direkten Übungszuordnungen pro Slot („Stückliste“, CURR‑010). Der persistierte Progressionsgraph zwischen Übungen bleibt optional und ersetzt keine Slot-Zuordnung (CURR‑013).

Zwei Nutzungsmodi (CURR‑012): concrete (Kurzfrist‑/Gruppenkontext; optional group_id, Slots dürfen training_unit_id tragen) vs. library (zeit‑/gruppenlose Vorlage; group_id und Slot‑Einheitsverknüpfungen sind fachlich gesperrt — technisch werden Einheits-FKs beim Wechsel geleert). Materialisierung / Bulk‑Anlegen von training_units aus dem Rahmen ist ein separater Schritt (Stub/PR). optional training_plan_template_id pro Slot ist bewusst deferred (C5/CURR‑010).

---

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