shinkan-jinkendo/.claude/docs/technical/DATABASE_SCHEMA.md

Shinkan Jinkendo - Datenbank-Schema (Technisch)

Version: 0.3.4
Stand: 2026-04-23
Aktuell deployed: Migration 009 (Target Groups M:N Refactoring)

---

Übersicht

Dieses Dokument beschreibt die technische Datenbankstruktur von Shinkan Jinkendo.

Zuständig für fachliche Modellierung: siehe DOMAIN_MODEL.md

---

Migrations-Historie

Nr.	Datum	Beschreibung	Status
001	2026-04-20	Initial Schema (Auth, Profiles)	✅ Deployed
002	2026-04-20	Clubs, Divisions, Groups	✅ Deployed
003	2026-04-20	Skills, Methods	✅ Deployed
004	2026-04-21	Training Types	✅ Deployed
005	2026-04-21	Exercises (Basis)	✅ Deployed
006	2026-04-21	Training Planning	✅ Deployed
007	2026-04-22	Exercise Catalogs (idempotent)	✅ Deployed
008	2026-04-23	M:N Exercise Relations + Hierarchical Catalogs	✅ Deployed
009	2026-04-23	Target Groups M:N Refactoring (BREAKING)	✅ Deployed

---

Migration 009: Target Groups M:N Refactoring (BREAKING CHANGE)

Problem: Zielgruppen waren hierarchisch an Trainingsstile gebunden (1:N via FK training_style_id).
Lösung: M:N Beziehung über Junction-Tabelle training_style_target_groups.

Änderungen:

• ❌ Entfernt: target_groups.training_style_id (FK constraint + column)
• ✅ Neu: training_style_target_groups Junction-Tabelle
• ✅ Migriert: Alte Zuordnungen zu M:N (alle mit is_primary = true)
• ✅ Architektur: Eine Zielgruppe kann mehreren Stilen zugeordnet sein

Neue Struktur:

-- Global unabhängige Zielgruppen (KEINE training_style_id mehr)
target_groups (
  id, name, description, min_age, max_age, 
  sort_order, status, created_at, updated_at
)

-- M:N Junction-Tabelle
training_style_target_groups (
  id SERIAL PRIMARY KEY,
  training_style_id INT REFERENCES training_styles(id) ON DELETE CASCADE,
  target_group_id INT REFERENCES target_groups(id) ON DELETE CASCADE,
  is_primary BOOLEAN DEFAULT false,
  created_at TIMESTAMP DEFAULT NOW(),
  UNIQUE(training_style_id, target_group_id)
)

Backend API: 5 neue Endpoints:

• GET /api/training-style-target-groups (Liste mit Filtern + Enrichment)
• POST /api/training-style-target-groups (Upsert-Logik)
• PUT /api/training-style-target-groups/{id} (is_primary Flag)
• DELETE /api/training-style-target-groups/{id}
• GET /api/training-styles/hierarchy (Hierarchische Struktur für Tree-View)

Frontend:

• Admin-UI Tab "Hierarchie" (Tree-View: Fokusbereich → Stil → Zielgruppen)
• Admin-UI Tab "Zuordnungen" (Checkbox-Matrix für M:N)
• Tab "Zielgruppen" überarbeitet (global, ohne training_style_id Dropdown)

---

Kern-Entitäten (Stand Migration 007)

Auth & Profile

profiles (id, name, email, password_hash, role, created_at)
sessions (id, profile_id, token, created_at, expires_at)

Organisation

clubs (id, name, abbreviation, description, logo_url, ...)
divisions (id, club_id, name, description, ...)
training_groups (id, division_id, name, description, focus_area, level, ...)

Kataloge (Einfache FK-Struktur - zu refactoren)

ACHTUNG: Aktuell 1:1 Beziehungen - fachlich inkorrekt!

focus_areas (id, name, abbreviation, description, color, icon, ...)
training_styles (id, name, abbreviation, description, parent_style_id, ...)
training_characters (id, name, description, ...)
skill_categories (id, name, description, parent_category_id, ...)

Übungen (Aktuell - zu refactoren)

exercises (
  id, title, summary, goal, execution, preparation, trainer_notes,
  focus_area_id,           -- ❌ 1:1 - sollte M:N sein
  training_style_id,       -- ❌ 1:1 - sollte M:N sein
  training_character_id,   -- ❌ 1:1 - sollte M:N sein
  visibility, status, created_by, club_id, ...
)

exercise_skills (exercise_id, skill_id, is_primary, intensity, ...)
exercise_variants (id, exercise_id, name, description, ...)
exercise_media (id, exercise_id, type, url, title, description, ...)

Training Planning

training_units (id, group_id, date, title, description, ...)
training_unit_exercises (training_unit_id, exercise_id, sort_order, ...)

---

Geplante Änderungen (Migration 008)

Hierarchische Katalog-Struktur

Fachliche Anforderung (§8.1 Anforderungsdokument):

Fokusbereich → Stil → Zielgruppe

Neue Struktur:

-- Level 1: Fokusbereiche (Root)
focus_areas (
  id SERIAL PRIMARY KEY,
  name VARCHAR(100) UNIQUE NOT NULL,
  abbreviation VARCHAR(20),
  description TEXT,
  color VARCHAR(20),
  icon VARCHAR(50),
  sort_order INT,
  status VARCHAR(50) DEFAULT 'active'
)

