Refactor section movement logic in TrainingUnitSectionsEditor

- Streamlined the section movement process by consolidating validation checks and enhancing the handling of parallel phase indices.
- Improved the overall clarity and efficiency of the section management functionality, ensuring a smoother user experience during edits.

.claude/docs/technical/AI_TRAINING_PLANNING_CONCEPT.md

@@ -0,0 +1,178 @@
+# KI-gestützte Trainingsplanung – Zentrales Konzept
+
+**Version:** 0.1  
+**Datum:** 2026-05-16  
+**Status:** Arbeitsdokument (Verfeinerung durch fachliche Konzept-Agentur vorgesehen)  
+**Ziel:** Einheitlicher Rahmen für **stufenweise** KI-Unterstützung bei der Planung (Abschnitte, Einheiten, später mehrtägig/Rahmen) – ohne vollständigen Katalog im Prompt zu spiegeln.
+
+**Verwandte Dokumente:**  
+`functional/DOMAIN_MODEL.md` · `functional/TRAINING_CURRICULUM_AND_GOVERNANCE_CONCEPT.md` (u. a. CURR-003 zu Progressions-/KI-Automatik) · `technical/TRAINING_FRAMEWORK_SPEC.md` · `technical/KI_FEATURES_SPEC.md` · `technical/AI_PROMPT_SYSTEM_SPEC.md` · `docs/FACHLICHE_NUTZERFUNKTIONEN.md` · `docs/HANDOVER.md`
+
+---
+
+## 1. Produktliche Leitlinien
+
+- **Nutzer:** Trainer/Vereinskontext, **Gruppenplanung** – keine Pflicht zur individuellen Sportler-Verfolgung; Kontext soll primär aus **Gruppe**, **bereits geplanten/durchgeführten Einheiten**, **Rahmen-/Zielen** und **berechtigtem Übungskorpus** bestehen.
+- **Human-in-the-loop:** KI liefert **Vorschläge** (Liste, Reihenfolge, Begründung); schreibende Übernahme in Pläne nur nach **Trainer-Bestätigung** oder expliziter Aktion (analog „Manual First“ in `KI_FEATURES_SPEC.md`).
+- **Governance-first:** Nur Übungen, die die API bereits für den Mandanten/Kontext **sichtbar** freigibt, dürfen in Kandidatenlisten landen – **vor** Retrieval und **vor** jedem Prompt.
+
+---
+
+## 2. Kernproblem: Skalierung des Kontextes
+
+Aus einer **großen Übungssammlung** („>1000 Übungen“) können weder alle **Felder** (Ziele, Ablauf, Skills, Varianten …) noch alle **Zeilen** sinnvoll in einen LLM-Prompt.
+
+**Festlegung:** Der LLM-Prompt erhält immer nur ein **begrenztes Kontext-Paket** mit:
+
+| Paketteil | Zweck |
+|-----------|--------|
+| **Auftrag** | z. B. Sektionstyp, Dauerbudget, Schwierigkeit, erlaubte Phasen/Streams |
+| **Hard Constraints** | Gruppe, Termin/Zeitraum, Governance-Filter bereits angewendet |
+| **Komprimierte Historie** | Letzte *N* Einheiten als **Liste von Übungs-IDs + Kurzlabels** (+ optional Haupt-Skills), keine vollen Fließtexte |
+| **Ziele / Rahmen** | Kurztexte aus Rahmen-Slot/Zielblöcken oder Trainer-Prompt |
+| **Kandidaten-Top‑K** | z. B. 30–120 Übungen, **je Zeile gekürzt** (Titel, `summary`, 2–5 Skill-Namen/Stufen); **nie** der gesamte Katalog |
+| **Strukturierte Kanten optional** | Kleine Mengen Kanten aus Progressionsgraph: „Nachbarn von zuletzt genutzten Übungen“ |
+
+**Zahlen‑Richtwerte (überarbeitungsfähig):**  
+Kandidaten **vor** dem LLM typischerweise **50–150** Einträge; im Prompt durch Token-Limit weiter **truncate** oder **zweistufig** (grober Ranking-Schritt ohne LLM, dann finer mit LLM auf Top‑40).
+
+---
+
+## 3. Pipeline: „Selektion vor dem Prompt“
+
+Die **„optimale“** Auswahl entsteht **nicht**, indem das Modell den Katalog „im Kopf“ hält, sondern über eine **mehrstufige Pipeline**:
+
+### Stufe 1 – Harte Filter (deterministisch, DB)
+
+Synchron zur bestehenden Suche/List-API-Logik, z. B.:
+
+- Sichtbarkeit / Verein / `official`‑Regeln  
+- Aktivitäts-/Archiv-Status der Übung  
+- Fokusbereich, Stil, Zielgruppe (wenn Trainings-/Gruppenkontext das vorgibt)  
+- Ausschluss bereits in **dieser Einheit** fester Übernutzung (optional)
+
+Ergebnis: Menge \(M\) – kann noch sehr groß sein.
+
+### Stufe 2 – Kontext-Verankerung (deterministisch + Graph)
+
+- **Historie:** aus letzten *N* Gruppeneinheiten extrahierte `exercise_id`s (optional Variant).  
+- **Progressionsgraph:** ausgehend davon Nachbarn (eingehend/ausgehend begrenzte Tiefe) – bereits im Produkt als **unterstützend** modelliert (**CURR‑013**).  
+- **Rahmen/Slot-Ziele:** Überlapp mit Skill-Tags oder Stichwortliste (falls formalisiert).  
+- **Variantenketten:** `prerequisite_variant_id` / `progression_level` nur innerhalb bereits gewählter Übung prüfen oder als Hint an den LLM-Block durchreichen.
+
+Ergebnis: **„Anker‑Menge“** + **„Graph‑Nachbarschaft“** → priorisierte Kandidaten.
+
+### Stufe 3 – Weiches Ranking / Retrieval (halb-strukturiert)
+
+Mindestens **eine** der folgenden Optionen – kombinierbar:
+
+1. **Skill-/Facet-Overlap:** Punktezahl, wenn Übungs-Skills mit Ziel-/Matrix-Schwerpunkten übereinstimmen (bereits Daten in `exercise_skills`).  
+2. **Diversitäts-/Wiederholungsstrafe:** häufig in letzten Wochen geübte Übungen abwerten.  
+3. **Textsuche:** PostgreSQL **`tsvector`/Volltext** auf `title`, `summary`, ggf. gekürzte `goal` – für Trainer-Stichwort „Koordination Sprung“.  
+4. **Semantische Suche:** Embeddings + **Ähnlichkeitsuche** auf Kurztexte (siehe §5).
+
+Ergebnis: sortierte Liste, **Top‑K** für den Prompt.
+
+### Stufe 4 – LLM (optional zweistufig)
+
+- **Optional 1:** LLM nur **sortiert/rankted** bereits vorgegebene IDs (Ranking mit kurzer Begründung).  
+- **Optional 2:** Zwei Calls: erst „welche drei Schwerpunkte“ / „Welche Constraints habe ich übersehen?“, zweiter Call nur mit gekürztem Top‑K – nur wenn UX den Mehraufwand rechtfertigt.
+
+**Ausgabe-Contract:** Zurückkommen dürfen **nur gültige `exercise_id`s** aus der übergebenen Kandidatenliste (Server validiert gegen Set); **Halluzinationsrisiko damit entschärft**.
+
+---
+
+## 4. Antwort auf die konkrete Frage: „Alle Übungen in den Prompt?“
+
+**Nein.** Workflow:
+
+1. **DB + Regeln + Graph + Historie** reduzieren auf **einige Hundert bis wenige tausend** Rohzeilen höchstens **intern** – aber  
+2. in den **LLM-Prompt** gehen nur **Top‑K kompakte Artefakte** (siehe §2).
+
+Das LLM löst dann **Ranking, Reihenfolge, Timing-Hinweise, Trainer-sprachliche Kurzkommentare** – nicht die Frage „gibt es diese Übung überhaupt im System?“.
+
+---
+
+## 5. Vector DB (z. B. Qdrant) – wann nötig, wann nicht?
+
+### 5.1 Ziel embeddings
+
+Semantic Retrieval: „wie springt Coordinative Belastung ohne das Wort ‚Koordination‘ im Titel zu stehen.“ Das ist **über** reine Filtersuche und oft **über** stumpfe Volltextsuche erreichbar.
+
+### 5.2 Option A – ohne separate Vector DB
+
+- **PostgreSQL + `pgvector`** (Extension): Embeddings-Spalte an `exercises` (oder an „Search Document“-Zeilen), Indices, Abfrage zusammen mit SQL-Filtern in **einer Transaktions-DB**.  
+- **Größenordnung** einige 10 k–100 k Zeilen für Übungen: für Shinkan **oft ausreichend**.  
+- Vorteile: ein Betriebspfad, Mandanten-/Governance weiter in SQL lösen; Backup wie heute.
+
+### 5.3 Option B – Qdrant (oder anderer Dediz-Vektorstore)
+
+Sinnvoller zeitlicher Punkt oder technische Auslöser:
+
+- sehr hohe Latenz-Anforderung mit **Hybrid-Filter** über viele kombinierte Metadaten in nahezu Echtzeit,  
+- Entkopplung: Embedding-Pipeline läuft asynchron und soll die **Operational DB** nicht beschweren,  
+- später **mehrsprachig** oder **mehrere Embedding-Versionen**/Re-Index ohne großen Migrationstress,  
+- Team bevorzugt **Dedicated** Vector-Ops gegenüber Postgres-Ops.
+
+### 5.4 Empfehlung für diese Codebasis (überarbeitungsfähig)
+
+1. **Phase 1:** Harte Filter + Graph + Historie + **PostgreSQL-Volltext** + Top‑K; LLM erst auf komprimierten Kandidaten → hoher Nutzen ohne neuen Infrastructure-Typen.  
+2. **Phase 2:** Bei nachweisbaren „Recall-Lücken“ (Trainer findet nichts Passendes trotz großem Korpus) **`pgvector` in Postgres** evaluieren – **vor** zusätzlicher Infrastruktur wie Qdrant.  
+3. **Phase 3:** Qdrant (o. ä.) wenn Größenordnung, Betrieb oder Produkt-Anforderungen **pgvector** sprengen oder klar eine **embedding-first** Produktstraße geplant wird.
+
+**Fazit:** Eine dedizierte **Vector DB ist nicht zwingende Voraussetzung** für vernünftige Selektion; sie ist eine **Ausbaustufe**, wenn **semantische Lücke** und Skalierung es rechtfertigen. **Selektion** ist immer **„Filter + Ranking + kleines Top‑K“**, unabhängig vom Speicherort der Vektoren.
+
+---
+
+## 6. Datenpflege für gutes Retrieval (fachlicher Hebel)
+
+Retrieval‑Qualität hängt stärker an **Metadaten** als an der Embedding-Technologie allein:
+
+- verlässliche **Skills** (`exercise_skills`, ggf. KI-geholfen bereits laut Spez beim Übungs-Anlegen);  
+- sinnvolle **`summary`**-Felder für Karten/Liste/KI-Pack;  
+- **Progressionsgraph** dort, wo pädagogische Ketten gefestigt sind;  
+- konsistente **Fokusbereich/Stil**-Zuordnung.
+
+Das fachliche Konzept sollte entscheiden: **wie viel automatische Pflege vs. Trainer-Pflichtfelder**.
+
+---
+
+## 7. Produkt-/Release-Stufen (Anknüpfung)
+
+| Stufe | Nutzen | Technik-Schwerpunkt |
+|-------|--------|---------------------|
+| A | Backend-KI-Service + Prompt-Slugs unter `technical/AI_PROMPT_SYSTEM_SPEC.md` | OpenRouter, Timeouts, 503 ohne Key |
+| B | „Übungen für Abschnitt vorschlagen“ | Pipeline §3 Stufen 1–3 + Prompt mit Top‑K |
+| C | Reihenfolge / Zeitslots innerhalb bestehender Sektion | Graph + LLM Ranking |
+| D | Ganze Einheit (inkl. Phasen/Streams vereinfacht) | strukturiertere JSON-Ausgabe, strikte Schema-Validation |
+| E | Mehreinheiten / Rahmen‑Alignment | Ziele aus Rahmenprogramm, Serie von Slots |
+
+Die **Selektions‑Pipeline §3 bleibt** über alle Stufen konsistent und wird nur parametrierbar erweitert.
+
+---
+
+## 8. Compliance & Datenschutz (Kurzhinweis)
+
+- Datenminimierung: **keine Teilnehmerliste** ohne expliziten Scope; Kontext über **Einheiten-Metadaten** und Übungen.  
+- **OpenRouter**/Modellwahl: Organisation intern klären (AV/Verarbeitungsvertrag, Datenflüsse außerhalb EU – siehe Repo-Compliance-Dokumente).  
+- **Logging:** Prompts keine unnötigen personenbezogenen Daten; wenn Debug: Retention definieren.
+
+---
+
+## 9. Offene Punkte für die fachliche Verfeinerung
+
+- Gewichtung „**Wiederholung** vs. **Progression** vs. **Motivation**“ (domänenspezifisch).  
+- Umgang mit **Kombinationsübungen** und **Coach-Stufen B/C** in der Datenübergabe.  
+- Soll das System **„Lücken“** aus der **Matrix-Auflösung** aktiv quantifizieren oder nur Narrative verwenden?  
+- Akzeptierte **Übersetzungen**: nur Deutsch oder mehrsprachige Embeddings erforderlich?
+
+---
+
+## 10. Glossar
+
+| Begriff | Bedeutung |
+|---------|-----------|
+| **Top‑K** | Feste kleine Obergrenze Übungen pro LLM-Anfrage |
+| **Hard filter** | Deterministische SQL-/Policy-Einschränkung vor KI |
+| **Kontext-Paket** | Zusammengesetztes, tokenlimitiertes Eingabeobjekt für den Prompt |
+| **Retrieval** | algorithmischer Schritt ohne Generierung („wer kommt überhaupt in Frage“) |