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

Shinkan Jinkendo - Fachliches Domänenmodell

Version: 0.3.4
Stand: 2026-04-23 (Migration 009: Target Groups M:N Refactoring)
Basis: shinkan_anforderungsdokument_entwurf.md

---

Ü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.

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

---

Ü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:

• Distanzgefühl (Intensität: hoch)
• Timing (Intensität: hoch)

Nebenfähigkeiten:

• Beinarbeit (Intensität: mittel)
• Reaktionsfähigkeit (Intensität: mittel)

Attribute pro Fähigkeitsbezug:

• is_primary (Haupt- oder Nebenfähigkeit)
• intensity (niedrig/mittel/hoch)
• development_contribution (Entwicklungsbeitrag)
• required_level (Voraussetzung)
• target_level (Ziel-Level)

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
• Selbstverteidigungs-Inhalte
• Gewaltschutz-Inhalte

---

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:
   • training_styles.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 training_styles 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

• Hierarchie-UI Wireframes erstellen
• Admin-CRUD-Endpoints spezifizieren
• Cascade-Logik detaillieren
• Umrouten-Workflows implementieren
• Migration 008 Entwurf finalisieren
• Tests für alle Admin-Operationen

---

Letzte Aktualisierung: 2026-04-23
Verantwortlich: Claude Code
Review: Pending