203 lines
9.8 KiB
Markdown
203 lines
9.8 KiB
Markdown
# 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](#offene-fragen-für-den-fachlichen-konzeptagenten) 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
|
||
|
||
```markdown
|
||
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
|
||
|
||
```markdown
|
||
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
|
||
|
||
```markdown
|
||
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
|
||
|
||
```markdown
|
||
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
|
||
|
||
```markdown
|
||
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
|
||
|
||
```markdown
|
||
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
|
||
|
||
```markdown
|
||
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.*
|