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:
   ```sql
   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:
   ```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

- [ ] 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