mitai-jinkendo/docs/issues/UMSETZUNGSPLAN_TRAININGSPROFILE_SPORTSPEZIFISCH_2026-04-05.md

Umsetzungsplan: Sportspezifisch auswertbare Trainingsprofile

Status: Konzept für fachliche Abstimmung / Konzeptagent
Datum: 2026-04-05
Bezug: Fachliches Teilkonzept „Sportspezifisch auswertbare Trainingsprofile“ (User-Entwurf)
Hinweis: Keine Implementierung ohne Freigabe der unter Offene Fragen gekläerten Punkte.

---

1. Kurzfazit: Machbarkeit

Fachlich und technisch grundsätzlich machbar als gestaffelte Erweiterung auf dem bestehenden System:

• training_types.profile (JSONB)
• TrainingProfileEvaluator (backend/profile_evaluator.py)
• Persistenz: activity_log.evaluation, quality_label, overall_score

Engpass: Viele im Teilkonzept genannten Kriterien (z. B. Muskelgruppen, Nähe zum muskulären Versagen, detaillierte Zonenzeiten) lassen sich aus der aktuellen activity_log-Datenbasis nicht zuverlässig ableiten. Dafür braucht es zusätzliche Erfassung, Importfelder oder explizite „niedrige Evidenz / unbekannt“-Markierung in Metriken und KI-Kontext (Placeholder-Registry, Erklärbarkeit).

---

2. Ist-Analyse (Abhängigkeiten)

2.1 Daten & Konfiguration

Baustein	Rolle
training_types	category, subcategory, name_*, optional abilities (JSONB), profile (JSONB)
activity_type_mappings	Import/manuelles Mapping activity_type → training_type_id (unverändert lassen)
training_parameters	Registry messbarer Parameter für Regeln (source_field → activity_log)
activity_log	u. a. training_type_id, evaluation, quality_label, overall_score

2.2 Bewertung heute

• Der Evaluator läuft über mehrere rule_sets (Minimumanforderungen, Zonen, Effekte, Periodisierung, KPI, Safety).
• Ein zusammengefasster overall_score und ein quality_label (excellent | good | acceptable | poor).
• Relevanz, intrinsische Qualität, Zielbezug, Platzierung sind im Ergebnis nicht formal getrennt; Periodisierung/Performance sind teils MVP/vereinfacht.

2.3 Downstream (nicht brechen)

• Issue #31 / Quality Filter: profiles.quality_filter_level, quality_filter.py (SQL-Fragmente nach quality_label)
• Frontend: Badges in Aktivitäts-UI, History-Hinweise
• Data Layer / Charts: u. a. calculate_quality_sessions_pct, activity_score, Korrelationen
• Placeholder Registry: u. a. quality_sessions_pct (bekannte Semantik-/Label-Diskrepanz, siehe unten)

2.4 Bekannte technische Inkonsistenz (Bestand)

calculate_quality_sessions_pct filtert u. a. auf quality_label IN (..., 'very_good', ...), der TrainingProfileEvaluator setzt very_good nicht. Das sollte vor oder zusammen mit größeren Profil-Erweiterungen bereinigt werden, damit neue Dimensionen nicht auf wackeliger Basis validiert werden.

---

3. Umsetzungsprinzipien (Kompatibilität)

1. Kein Big-Bang: Consumer erwarten weiterhin sinnvolle quality_label / overall_score, es sei denn, es gibt eine versionierte Cutover-Strategie.
2. Additive JSON-Struktur in evaluation (z. B. mehrdimensionale Teilergebnisse), ohne bestehende Schlüssel willkürlich zu entfernen.
3. Legacy-Vertrag festlegen: z. B. overall_score = primär intrinsische Qualität (oder explizit „Legacy-Komposit“ mit schema_version).
4. training_types bleibt Single Source für Typ + Profil; Mapping-Import-Logik nicht „mitziehen“, außer es ist fachlich nötig.
5. Neue Coach-Metriken: über Placeholder Registry, mit Evidence-Tags; keine doppelte Wahrheit neben der Registry.
6. KI: ai_context / interpretation_boundary im Profil ausbaubar machen (was erlaubt/verboten ist, bei Datenlücken).

---

4. Phasenplan

Phase 0 – Begriffe, Verträge, Bestandsaufnahme

• Glossar: Relevanz, intrinsische Qualität, Zielbeitrag, Platzierung, Belastung, sportspezifische Qualität → Mapping auf bestehende rule_sets.
• Vollständige Liste: wer liest quality_label / evaluation / overall_score (APIs, SQL, Frontend).
• Align: very_good vs. Evaluator-Labels; optional: Rolle von acceptable in „Qualitätssessions“ vs. globalem Filter fachlich klären.

Phase 1 – Metamodell im Profil-JSON

• Erweiterung training_types.profile: z. B. sport_logic, dimensions_config, goal_linkage, load_character, recovery_character, interference, ai_interpretation.
• Evaluator liefert Teilscores + Begründungen pro Dimension; Legacy-Felder ableitbar und dokumentiert.

Phase 2 – Zielbezug

• Input: aktive Ziele, goal_mode, Focus-Gewichte (user_focus_area_weights).
• Ausgabe: eigene Dimension goal_fit, ohne intrinsische Bewertung zu überschreiben.

Phase 3 – Wochenkontext / Platzierung / Interferenz

• Kontext in load_evaluation_context erweitern (Reihenfolge, Vortag, Ruhetage, optional Vitals/Schlaf).
• Regeln schrittweise; False-Positive-Risiko beachten.

Phase 4 – Sportspezifische Templates