-- Level 2: Trainingsstile (untergeordnet zu Fokusbereich)
training_styles (
  id SERIAL PRIMARY KEY,
  focus_area_id INT REFERENCES focus_areas(id), -- Hierarchie-Link
  name VARCHAR(100) NOT NULL,
  abbreviation VARCHAR(20),
  description TEXT,
  parent_style_id INT REFERENCES training_styles(id), -- Optional: Sub-Stile
  sort_order INT,
  status VARCHAR(50) DEFAULT 'active'
)

-- Level 3: Zielgruppen (untergeordnet zu Stil)
target_groups (
  id SERIAL PRIMARY KEY,
  training_style_id INT REFERENCES training_styles(id), -- Hierarchie-Link
  name VARCHAR(100) NOT NULL,
  description TEXT,
  min_age INT,
  max_age INT,
  sort_order INT,
  status VARCHAR(50) DEFAULT 'active'
)

M:N Übungs-Zuordnungen

-- Übung → Fokusbereiche (M:N)
exercise_focus_areas (
  id SERIAL PRIMARY KEY,
  exercise_id INT REFERENCES exercises(id) ON DELETE CASCADE,
  focus_area_id INT REFERENCES focus_areas(id),
  is_primary BOOLEAN DEFAULT false,
  UNIQUE(exercise_id, focus_area_id)
)

-- Übung → Stile (M:N)
exercise_styles (
  id SERIAL PRIMARY KEY,
  exercise_id INT REFERENCES exercises(id) ON DELETE CASCADE,
  training_style_id INT REFERENCES training_styles(id),
  is_primary BOOLEAN DEFAULT false,
  UNIQUE(exercise_id, training_style_id)
)

-- Übung → Zielgruppen (M:N)
exercise_target_groups (
  id SERIAL PRIMARY KEY,
  exercise_id INT REFERENCES exercises(id) ON DELETE CASCADE,
  target_group_id INT REFERENCES target_groups(id),
  is_primary BOOLEAN DEFAULT false,
  UNIQUE(exercise_id, target_group_id)
)

-- Übung → Altersgruppen (M:N - separate Dimension)
exercise_age_groups (
  id SERIAL PRIMARY KEY,
  exercise_id INT REFERENCES exercises(id) ON DELETE CASCADE,
  age_group VARCHAR(50) NOT NULL, -- 'Minis', 'Kinder', 'Schüler', 'Teenager', 'Erwachsene'
  UNIQUE(exercise_id, age_group)
)

---

Kaskadier-Regeln (Geplant)

Fokusbereich löschen

Verhalten: RESTRICT (Löschen verweigern wenn verwendet)

Alternativen:

1. Umrouten: Alle abhängigen Stile auf neuen Fokusbereich setzen
2. Archivieren: Status auf 'archived' setzen statt löschen

Implementierung:

-- Prüfung vor Löschen:
SELECT COUNT(*) FROM training_styles WHERE focus_area_id = :id
SELECT COUNT(*) FROM exercise_focus_areas WHERE focus_area_id = :id

-- Falls verwendet → HTTP 409 Conflict mit Hinweis

Stil löschen

Verhalten: RESTRICT wenn Zielgruppen oder Übungen zugeordnet

Umrouten-Workflow:

1. Admin wählt Ziel-Stil
2. System aktualisiert:
   • target_groups.training_style_id
   • exercise_styles.training_style_id
3. Löschen erlaubt

Zielgruppe löschen

Verhalten: SET NULL oder CASCADE in exercise_target_groups

---

Indizes (Geplant)

-- Hierarchie-Lookups
CREATE INDEX idx_training_styles_focus_area ON training_styles(focus_area_id);
CREATE INDEX idx_target_groups_style ON target_groups(training_style_id);

-- M:N Joins
CREATE INDEX idx_exercise_focus_areas_exercise ON exercise_focus_areas(exercise_id);
CREATE INDEX idx_exercise_focus_areas_focus ON exercise_focus_areas(focus_area_id);
CREATE INDEX idx_exercise_styles_exercise ON exercise_styles(exercise_id);
CREATE INDEX idx_exercise_styles_style ON exercise_styles(training_style_id);
CREATE INDEX idx_exercise_target_groups_exercise ON exercise_target_groups(exercise_id);
CREATE INDEX idx_exercise_target_groups_target ON exercise_target_groups(target_group_id);

---

Deprecation-Pfad (Migration 008)

Legacy-Spalten in exercises:

-- Werden in Migration 008 deprecated:
exercises.focus_area_id        → Migriert zu exercise_focus_areas (is_primary=true)
exercises.training_style_id    → Migriert zu exercise_styles (is_primary=true)
exercises.training_character_id → Bleibt vorerst (separate Dimension)

-- Spalten bleiben zur Rückwärtskompatibilität, aber:
-- 1. Daten migriert
-- 2. Neue Übungen nutzen M:N-Tabellen
-- 3. API liefert enriched data aus M:N
-- 4. Später: Spalten droppen nach Stabilisierung

---

Nächste Schritte

• Migration 008 Entwurf erstellen
• Migrations-Strategie für Altdaten dokumentieren
• Admin-UI für Baum-Verwaltung planen
• API-Endpoints für hierarchische Navigation
• Cascade-Logik implementieren
• Tests für Löschen/Umrouten

---

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