• Profilvorlagen pro sport_logic (analog profile_templates.py), unterschiedliche Parameter und Schwellen.
• confidence / data_sufficiency pro Dimension.

Phase 5 – Coach-Metriken & Placeholder

• Neue Platzhalter nur bei klarer Semantik; ggf. quality_sessions_pct umschreiben oder durch neuen Key ersetzen + Deprecation-Plan.

Phase 6 – Frontend / Admin

• Dimensionen sichtbar machen; Badges können vorerst Legacy-Score anzeigen.

---

5. Risiken (Kurz)

Risiko	Maßnahme
Bedeutung von quality_label wechselt still	evaluation.schema_version, dokumentierter Vertrag, ggf. separates intrinsic_quality_label nach Cutover
Charts/Scores springen	Shadow-Vergleich, gestuftes Rollout
KI übertreibt bei Datenlücken	ai_interpretation + Metadata-Evidence
Registry-Drift	Alle neuen Kennzahlen registrieren

---

Offene Fragen für den fachlichen Konzeptagenten

Die folgenden Blöcke sind bewusst als Markdown-Codeblöcke formatiert, damit sie unverändert in Prompts oder Tickets übernommen werden können.

Block A – Priorität & Konflikte zwischen Dimensionen

Wenn sich Dimensionen widersprechen (z. B. intrinsische Qualität „hoch“, Zielpassung „niedrig“, Platzierung „problematisch“):

1. Welche Dimension soll für die **primäre Nutzer-/Coach-Aussage** in der UI führend sein?
2. Gibt es eine **feste Prioritätsreihenfolge** (z. B. Sicherheit > Platzierung > Zielpassung > intrinsische Qualität) oder ist sie kontextabhängig?
3. Soll es eine **explizite „Gesamt-Coach-Empfehlung“** geben, die aus den Dimensionen kombiniert wird, oder nur parallele Teilurteile ohne Gesamtnote?

Block B – Minimaldatensatz & Sportlogiken

Pro Trainingsfamilie / „sport_logic“ (Kraft, Cardio, Schnellkraft, Kampfsport, Mobility, Erholung aktiv, Geist & Meditation):

1. Welche **messbaren Felder** sind minimal nötig, damit eine sportspezifische Bewertung **fachlich vertretbar** ist (nicht nur „nice to have“)?
2. Welche Aussagen dürfen **ohne** diese Felder **nicht** getroffen werden (nur „unbekannt“ / Confidence niedrig)?
3. Sollen fehlende Daten die **intrinsische** Bewertung hart begrenzen (Cap), oder nur **Zusatzdimensionen** betreffen?

Block C – Einzeltraining vs. Wochenkontext

Platzierung / Kontextqualität:

1. Darf schlechte Platzierung die **sichtbare Einheit-Qualität** numerisch senken, oder nur **Flags/Hinweise** erzeugen?
2. Welche zeitliche Auflösung ist Pflicht: nur **Datum** oder auch **start_time** / Reihenfolge am Tag?
3. Wie gehen wir mit **unvollständiger Historie** um (Importlücken, manuell gelöschte Einträge)?

Block D – Ziele & Multi-Ziel

Zielbezug (goal_fit):

1. Bewertung strikt gegen **ein Primärziel**, oder gewichtet gegen **alle aktiven Ziele**?
2. Wie werden **Focus Areas** vs. **konkrete Goals** priorisiert, wenn sie sich widersprechen?
3. Soll „behindert das Ziel“ (Teilkonzept) ein **eigener Score** oder nur eine **kategorische** Aussage sein?

Block E – KI & Haftung / Grenzen

KI-Interpretationsrahmen (pro Profil oder global):

1. Welche Formulierungen sind **verboten** (medizinische Diagnosen, absolute Leistungsversprechen, …)?
2. Muss jede KI-gestützte Aussage einen **Evidenz-Hinweis** tragen („basierend auf Dauer/HF“, „Muskelgruppen nicht erfasst“)?
3. Soll der Nutzer **opt-in** für interpretative Texte jenseits der Regeln haben?

Block F – Legacy-Metriken & Filter

Bestehende Kennzahlen:

1. Soll `quality_label` / `overall_score` dauerhaft **nur intrinsisch** bedeuten, oder ein **Komposit** aus mehreren Dimensionen?
2. Wie sollen `quality_sessions_pct` und der globale **Quality Filter** künftig mit mehrdimensionalen Urteilen umgehen (nur intrinsisch filtern vs. Kombination)?
3. Ist `acceptable` fachlich eine „Qualitätssession“ oder nur „formal ok“?

Block G – Abnahme / Akzeptanz

Abnahme:

1. Welche **messbaren** Abnahmekriterien gelten pro Phase (z. B. % konsistent bewerteter Sessions, keine Regression bei Filter-Charts)?
2. Wer **fachlich** sign-off: Rolle „Domain Owner“ vs. Entwicklung?

---

Anhang: Referenz im Repository

Thema	Pfad (orientierend)
Evaluator	backend/profile_evaluator.py
Regeln	backend/rule_engine.py
Auswertung + Kontext	backend/evaluation_helper.py
Profile JSON / Migration	backend/migrations/014_training_profiles.sql, Templates backend/profile_templates.py
Quality Filter	backend/quality_filter.py
Aktivitäts-API inkl. Eval	backend/routers/activity.py
Quality-Sessions-Metrik	backend/data_layer/activity_metrics.py (calculate_quality_sessions_pct)
Placeholder Registry	backend/placeholder_registrations/activity_metrics.py

---

Ende des Dokuments.