mitai-jinkendo/.claude/docs/functional/mitai_jinkendo_konzept_diagramme_auswertungen_v2.md

# Konzept – Diagramme, Scores und regelbasierte Auswertungen für Mitai Jinkendo

**Stand:** 24.03.2026  
**Ziel:** Fachlich belastbares Konzept für Diagramme, Kennzahlen, Scores, Warnungen und regelbasierte Empfehlungen **ohne KI**, aber so strukturiert, dass ein Coding Agent es direkt umsetzen kann.  
**Basis:** Analyse des hochgeladenen Datenmodells `DATA_ARCHITECTURE.md` (Gewicht, Umfänge, Caliper, Aktivitäten, Vitalwerte, Blutdruck, Schlaf, Ernährung, geplante Recovery-/Korrelations-Logik).  

---

## 1. Zielbild

Das System soll vor einer späteren KI-Stufe bereits drei Ebenen sauber abdecken:

1. **Deskriptiv:** Was ist passiert?
   - Zeitreihen, Verteilungen, Trends, Volumina, Zielabweichungen
2. **Diagnostisch:** Was hängt wahrscheinlich zusammen?
   - Lag-basierte Zusammenhänge, Baseline-Abweichungen, Muster, Plateaus, Wechselwirkungen
3. **Präskriptiv (regelbasiert, nicht KI):** Was ist als nächste Handlung naheliegend?
   - konkrete, nachvollziehbare Hinweise mit Trigger-Logik und Vertrauensstufe

Wichtig ist, dass das System **zielabhängig** interpretiert:
- Gewichtsreduktion
- Muskel-/Kraftaufbau
- Konditions-/Ausdaueraufbau
- Körperrekomposition
- allgemeine Gesundheit
- Mischziele

Dasselbe Rohsignal kann je nach Ziel anders bewertet werden. Ein Kaloriendefizit ist z. B. bei Gewichtsreduktion oft positiv, bei Kraftaufbau aber potenziell hinderlich.

---

## 2. Fachliche Bewertung des aktuellen Datenmodells

## 2.1 Stärken des vorhandenen Modells

Das vorhandene Modell ist bereits ungewöhnlich stark, weil es mehrere Domänen zusammenführt:
- **Körper:** Gewicht, Umfänge, Caliper, BF%, LBM, FM
- **Aktivität:** Trainingstypen, Qualität, Dauer, HR, Kalorien, Fähigkeiten-Beitrag
- **Recovery / Gesundheit:** RHR, HRV, VO2max, SpO2, Atemfrequenz, Blutdruck
- **Lifestyle:** Schlafdauer, Schlafsegmente, Ernährung, Ruhetage
- **Korrelationen / spätere KI:** bereits als Richtung angelegt

Dadurch sind nicht nur Einzelcharts möglich, sondern **wirkliche Mehrfaktorauswertungen**. Das ist ein zentraler Vorteil des Modells.

## 2.2 Fachliche Schwächen / Risiken im aktuellen Konzept

### A. Recovery Score aktuell zu grob
Die aktuell vorgesehene Recovery-Logik (HRV vs. 7-Tage-Mittel, RHR invertiert, Schlafqualität) ist als Startpunkt brauchbar, aber fachlich zu fragil für harte Entscheidungen.

Probleme:
- HRV ist stark mess- und tagesformabhängig.
- Ein bloßer Quotient gegen den 7-Tage-Mittelwert ist ausreißeranfällig.
- Es fehlt eine **Messqualitätslogik**.
- Es fehlt eine **individuelle Normalzone** statt reinem Durchschnitt.
- Es fehlt eine **Kontextlogik** für Schlafschuld, Vorbelastung und Messlücken.

### B. Trainingsqualität darf nicht HR-zentriert sein
Die vorhandene `quality_label`-Logik ist für Cardio sinnvoll, aber nicht für alle Trainingstypen. Krafttraining, Mobility, Meditation oder Techniktraining dürfen nicht primär an Avg-HR/Max-HR gemessen werden.

### C. BMI nur als Nebenindikator
BMI kann angezeigt werden, sollte aber im System **nicht dominant** interpretiert werden, wenn bereits BF%, LBM und Umfänge vorliegen.

### D. Korrelationen nicht als simples Pearson auf Rohzeitreihen
Reine Pearson-Korrelationen auf gleitenden Alltagsdaten können bei Trends, Saisonmustern und Lags irreführend sein. Für Trainings- und Ernährungsdaten sind **Verzögerungen (lags)**, Detrending und Mindeststichproben deutlich robuster.

### E. Zielbezug fehlt noch als Steuerungszentrum
Fachlich entscheidend ist ein expliziter `goal_mode`, der Score-Gewichtung, Diagramm-Priorisierung und Textbewertung steuert.

---

## 3. Zwingende Analyse-Prinzipien für alle Diagramme und Scores

Diese Regeln sollten global gelten.

## 3.1 Analysefenster
Für fast alle Kennzahlen sollten parallel drei Ebenen geführt werden:
- **kurzfristig:** 7 Tage
- **mittelfristig:** 28 Tage
- **langfristig:** 90 Tage

Empfehlung:
- 7 Tage = Tagesform / Reaktion
- 28 Tage = Verhalten / Adhärenz
- 90 Tage = echte Entwicklung

## 3.2 Mindestdatenmenge / Confidence
Jede Auswertung bekommt eine **Confidence-Klasse**:
- **hoch** = ausreichend Daten, wenig Lücken, mehrere Messpunkte
- **mittel** = brauchbar, aber eingeschränkt
- **niedrig** = nur orientierend
- **nicht auswertbar** = Datenbasis zu klein

Default-Regeln:
- 7d-Auswertung nur ab **mind. 4 gültigen Tagen**
- 28d-Auswertung nur ab **mind. 18 gültigen Tagen**
- 90d-Auswertung nur ab **mind. 60 gültigen Tagen**
- Korrelationen nur ab **mind. 21 gepaarten Tageswerten**
- lag-basierte Korrelationen nur ab **mind. 28 gepaarten Tagen**

## 3.3 Ausreißerbehandlung
Für Gewicht, HRV, RHR, Blutdruck, Schlaf und Ernährung sollten extreme Einzelwerte nicht direkt in Scores laufen.

Empfehlung:
- primär **Rolling Median** oder **EWMA** für Trenddarstellung
- Ausreißererkennung per **Hampel Filter** oder Winsorizing
- Rohwert bleibt sichtbar, geht aber nicht ungefiltert in Score-Berechnung

## 3.4 Individuelle Baselines statt nur Normwerte
Für Sport- und Recovery-Daten sind **intraindividuelle Baselines** oft wichtiger als Populationsnormen.

Empfehlung:
- HRV, RHR, Schlafdauer, Blutdruck, Gewicht, Trainingsvolumen immer gegen
  - 7d Trend
  - 28d Baseline
  - optional 90d Baseline
  vergleichen

## 3.5 Lags immer mitdenken
Viele Effekte sind verzögert:
- Kalorienbilanz → Gewicht oft mit 2–14 Tagen Verzögerung
- Protein / Krafttraining → LBM eher mit 2–6 Wochen Verzögerung
- Trainingslast → HRV/RHR häufig mit 1–3 Tagen Verzögerung
- Schlafdefizit → Recovery / Leistung typischerweise 1–3 Tage verzögert

Darum sollen Korrelationen nie nur `lag=0` prüfen.

## 3.6 Medizinischer Sicherheitsmodus
Gesundheitsnahe Kennzahlen müssen in drei Schichten bewertet werden:
- **Info**
- **Hinweis**
- **Abklärung empfohlen**

Das System darf motivieren und priorisieren, aber **nicht diagnostizieren**.

---

## 4. Zusätzliche Felder, die fachlich sehr sinnvoll wären

Diese Felder sind nicht zwingend für die erste Umsetzung, würden aber die Qualität stark erhöhen:

### Pflichtnah für Phase 2
- `goal_mode` (weight_loss, strength, endurance, recomposition, health)
- `secondary_goals[]`
- `goal_priority_weights`
- `training_age` / Trainingserfahrung
- `measurement_time_consistency` (z. B. Gewicht morgens nüchtern ja/nein)
- `illness_flag`
- `travel_flag`
- `competition_flag`

### Sehr wertvoll
- subjektive Belastung / `session_rpe`
- subjektive Müdigkeit / `fatigue_score`
- subjektive Schlafqualität, wenn Gerätedaten fehlen
- Schrittzahl / Alltagsbewegung
- geschätzter Grundumsatz / TDEE
- Taillenumfang-zu-Körpergröße (`waist_to_height_ratio`)
- standardisierte Blutdruck-Heimmessung-Markierung

Ohne diese Felder bleiben einige Interpretationen möglich, aber weniger präzise.

---

## 5. Ziel-Modi und ihre Wirkung auf Diagramme und Scores

## 5.1 Ziel-Modi

```yaml
goal_modes:
  weight_loss:
    focus: [fettmasse, gewichtstrend, kalorienbilanz, protein_sicherung, aktivitaetsvolumen, schlaf]
  strength:
    focus: [trainingsqualitaet, protein, lbm, recovery, progressionslogik, schlaf]
  endurance:
    focus: [trainingsvolumen, intensitaetsverteilung, vo2max, recovery, schlaf, energieverfuegbarkeit]
  recomposition:
    focus: [lbm, fettmasse, protein, trainingsqualitaet, kalorienbalance, schlaf]
  health:
    focus: [bewegung, blutdruck, schlaf, gewicht, taille, regelmaessigkeit, moderates trainingsvolumen]
```

## 5.2 Score-Gewichtung je Ziel

```yaml
score_weights:
  weight_loss:
    body_progress: 0.30
    nutrition: 0.25
    activity: 0.20
    recovery: 0.15
    health_risk: 0.10
  strength:
    body_progress: 0.20
    nutrition: 0.25
    activity: 0.30
    recovery: 0.20
    health_risk: 0.05
  endurance:
    body_progress: 0.10
    nutrition: 0.20
    activity: 0.35
    recovery: 0.25
    health_risk: 0.10
  recomposition:
    body_progress: 0.30
    nutrition: 0.25
    activity: 0.25
    recovery: 0.15
    health_risk: 0.05
  health:
    body_progress: 0.20
    nutrition: 0.20
    activity: 0.20
    recovery: 0.20
    health_risk: 0.20
```

---

## 6. Kategoriemodell für Visualisierungen

Die Diagramme werden in vier Hauptgruppen ausgeliefert:
- **Körper**
- **Ernährung**
- **Aktivität**
- **Korrelation**

Jede Visualisierung erhält:
- `chart_id`
- `category`
- `title`
- `purpose`
- `required_fields`
- `optional_fields`
- `derived_metrics`
- `aggregation`
- `default_range`
- `goal_relevance`
- `interpretation_rules`
- `recommendation_rules`
- `confidence_logic`

---

## 7. Diagrammkatalog – KÖRPER

## K1. Gewichtstrend + Trendkanal + Zielprojektion

**Typ:** Linienchart mit Trendband  
**Ziel:** echte Entwicklung statt Tagesrauschen sichtbar machen

**Einzubeziehende Werte**
- `weight.value`
- Profilgröße für BMI optional
- Zielgewicht
- Startgewicht

**Berechnungen**
- Tagesgewicht (Rohwerte)
- 7d Rolling Median
- 28d Trend-Slope
- 90d Trend-Slope
- Zielprojektion auf Basis 28d-Trend
- prozentuale Zielannäherung

**Aussagen**
- Gewicht sinkt/stagniert/steigt
- Trend ist stabil oder volatil
- aktuelles Tempo ist schneller/langsamer als nachhaltiger Zielkorridor

**Regelbasierte Hinweise**
- bei Gewichtsreduktion: Warnung, wenn 28d-Trend = flach und dokumentierte Energiebilanz im Defizit
- Hinweis, wenn Gewichtsverlust sehr schnell ist und gleichzeitig LBM sinkt
- Hinweis auf Messrauschen, wenn Tagesvolatilität hoch, aber 28d-Trend stabil

**Coding-Hinweis**
- Rohwerte immer mit anzeigen, aber Standardfokus auf geglättetem Trend

---

## K2. Körperzusammensetzung: Gewicht vs. Fettmasse vs. Magermasse

**Typ:** kombinierter Linienchart oder gestapelter Flächenchart  
**Ziel:** Gewichtsänderung in Bestandteile zerlegen

**Einzubeziehende Werte**
- Gewicht
- BF%
- FM
- LBM

**Berechnungen**
- FM = Gewicht × BF%
- LBM = Gewicht × (1 - BF%)
- 28d- und 90d-Änderung von FM und LBM

**Aussagen**
- Gewichtsverlust stammt überwiegend aus Fettmasse
- Gewichtsverlust geht mit LBM-Verlust einher
- Gewicht bleibt stabil, aber Rekomposition liegt vor

**Regelbasierte Hinweise**
- positiv bei Gewichtsreduktion/Rekomposition: FM runter, LBM stabil
- kritisch bei Kraftziel: LBM sinkt trotz Training/Protein
- positiv bei Kraftziel: LBM steigt bei stabiler oder leicht sinkender FM

**Wichtig**
- BF%-Messungen via Caliper sind nützlich, aber messfehleranfällig; deshalb Confidence reduzieren, wenn Messfrequenz niedrig oder Abstände stark unregelmäßig sind

---

## K3. Umfangs-Panel als Small Multiples

**Typ:** 8 Mini-Liniencharts statt Radar als Standard  
**Ziel:** lokale Veränderungen sichtbar machen

**Einzubeziehende Werte**
- chest
- waist
- hip
- arm
- thigh_l / thigh_r
- calf_l / calf_r

**Berechnungen**
- 28d und 90d Delta je Umfang
- links-rechts Asymmetrie bei Bein/Wade
- optional Verhältnis Taille/Hüfte
- optional Taille/Körpergröße

**Aussagen**
- zentrale Adiposität verändert sich
- Muskelaufbau eher Oberkörper/Arme/Beine
- Asymmetrien wachsen oder sinken

**Regelbasierte Hinweise**
- Gewichtsverlust ohne sinkende Taille = möglicher Hinweis auf Wasser-/Mess- oder Adhärenzthema
- Taillenumfang sinkt trotz stabilem Gewicht = sehr positives Signal für Rekomposition
- starke Seitendifferenz = Asymmetrie-Hinweis

---

## K4. Rekompositions-Detektor

**Typ:** Quadranten-Chart  
**X-Achse:** 28d Δ FM  
**Y-Achse:** 28d Δ LBM

**Quadrantenlogik**
- **optimal recomposition:** FM runter, LBM rauf
- **cut with risk:** FM runter, LBM runter
- **bulk / gain:** FM rauf, LBM rauf
- **unfavorable:** FM rauf, LBM runter

**Ziel:** schnelle Interpretation komplexer Körperveränderung

**Einsatz:** besonders stark für Mischziele

---

## K5. Body Progress Score (0–100)

**Typ:** Score + Sparklines  
**Ziel:** Zielbezogene Gesamtbewertung der Körperentwicklung

**Komponenten je Zielmodus**

```yaml
body_progress_score:
  weight_loss:
    fm_change: 0.40
    waist_change: 0.25
    weight_trend: 0.20
    lbm_preservation: 0.15
  strength:
    lbm_change: 0.45
    arm_thigh_change: 0.20
    weight_trend: 0.10
    bf_stability: 0.10
    waist_stability: 0.15
  recomposition:
    fm_change: 0.35
    lbm_change: 0.35
    waist_change: 0.20
    weight_neutrality: 0.10
```

**Regel**
- Score nur anzeigen, wenn in den letzten 28 Tagen ausreichende Körperdaten vorliegen

---

## 8. Diagrammkatalog – ERNÄHRUNG

## E1. Energieaufnahme vs. geschätzter Energieverbrauch vs. Gewichtstrend

**Typ:** kombinierter Linien-/Balkenchart  
**Ziel:** Energielogik in Relation zum Gewicht sichtbar machen

**Einzubeziehende Werte**
- Kalorienaufnahme täglich
- Trainingskalorien
- optional geschätzter Grundumsatz / TDEE
- Gewichtstrend

**Berechnungen**
- tägliche Aufnahme
- 7d Durchschnitt Aufnahme
- Energieüberschuss/-defizit
- 7d geglättete Bilanz
- lagged comparison zur Gewichtsentwicklung (3d, 7d, 14d)

**Aussagen**
- Bilanz passt nicht zur Gewichtsrealität
- Wochenendeffekt vorhanden
- Intake ist hoch volatil

**Regelbasierte Hinweise**
- Gewicht sinkt nicht trotz dokumentiertem Defizit → Messlücke, Verbrauchsüberschätzung oder kurze Beobachtungsdauer möglich
- anhaltend großes Defizit + Recovery-Verschlechterung → Belastungshinweis
- deutliche Intake-Volatilität → Adhärenz-Hinweis

**Wichtige fachliche Anmerkung**
Trainingskalorien aus Wearables sind ungenau. Für Scores sollten sie mit geringerer Priorität eingehen als dokumentierte Zufuhr und Gewichtsrealität.

---

## E2. Protein adequacy chart (g/Tag, g/kg KG, optional g/kg LBM)

**Typ:** Linienchart mit Zielband  
**Ziel:** Protein nicht nur absolut, sondern relativ interpretieren

**Einzubeziehende Werte**
- Protein g
- Körpergewicht
- optional LBM
- Zielmodus

**Berechnungen**
- Protein absolut
- Protein g/kg Körpergewicht
- optional Protein g/kg LBM
- 7d und 28d Mittel
- Tage im Zielbereich

**Default-Referenzlogik**
- allgemeine Aktivität / Gewichtsreduktion: individueller Zielkorridor konfigurierbar
- Kraft/Rekomposition: höherer Zielkorridor
- App-seitig als konfigurierbare Logik aufsetzen, nicht als starren globalen Wert

**Mindestfachliche Defaults**
- für trainierende Personen ist höhere Proteinzufuhr als bei Inaktiven sinnvoll
- pro Mahlzeit bzw. Portion sind 20–40 g bzw. etwa 0,25 g/kg hochwertige Proteinmenge ein belastbarer Referenzanker

**Regelbasierte Hinweise**
- Kraftziel + Protein an <4 Tagen/Woche im Zielband → Protein-Hinweis
- Defizitphase + Protein unter Zielband → Hinweis auf erhöhtes LBM-Verlustrisiko

---

## E3. Makroverteilung und Wochenkonsistenz

**Typ:** 100%-gestapelter Wochenbalken + Streuungsindikator  
**Ziel:** weniger „Makro-Schönheit“, mehr Verhaltenskonsistenz

**Einzubeziehende Werte**
- Protein
- Fett
- Kohlenhydrate
- Kalorien
- optional Zucker
- optional Ballaststoffe

**Berechnungen**
- Wochenmittel je Makro
- Variationskoeffizient
- Wochenende vs. Werktag

**Aussagen**
- stark schwankende Ernährung
- proteinarm an Belastungstagen
- hoher Zuckerschwerpunkt bei gleichzeitig niedrigem Ballaststoffniveau

**Regelbasierte Hinweise**
- bei Gesundheit/Zielreduktion: hoher Zucker + niedrige Ballaststoffe → Qualitäts-Hinweis
- bei Ausdauer: Kohlenhydrate an Belastungstagen zu niedrig → Performance-Hinweis

---

## E4. Ernährungs-Adhärenz-Score (0–100)

**Typ:** Scorecard  
**Ziel:** nicht die „perfekte Ernährung“, sondern Zieltreue messen

**Komponenten**

```yaml
nutrition_score:
  weight_loss:
    calorie_target_adherence: 0.35
    protein_target_adherence: 0.25
    intake_consistency: 0.20
    fiber_or_food_quality: 0.10
    sugar_control: 0.10
  strength:
    protein_target_adherence: 0.35
    calorie_support: 0.25
    intake_consistency: 0.20
    carb_support_on_training_days: 0.20
  endurance:
    energy_adequacy: 0.30
    carb_support: 0.30
    protein_adequacy: 0.20
    intake_consistency: 0.20
```

**Hinweis**
Ballaststoffe und Zucker nur dann relevant gewichten, wenn Datenqualität ausreichend ist.

---

## E5. Energieverfügbarkeits-Warnung (heuristisch, klar als Heuristik markieren)

**Typ:** Ampel / Warnkarte  
**Ziel:** Unterversorgung erkennen, ohne klinische Diagnose zu behaupten

**Einzubeziehende Werte**
- Kalorienaufnahme
- Trainingskalorien
- Gewichtstrend
- Recovery Score
- Schlaf
- ggf. LBM

**Heuristische Trigger**
- anhaltendes großes Defizit über mehrere Tage/Wochen
- Recovery sinkt gleichzeitig
- Schlaf verschlechtert sich gleichzeitig
- LBM sinkt gleichzeitig

**Ausgabe**
- „mögliche Unterversorgung / zu aggressives Defizit“
- keine Diagnoseformulierung

---

## 9. Diagrammkatalog – AKTIVITÄT

## A1. Trainingsvolumen pro Woche

**Typ:** gestapelte Wochenbalken  
**Ziel:** Umfang und Mix sichtbar machen

**Einzubeziehende Werte**
- Dauer
- Trainingskalorien
- Trainingstyp
- quality_label

**Berechnungen**
- Einheiten pro Woche
- Minuten pro Woche
- Minuten je Kategorie
- Anteil qualitativ brauchbarer Sessions

**Aussagen**
- Training ist regelmäßig oder sprunghaft
- relevante Kategorien fehlen
- „viel trainiert“ vs. „viel dokumentiert, aber wenig qualitativ“

---

## A2. Intensitätsverteilung / Zonenbild

**Typ:** gestapelter Flächenchart oder Wochenbalken  
**Ziel:** Intensitätsmuster sichtbar machen

**Einzubeziehende Werte**
- HR-Zonen-Verteilung, sobald vorhanden
- bis dahin: `avg_hr`, `max_hr`, `quality_label`, Trainingstyp

**Fallback-Logik ohne echte Zonen**
- Proxy-Intensität in 3 Stufen:
  - niedrig
  - moderat
  - hoch
- Ableitung aus Kombination von Dauer, avg_hr, max_hr und Typ

**Aussagen**
- Ausdauerziel: zu wenig Grundlagentraining oder zu viel harte Belastung
- Gesundheit: Bewegung vorhanden, aber kaum moderat/vigorous
- Kraftziel: hohe HR ist kein Muss, daher Zonen nur begrenzt gewichten

---

## A3. Trainingsqualitäts-Matrix

**Typ:** Heatmap  
**Achsen:** Woche × Trainingstyp  
**Ziel:** Qualität nicht nur als Einzelbadge, sondern als Muster darstellen

**Einzubeziehende Werte**
- training_type
- quality_label
- duration
- avg_hr / max_hr optional

**Darstellung**
- Zellenfarbe = mittlere Qualitätsstufe
- Zellgröße optional = Anzahl Sessions

**Nutzen**
- zeigt, ob bestimmte Typen regelmäßig unter Mindestqualität bleiben
- sehr gut für Coaching und Programmsteuerung

---

## A4. Fähigkeiten-Balance / Ability Radar

**Typ:** Radar + Zeittrend  
**Ziel:** zeigen, welche Entwicklungsdimensionen systematisch trainiert werden

**Einzubeziehende Werte**
- `training_types.abilities`
- Aktivitäten
- Dauer / Qualität

**Berechnungen**
- wöchentlicher Ability Load je Dimension
- geglätteter 28d-Wert
- Balance-Index

**Dimensionen**
- Kraft
- Ausdauer
- Mental
- Koordination
- Mobilität

**Aussagen**
- Training ist einseitig
- Mobilität/Mental fehlen
- gute Balance oder starke Spezialisierung

**Regelbasierte Hinweise**
- bei Stagnation und sehr einseitiger Belastung → Balance-Hinweis
- bei Gesundheit/Zielbreite → zu schmale Bewegungsbasis

---

## A5. Load-Monitoring: interne Last, Monotony, Strain

**Typ:** Wochenchart mit Warnbändern  
**Ziel:** Belastungssteuerung sichtbar machen

**Wichtiger fachlicher Hinweis**
Da `session_rpe` aktuell fehlt, sollte ein **Proxy-Load** verwendet werden und klar als Proxy gekennzeichnet sein.

**Proxy-Load-Vorschlag**

```yaml
proxy_internal_load:
  formula: duration_min * intensity_factor * quality_factor
  intensity_factor:
    low: 1.0
    moderate: 1.5
    high: 2.0
  quality_factor:
    excellent: 1.15
    very_good: 1.05
    good: 1.0
    acceptable: 0.9
    poor: 0.75
    excluded: 0.0
```

**Darstellungen**
- Wochenlast
- Monotony = Wochenmittel / Wochen-Standardabweichung
- Strain = Wochenlast × Monotony

**Wichtiger Hinweis**
Monotony/Strain sind nützliche Coach-Metriken, aber **nicht als medizinische Wahrheit** interpretieren.

---

## A6. Aktivitäts-Goal-Alignment-Score (0–100)

**Typ:** Scorecard  
**Ziel:** Training im Verhältnis zum Nutzerziel bewerten

**Beispiel-Logik**

```yaml
activity_score:
  weight_loss:
    weekly_minutes: 0.25
    frequency: 0.20
    quality_sessions: 0.20
    strength_presence: 0.15
    activity_consistency: 0.20
  strength:
    strength_session_presence: 0.35
    quality_strength_sessions: 0.25
    recovery_respect: 0.15
    supportive_cardio: 0.10
    consistency: 0.15
  endurance:
    weekly_minutes: 0.25
    intensity_distribution: 0.25
    frequency: 0.20
    load_progression: 0.15
    recovery_respect: 0.15
```

---

## A7. Ruhetags-/Recovery-Compliance

**Typ:** Kalender-Heatmap  
**Ziel:** zeigen, ob Belastung und Erholung zusammenpassen

**Einzubeziehende Werte**
- geplante Ruhetage
- tatsächliche Aktivitäten
- Recovery Score
- Schlafschuld

**Aussagen**
- Ruhetag wird respektiert oder regelmäßig „durchtrainiert“
- schlechte Recovery trotz fehlender Ruhetage
- unnötig viele Ruhetage bei Leistungsziel

---

## A8. VO2max-Entwicklung

**Typ:** Linienchart  
**Ziel:** kardiorespiratorische Entwicklung sichtbar machen

**Einzubeziehende Werte**
- VO2max
- Aktivitätsvolumen
- Intensitätsverteilung
- Ruhepuls optional

**Regelbasierte Hinweise**
- steigendes Volumen ohne VO2max-Fortschritt → Programm-/Intensitätsfrage
- sinkende VO2max + sinkende Aktivität → Deconditioning-Hinweis
- bei Kraftziel nur sekundär priorisieren

---

## 10. Diagrammkatalog – KORRELATIONEN / KOMPLEXE ZUSAMMENHÄNGE

## Grundsatz
Korrelationen müssen **explizit als explorativ** gekennzeichnet sein. Sie zeigen Hinweise, keine Beweise.

Jeder Korrelationschart bekommt:
- Effektstärke
- Vorzeichen
- bestes Lag-Fenster
- Datenanzahl
- Confidence
- Text: „Hinweis“, nicht „Ursache“

---

## C1. Energie-Balance vs. Gewichtsveränderung (lagged)

**Typ:** Lag-Heatmap oder Cross-Correlation Panel  
**Ziel:** erkennen, nach wie vielen Tagen Energiebilanz und Gewicht am plausibelsten zusammenlaufen

**Einzubeziehende Werte**
- tägliche Kalorienbilanz
- 7d Gewichtsänderung

**Lags**
- 0, 3, 7, 10, 14 Tage

**Ausgabe**
- bestes Lag
- Richtung des Zusammenhangs
- Confidence

**Nutzen**
- deutlich besser als einfache Same-Day-Pearson-Korrelation

---

## C2. Protein adequacy vs. LBM-Trend

**Typ:** Scatter + Trend + 28d Fenstervergleich  
**Ziel:** erkennen, ob Proteinversorgung mit Magermasse-Stabilität oder -Anstieg einhergeht

**Einzubeziehende Werte**
- Protein g/kg
- LBM
- Krafttrainingslast

**Hinweis**
Protein nie isoliert interpretieren; Training muss als Moderator mitgedacht werden.

---

## C3. Trainingslast vs. HRV/RHR (1–3 Tage verzögert)

**Typ:** duale Lag-Auswertung  
**Ziel:** individuelle Ermüdungsreaktion erkennen

**Einzubeziehende Werte**
- Proxy-Load / Volumen
- HRV
- RHR
- Schlaf

**Lags**
- 1, 2, 3 Tage

**Aussagen**
- hohe Last führt individuell eher zu HRV-Abfall / RHR-Anstieg
- keine klare Reaktion erkennbar
- Reaktion nur bei Schlafmangel ausgeprägt

---

## C4. Schlafdauer + Schlafregularität vs. Recovery

**Typ:** Bubble-/Quadrantenchart  
**Achsen:** Schlafdauer, Schlafregularität  
**Bubble:** Recovery Score

**Ziel:** zeigen, dass nicht nur Menge, sondern auch Regelmäßigkeit relevant ist

**Einzubeziehende Werte**
- Schlafdauer
- Bedtime/Waketime
- daraus Sleep Regularity Index oder einfacher Regularity Proxy
- Recovery Score

**Empfehlung**
Mindestens eine einfache Regularitätsmetrik ergänzen:

```yaml
sleep_regularity_proxy:
  inputs: [bedtime, waketime]
  metric: mean_absolute_shift_from_previous_day_minutes
  lower_is_better: true
```

Optional später:
- echter `Sleep Regularity Index (SRI)`

---

## C5. Blutdruck-Kontextmatrix vs. Schlaf / Training / Stress-naher Kontext

**Typ:** Matrix / Boxplots nach Kontext  
**Ziel:** nicht nur Höhe, sondern Situation verstehen

**Einzubeziehende Werte**
- systolisch
- diastolisch
- Puls
- Messkontext
- Schlaf der Vor-Nacht
- Training am selben / Vortag

**Aussagen**
- Blutdruck morgens systematisch höher
- Training scheint akut positiv/neutral/negativ assoziiert
- Stress-Kontexte sind Ausreißerträger

**Medizinischer Hinweis**
Das System soll hier eher **Screening-/Monitoring-Logik** abbilden, nicht Diagnose.

---

## C6. Plateau-Detektor

**Typ:** Ereignis-Karte / Warnpanel  
**Ziel:** „viel Einsatz, wenig Fortschritt“ identifizieren

**Plateau-Definitionen je Zielmodus**

```yaml
plateau_logic:
  weight_loss:
    condition:
      - 28d_weight_slope_flat
      - waist_change_small
      - adherence_high
  strength:
    condition:
      - activity_score_high
      - lbm_change_flat
      - recovery_low_or_variable
  endurance:
    condition:
      - volume_high
      - vo2max_flat
      - monotony_high
```

**Ausgabe**
- Plateau wahrscheinlich / möglich / nicht erkennbar
- Top-3 plausible Einflussfaktoren

---

## C7. Multi-Faktor Driver Panel

**Typ:** priorisierte Einflusskarten  
**Ziel:** ohne KI eine „Top-Treiber“-Ansicht erzeugen

**Mechanik**
Das System bewertet für ein Ziel die wichtigsten beeinflussbaren Faktoren regelbasiert:
- Energie
- Protein
- Schlafdauer
- Schlafregelmäßigkeit
- Trainingskonsistenz
- Qualitätsanteil
- Recovery
- Ruhetagsrespekt

**Ausgabe pro Faktor**
- Status: förderlich / neutral / hinderlich
- Evidenz: hoch / mittel / niedrig
- Begründung: 1 Satz

Das ist eine sehr starke Brücke zur späteren KI-Stufe.

---

## 11. Zentrale Scores

## S1. Recovery / Readiness Score (verbesserte Version)

Die bestehende Idee ist gut, sollte aber robuster umgesetzt werden.

### Eingangswerte
- HRV vs. 28d Baseline
- RHR vs. 28d Baseline
- Schlafdauer vs. Ziel
- Schlafschuld
- Schlafregularität
- Vorbelastung 1–3 Tage
- Messqualität / Datenvollständigkeit

### Empfohlene Logik
Nicht rohe Quotienten, sondern normalisierte Abweichungszonen.

```yaml
recovery_score:
  components:
    hrv_status: 0.25
    rhr_status: 0.20
    sleep_duration: 0.20
    sleep_debt: 0.10
    sleep_regularity: 0.10
    recent_load_balance: 0.10
    data_quality: 0.05
  output:
    0_39: low
    40_59: strained
    60_79: normal
    80_100: ready
```

### Zusätzliche Regeln
- Kein Score bei zu wenigen validen Datenpunkten
- Fallback-Modus ohne HRV möglich
- Separate Anzeige „Messqualität“

---

## S2. Health Risk / Health Stability Score

**Typ:** Score 0–100  
**Ziel:** allgemeine Gesundheitsstabilität abbilden

**Komponenten**
- Blutdruckstatus
- Schlafbasis
- Bewegungsbasis
- Gewicht/Umfangsrisiko
- Regelmäßigkeit

**Hinweis**
Dieser Score ist für allgemeine Gesundheit sehr sinnvoll, aber für Leistungssport sekundär.

---

## S3. Goal Progress Score (Meta-Score)

**Typ:** Zielabhängiger Gesamtscore  
**Formel:** gewichtete Summe aus Body, Nutrition, Activity, Recovery, Health Risk

**Regeln**
- nie ohne Teilscore-Transparenz anzeigen
- immer mit Treiberaufschlüsselung
- nie als „Gesundheitsnote“ formulieren

---

## S4. Data Quality Score

**Typ:** technischer Fachscore  
**Ziel:** schlechte Daten nicht mit scheinbarer Präzision interpretieren

**Komponenten**
- Messhäufigkeit
- Regelmäßigkeit
- Lücken
- Konsistenz
- Anzahl gepaarter Datenpunkte für Korrelationen

Dieser Score ist extrem wichtig. Ohne ihn werden schlechte Daten zu scheinbar präzisen Aussagen führen.

---

## 12. Regelbasierte Aussagen und Empfehlungen ohne KI

Die Formulierungen sollten knapp, neutral und nachvollziehbar sein.

## 12.1 Beispiel-Statements – Gewichtsreduktion

### Positiv
- „Dein 28-Tage-Trend zeigt eine stabile Gewichtsabnahme innerhalb eines nachhaltigen Bereichs.“
- „Der Taillenumfang sinkt parallel zum Gewicht. Das spricht für echten Fortschritt.“
- „Die Magermasse ist trotz Defizit stabil. Das ist in einer Reduktionsphase ein gutes Signal.“

### Neutral / Beobachtung
- „Die Tageswerte schwanken deutlich, der 28-Tage-Trend ist aber nahezu stabil.“
- „Die dokumentierte Kalorienbilanz spricht für ein Defizit, das Gewicht reagiert bisher aber nur schwach.“

### Kritisch
- „Die Magermasse sinkt parallel zur Gewichtsabnahme. Prüfe Defizithöhe, Protein und Krafttraining.“
- „Der Gewichtsverlauf stagniert seit 4 Wochen trotz hoher Dokumentationsrate.“
- „Das Defizit wirkt im Verhältnis zu Recovery und Schlaf aktuell eher aggressiv.“

## 12.2 Beispiel-Statements – Kraftaufbau
- „Dein Trainingsmuster ist konsistent, die Körperdaten zeigen aber noch keinen klaren LBM-Anstieg.“
- „Die Proteinzufuhr liegt an mehreren Tagen unter dem Zielbereich für dein Kraftziel.“
- „Recovery und Schlaf sprechen aktuell gegen weitere Steigerung der Trainingslast.“
- „Deine Ability-Balance ist stark kraftlastig, Mobilität und Regeneration sind schwach ausgeprägt.“

## 12.3 Beispiel-Statements – Ausdauer
- „Die Wochenminuten steigen, aber die Intensitätsverteilung ist unausgeglichen.“
- „VO2max verbessert sich trotz Trainingsvolumen derzeit nicht sichtbar.“
- „Die letzten Wochen zeigen hohe Monotonie. Das spricht für wenig Variation in der Belastung.“

## 12.4 Beispiel-Statements – Gesundheit
- „Dein Schlaf liegt wiederholt unter 7 Stunden und ist unregelmäßig.“
- „Die Bewegung erfüllt den Mindestrahmen teilweise, Kraftreize fehlen jedoch.“
- „Deine Blutdruckwerte sollten im Verlauf enger beobachtet werden, insbesondere im Morgenkontext.“

---

## 13. Medizinische und fachliche Grenzlogik

## 13.1 Bewegung
Für erwachsene Personen sind als allgemeiner Gesundheitsrahmen mindestens **150–300 Minuten moderate** oder **75–150 Minuten intensive** Aktivität pro Woche plus **Muskelkräftigung an mindestens 2 Tagen/Woche** ein sinnvoller Referenzrahmen. Dieser Rahmen ist für die Kategorie „Gesundheit“ wichtig, aber nicht automatisch Leistungsoptimum. [R1]

## 13.2 Schlaf
Für Erwachsene ist **7+ Stunden Schlaf pro Nacht** ein belastbarer allgemeiner Mindestanker. Schlafdauer allein reicht aber nicht; Regelmäßigkeit und Qualität sind zusätzlich relevant. [R2][R8][R9]

## 13.3 Protein
Für Trainierende ist eine relativ höhere Proteinzufuhr fachlich sinnvoll; als gut belastbare Referenz für die Darstellung eignen sich **20–40 g pro Proteinportion** oder etwa **0,25 g/kg pro Portion**. Tagesziele sollten zielabhängig und konfigurierbar sein. [R3]

## 13.4 Blutdruck
Die App sollte sich in der Darstellung am aktuellen europäischen Begriffsrahmen orientieren: **elevated BP** bei Büro-/Praxiswerten **120–139 systolisch oder 70–89 diastolisch**, Hypertonie wie bisher ab **≥140/90 mmHg**. Für die App heißt das: Verlauf und Kontext zeigen, aber Diagnose vermeiden. [R4]

## 13.5 Trainingslast
Trainingsmonitoring ist fachlich sinnvoll, aber nie mit nur einer Kennzahl. Deshalb sollten Last, Erholung, Schlaf und Ziel-Fortschritt immer gemeinsam interpretiert werden. [R5]

---

## 14. Priorisierte Umsetzungsreihenfolge

## Phase 1 – sofort umsetzen
1. Gewichtstrend + Zielprojektion
2. Gewicht/FM/LBM-Chart
3. Umfangs-Panel
4. Energieaufnahme vs. Gewichtstrend
5. Protein adequacy chart
6. Trainingsvolumen pro Woche
7. Trainingsqualitäts-Matrix
8. Recovery Score verbessert
9. Goal Progress Score
10. einfache Korrelationen mit Confidence und Mindestdatenlogik

## Phase 2 – stark empfohlen
1. Sleep Regularity Proxy
2. Lag-Korrelationen
3. Plateaudetektor
4. Driver Panel
5. Health Stability Score
6. Ability-Balance-Radar
7. Ruhetags-/Recovery-Compliance

## Phase 3 – Vorbereitung für KI
1. Feature Store je 7/28/90 Tage
2. erklärbare Vorstufen-Texte aus Regeln
3. Ereignismarker (Infekt, Reise, Wettkampf, Stressphasen)
4. subjektive Daten (RPE, Müdigkeit, Schmerz, Motivation)

---

## 15. Konkrete technische Spezifikation für den Coding Agent

## 15.1 Chart Definition Contract

```json
{
  "chart_id": "K1_weight_trend",
  "category": "body",
  "title": "Gewichtstrend + Zielprojektion",
  "purpose": "Tagesrauschen von echter Entwicklung trennen",
  "required_fields": ["weight.date", "weight.value", "profile.target_weight"],
  "optional_fields": ["profile.height_cm"],
  "derived_metrics": [
    "weight_7d_median",
    "weight_28d_slope",
    "weight_90d_slope",
    "goal_projection_date",
    "goal_progress_pct"
  ],
  "default_range": "90d",
  "goal_relevance": ["weight_loss", "recomposition", "health"],
  "confidence_logic": {
    "7d_min_points": 4,
    "28d_min_points": 18,
    "90d_min_points": 60
  },
  "interpretation_rules": [
    "stable_downward_trend",
    "volatile_but_flat",
    "rapid_loss_with_lbm_drop"
  ],
  "recommendation_rules": [
    "review_deficit",
    "review_protein",
    "hold_course"
  ]
}
```

## 15.2 Statement Contract

```json
{
  "statement_id": "WL_rapid_loss_lbm_drop",
  "severity": "warning",
  "goal_modes": ["weight_loss", "recomposition"],
  "conditions": [
    "weight_28d_slope < -0.75_percent_per_week",
    "lbm_28d_change < -0.5kg",
    "nutrition_score < 70 OR protein_target_days_per_week < 4"
  ],
  "message": "Der Gewichtsverlust ist aktuell relativ schnell und geht mit sinkender Magermasse einher. Prüfe Defizithöhe, Protein und Kraftreize.",
  "confidence": "derived_from_data_quality"
}
```

## 15.3 Score Contract

```json
{
  "score_id": "goal_progress_score",
  "range": [0, 100],
  "goal_mode_dependent": true,
  "components": [
    "body_progress_score",
    "nutrition_score",
    "activity_score",
    "recovery_score",
    "health_risk_score"
  ],
  "weights_source": "config/goal_weights.yaml",
  "output": {
    "value": 78,
    "label": "gut",
    "drivers_positive": ["protein_adherence", "stable_weight_trend"],
    "drivers_negative": ["sleep_irregularity"]
  }
}
```

---

## 16. Fachliches Fazit

## Aus Perspektive der Datenanalyse
Ich würde das Modell klar als **mehrdimensional leistungsfähig** einstufen. Es ist weit über einem typischen Fitness-Tracker, weil es Körper, Training, Schlaf, Vitalwerte und Ernährung zusammenführt.

## Aus Perspektive eines Sportwissenschaftlers / Gesundheitsanalysten
Der größte Mehrwert entsteht nicht durch noch mehr Einzelmetriken, sondern durch:
- **zielabhängige Interpretation**
- **Baseline-Logik statt bloßer Rohwerte**
- **lag-basierte Zusammenhänge statt naiver Gleichzeitigkeit**
- **Confidence / Datenqualität**
- **klare Trennung zwischen Gesundheitsmonitoring, Performance und Heuristik**

## Zusammengeführt
Die beste Umsetzung ist **nicht** eine endlose Sammlung bunter Charts. Die beste Umsetzung ist ein System mit:
1. wenigen, starken Standardcharts,
2. robusten Scores,
3. erklärbaren Regeln,
4. einer sauberen Brücke zur späteren KI.

Wenn diese Struktur sauber umgesetzt wird, ist bereits ohne KI ein sehr hoher fachlicher Nutzen erreichbar.

---

## 17. Referenzbasis

**[R1]** ACSM / Physical Activity Guidelines: mindestens 150–300 min moderate oder 75–150 min intensive Aktivität pro Woche plus Muskelkräftigung an mindestens 2 Tagen/Woche.  
Quelle: ACSM, Physical Activity Guidelines FAQ  
https://acsm.org/physical-activity-guidelines-faqs/

**[R2]** AASM / Sleep Research Society: Erwachsene sollten regelmäßig 7 oder mehr Stunden pro Nacht schlafen.  
Quelle: AASM  
https://aasm.org/seven-or-more-hours-of-sleep-per-night-a-health-necessity-for-adults/

**[R3]** ISSN Position Stand Protein and Exercise: allgemeine Empfehlung pro Portion etwa 0,25 g/kg bzw. 20–40 g hochwertiges Protein; höhere Gesamtzufuhr bei Trainierenden oft sinnvoll.  
Quelle: Journal of the International Society of Sports Nutrition  
https://link.springer.com/article/10.1186/s12970-017-0177-8

**[R4]** ESC 2024 Guidelines: neue Kategorie „elevated BP“ 120–139 mmHg systolisch oder 70–89 mmHg diastolisch; Hypertonie weiterhin ab ≥140/90 mmHg.  
Quelle: European Society of Cardiology  
https://www.escardio.org/news/news-room/congress-news/2024-esc-clinical-practice-guidelines-for-the-management-of-elevated-blood-pressure-and-hypertension/

**[R5]** Athlete load monitoring soll als gemeinsamer Rahmen aus Last, Reaktion und Kontext verstanden werden, nicht als Einzelmetrik.  
Quelle: Monitoring Athlete Training Loads: Consensus Statement  
https://pubmed.ncbi.nlm.nih.gov/28463642/

**[R6]** Progressive resistance training muss zielgerichtet ausgestaltet werden; starre Einheitsregeln sind fachlich ungeeignet.  
Quelle: ACSM Position Stand – Progression Models in Resistance Training for Healthy Adults  
https://pubmed.ncbi.nlm.nih.gov/19204579/

**[R7]** Für Gewichtsreduktion gelten etwa 0,5–1,0 kg/Woche allgemein als sicher und nachhaltig, aber individualisiert.  
Quelle: NICE Overweight and Obesity Management  
https://www.nice.org.uk/guidance/ng246/resources/a-guide-for-prescribing-medicines-to-manage-overweight-and-obesity-15299628589/chapter/Prescribing-reviewing-and-stopping-tirzepatide

**[R8]** Schlafregularität ist als Gesundheitsfaktor eigenständig relevant und teils prädiktiver als bloße Schlafdauer.  
Quelle: Sleep regularity is a stronger predictor of mortality risk than sleep duration  
https://pubmed.ncbi.nlm.nih.gov/37738616/

**[R9]** Für die Messung von Schlafregularität sind mehrere Metriken möglich; Auswahl hängt von Studiendauer und Ziel ab.  
Quelle: Measuring sleep regularity: theoretical properties and practical usage of existing metrics  
https://pubmed.ncbi.nlm.nih.gov/33864369/


---

## 16. Ergänzung V2 – Trainingsqualitäts-Engine je Trainingstyp

Die neue Anforderung präzisiert einen zentralen Punkt des Gesamtsystems: **Trainingsqualität** wird pro **Trainingstyp** über definierbare Regeln ermittelt. Dabei können mehrere Messparameter kombiniert werden, und je Trainingstyp stehen unterschiedliche Berechnungsstrategien zur Verfügung:
- **Gewichteter Score**
- **Alle Regeln müssen erfüllt sein**
- **Mindestens N Regeln müssen erfüllt sein**

Diese Architektur ist fachlich sinnvoll, muss aber sauber modelliert werden, damit aus heterogenen Sensordaten kein irreführender Einheits-Score entsteht.

### 16.1 Fachliche Grundsätze

1. **Qualität ist nicht gleich Last.**  
   Dauer, Distanz, Puls, Leistung, Pace, RPE oder Kalorien beschreiben teils die externe Last, teils die interne Belastung und nur indirekt die „Qualität“. Darum sollte das System **drei getrennte Konzepte** führen:
   - `quality_score` = Wie gut erfüllt die Einheit die typ-spezifische Zielcharakteristik?
   - `load_score` = Wie hoch war der Trainingsreiz / die Belastung?
   - `confidence_score` = Wie belastbar ist die Bewertung auf Basis der verfügbaren Daten?

2. **Nicht jeder Parameter ist für jeden Trainingstyp sinnvoll.**  
   Avg-HR und Max-HR sind bei Laufen oder HIIT oft nützlich, bei Mobility, Technik, Meditation oder leichtem Krafttraining aber nur begrenzt aussagekräftig.  
   **Folge:** Jeder Trainingstyp erhält eine eigene Parameter-Matrix mit Relevanz, Pflichtstatus und Gewicht.

3. **Subjektive und objektive Daten sollen kombiniert, aber nicht vermischt werden.**  
   RPE liefert eine andere Information als HR, Pace oder Distanz und sollte deshalb als eigenständiger Marker behandelt werden.

4. **Regelbasierte Scoring-Engines sollten hybrid arbeiten.**  
   Rein gewichtete Modelle sind flexibel, aber anfällig für „falsche Positivbewertungen“. Reine `all_rules_must_pass`-Modelle sind oft zu hart. Fachlich am stabilsten ist meist ein **Hybrid aus Gates + eigentlicher Strategie**.

### 16.2 Empfohlene Architektur: 3-stufige Quality Engine

```yaml
training_quality_engine:
  stage_1_exclusion_gates:
    purpose: "Offensichtlich unbrauchbare oder falsch klassifizierte Sessions ausfiltern"
    examples:
      - duration_min < absolute_minimum
      - missing_all_primary_metrics == true
      - training_type_mismatch_flag == true
      - manually_marked_invalid == true

  stage_2_rule_evaluation:
    purpose: "Trainingstyp-spezifische Qualitätsbewertung"
    supported_strategies:
      - weighted_score
      - all_rules_must_pass
      - at_least_n_rules

  stage_3_labeling_and_confidence:
    purpose: "Normierung, Qualitätslabel, Datenvertrauen"
    outputs:
      - quality_score_0_100
      - quality_label
      - rules_passed_count
      - rules_total_count
      - confidence_score_0_100
      - confidence_label
```

### 16.3 Empfohlene Outputs pro Einheit

```yaml
activity_quality_result:
  quality_score: 0-100
  quality_label: [excellent, very_good, good, acceptable, poor, excluded]
  confidence_score: 0-100
  confidence_label: [high, medium, low]
  strategy_used: [weighted_score, all_rules_must_pass, at_least_n_rules]
  rules_passed_count: integer
  rules_total_count: integer
  mandatory_rules_passed: boolean
  parameter_breakdown:
    - parameter_key
    - raw_value
    - normalized_score_0_100
    - weight
    - passed
    - relevance
    - reason
  exclusion_reason: nullable
```

### 16.4 Datenmodell für Regeln je Trainingstyp

Empfehlung: Die Quality Rules im Trainingstyp nicht mehr nur als einfache Minima speichern, sondern als vollständige Regelobjekte.

```yaml
training_type_quality_config:
  strategy: weighted_score
  min_rules_required: null
  mandatory_gate_mode: any_fail_excludes
  missing_data_policy: renormalize_non_missing
  label_thresholds:
    excellent: 90
    very_good: 80
    good: 65
    acceptable: 50
    poor: 1
    excluded: 0

  parameters:
    - key: duration_min
      source: duration
      comparator: range
      unit: min
      required: true
      mandatory: true
      weight: 0.20
      min: 30
      max: 75
      tolerance_below: 10
      tolerance_above: 20
      scoring_curve: trapezoid

    - key: avg_hr
      source: avg_heart_rate
      comparator: range_relative_to_hrmax
      unit: bpm
      required: false
      mandatory: false
      weight: 0.20
      min_pct_hrmax: 0.70
      max_pct_hrmax: 0.85
      scoring_curve: trapezoid

    - key: rpe
      source: rpe
      comparator: range
      unit: borg_cr10
      required: false
      mandatory: false
      weight: 0.15
      min: 5
      max: 7
      scoring_curve: trapezoid
```

### 16.5 Unterstützte Regeltypen / Comparatoren

Die Engine sollte mindestens diese Comparatoren unterstützen:

```yaml
comparators:
  - min                # Wert muss >= Grenzwert sein
  - max                # Wert muss <= Grenzwert sein
  - range              # Wert innerhalb eines Bereichs
  - target             # Zielwert, Score sinkt mit Abstand
  - range_relative_to_hrmax
  - range_relative_to_resting_hr
  - range_relative_to_baseline
  - ratio_min
  - ratio_max
  - boolean_true
  - derived_formula
```

### 16.6 Sinnvolle Scoring-Kurven

Nicht jede Regel sollte nur binär bewertet werden. Für die meisten Trainingsdaten sind **weiche Übergänge** fachlich besser.

```yaml
scoring_curves:
  binary:
    description: "0 oder 100"
  linear:
    description: "lineare Annäherung an Zielbereich"
  trapezoid:
    description: "optimaler Bereich = 100, davor/danach weicher Abfall"
  gaussian_like:
    description: "Zielwert-orientiert, symmetrischer Abfall"
  asymmetric:
    description: "unter Ziel anders bestrafen als über Ziel"
```

**Praxisregel:**
- `binary` nur für harte Compliance-Vorgaben
- `trapezoid` für Dauer, Pace, HR, Leistung
- `asymmetric` für Überlastungsrisiken (z. B. „zu hart“ stärker bestrafen als „etwas zu leicht“)

### 16.7 Die 3 Berechnungsstrategien – fachliche Bewertung

#### A. `weighted_score`
**Geeignet für:** die meisten freien Trainingsformen mit mehreren Einflussgrößen

**Vorteile**
- robust bei teilweise fehlenden Daten
- fein abstufbar
- gut visualisierbar
- ideal für Laufen, Radfahren, allgemeine Cardio-Sessions

**Risiko**
- eine Session kann trotz fehlender Kernanforderung noch „gut“ aussehen, wenn Nebenparameter stark sind

**Daher Empfehlung**
- immer mit vorgeschalteten **Mandatory Gates** kombinieren

**Formel**
```yaml
weighted_score:
  formula: sum(parameter_score_i * weight_i) / sum(active_weights_i)
  result_scale: 0_100
```

#### B. `all_rules_must_pass`
**Geeignet für:** standardisierte Protokolle, Reha-Übungen, Technik- oder Compliance-Sessions

**Vorteile**
- sehr klar
- leicht erklärbar
- hohe fachliche Stringenz

**Risiko**
- zu hart bei natürlicher Messvariabilität
- problematisch bei Sensorausfällen
- wenig differenziert

**Empfehlung**
- eher für „Pflichtprogramm erfüllt / nicht erfüllt“ einsetzen
- zusätzlich einen separaten `soft_score` berechnen, damit die UI nicht nur schwarz/weiß bleibt

#### C. `at_least_n_rules`
**Geeignet für:** Daten mit Lücken, Wearable-Heterogenität, flexibel definierte Trainingsformen

**Vorteile**
- robust gegen fehlende Messkanäle
- gut für Alltagssport und gemischte Datenquellen

**Risiko**
- alle Regeln werden implizit gleich wichtig, falls keine Zusatzlogik vorliegt

**Empfehlung**
- nur in Kombination mit `mandatory_rules`
- für N-Regelmodelle zusätzlich `priority_groups` definieren

### 16.8 Fachlich empfohlener Standard: Hybrid-Modell

Die beste Standardarchitektur ist **nicht** eine einzelne Strategie, sondern:

```yaml
recommended_default_strategy:
  stage_1:
    mandatory_gates: true
  stage_2:
    primary_strategy: weighted_score
  stage_3:
    fallback_when_sparse_data: at_least_n_rules
```

**Begründung:**  
So werden offensichtlich ungeeignete Sessions ausgeschlossen, gleichzeitig bleibt die Bewertung flexibel und datenrobust. Das entspricht der sportwissenschaftlichen Praxis besser als ein starres Alles-oder-Nichts-Modell.

### 16.9 Parameterklassifikation

Die aktuell genannten Parameter sollten fachlich in Klassen eingeteilt werden.

#### A. Externe Last / Umfang
- Dauer
- Distanz
- Höhenmeter
- aktive Kalorien
- Ruhekalorien
- Kalorien pro km

#### B. Interne Belastung / Intensität
- Durchschnittspuls
- Maximalpuls
- Minimalpuls
- RPE

#### C. Leistungs-/Effizienzmarker
- Pace
- Trittfrequenz
- Durchschnittsleistung

#### D. Zukünftige sinnvolle Ergänzungen
- Zeit in HF-Zonen
- Leistung in Zonen
- Satz-/Wiederholungsvolumen bei Krafttraining
- Intervallstruktur
- subjektive Trainingszielerfüllung
- Technik-/Skill-Flags

### 16.10 Parameter-Relevanz nach Trainingstyp

Die Engine sollte **keine globale Gleichbehandlung** der Parameter vornehmen.

#### Beispielhafte Relevanzmatrix

```yaml
parameter_relevance_examples:
  running_endurance:
    duration: high
    distance: high
    avg_hr: high
    max_hr: medium
    pace: high
    cadence: medium
    elevation_gain: medium
    avg_power: medium
    rpe: high
    active_calories: low
    resting_calories: none
    calories_per_km: low

  intervals_hiit:
    duration: medium
    distance: medium
    avg_hr: medium
    max_hr: high
    pace: high
    cadence: medium
    avg_power: high
    rpe: high
    elevation_gain: low
    active_calories: low

  strength_general:
    duration: medium
    avg_hr: low
    max_hr: low
    min_hr: none
    rpe: medium
    active_calories: low
    resting_calories: none
    avg_power: low
    pace: none
    cadence: none
    calories_per_km: none

  walking_health:
    duration: high
    distance: medium
    avg_hr: medium
    max_hr: low
    pace: medium
    cadence: medium
    rpe: low
    elevation_gain: low

  mobility_yoga:
    duration: high
    avg_hr: none
    max_hr: none
    pace: none
    cadence: none
    rpe: low
```

**Fachliche Korrektur:**  
`active_calories`, `resting_calories` und `calories_per_km` sollten fast nie Kernparameter der Qualität sein. Sie können Zusatzmarker sein, aber keine Primärlogik tragen, weil sie stark von Gerät, Körpermasse und Algorithmus abhängen.

### 16.11 Relative statt absolute Zielbereiche

Wo immer möglich, sollten Regeln **relativ zur Person** und nicht nur absolut formuliert werden.

#### Beispiele
- Avg-HR relativ zu HRmax oder besser HRR
- Pace relativ zur persönlichen 28d-Baseline oder Zielzone
- Leistung relativ zur persönlichen Baseline
- Dauer relativ zum üblichen Session-Typ-Fenster
- Kalorien pro km nur relativ und nur explorativ

**Begründung:**  
Absolute Schwellen bestrafen Anfänger und unterschätzen Fortgeschrittene. Relative Zonen sind individualisierter.

### 16.12 Vorsicht bei Herzfrequenz-Regeln

HF-basierte Regeln sind nützlich, aber nie allein ausreichend:
- geschätzte HRmax ist fehleranfällig
- Medikamente, Stress, Hitze, Dehydrierung und Messfehler beeinflussen HR
- Krafttraining und technische Sportarten bilden sich über HF oft schlecht ab

Daher:
```yaml
hr_rule_policy:
  never_use_as_only_primary_rule: true
  prefer_relative_thresholds: true
  downweight_if_hrmax_estimated_only: true
  combine_with_rpe_or_external_load: true
```

### 16.13 Umgang mit fehlenden Werten

Die Engine braucht eine explizite `missing_data_policy`.

```yaml
missing_data_policies:
  fail:
    description: "fehlender Pflichtwert = Regel nicht bestanden"
  renormalize_non_missing:
    description: "nur vorhandene Gewichte werden neu normiert"
  impute_from_baseline:
    description: "nur für robuste Langzeitmarker verwenden"
  downgrade_confidence:
    description: "Score bleibt, Confidence sinkt"
```

**Empfehlung**
- Pflichtparameter: `fail`
- optionale Parameter: `renormalize_non_missing` + `downgrade_confidence`

### 16.14 Empfohlene Score-Logik pro Trainingstyp

#### 16.14.1 Ausdauer – lockerer Dauerlauf

```yaml
training_type_example_running_easy:
  strategy: weighted_score
  mandatory_gates:
    - key: duration_min
      comparator: min
      threshold: 20
    - key: distance_km
      comparator: min
      threshold: 2

  parameters:
    - key: duration_min
      weight: 0.25
      comparator: range
      min: 30
      max: 75
      scoring_curve: trapezoid

    - key: avg_hr
      weight: 0.20
      comparator: range_relative_to_hrmax
      min_pct_hrmax: 0.65
      max_pct_hrmax: 0.78
      scoring_curve: trapezoid

    - key: pace_relative_to_28d_baseline
      weight: 0.15
      comparator: range
      min: 0.92
      max: 1.05
      scoring_curve: trapezoid

    - key: cadence
      weight: 0.10
      comparator: range_relative_to_baseline
      min_ratio: 0.95
      max_ratio: 1.08
      scoring_curve: trapezoid

    - key: rpe
      weight: 0.20
      comparator: range
      min: 3
      max: 5
      scoring_curve: trapezoid

    - key: elevation_gain_per_km
      weight: 0.10
      comparator: max
      threshold: 35
      scoring_curve: asymmetric
```

#### 16.14.2 HIIT / Intervalle

```yaml
training_type_example_hiit:
  strategy: at_least_n_rules
  min_rules_required: 4
  mandatory_gates:
    - key: duration_min
      comparator: min
      threshold: 12

  parameters:
    - key: max_hr
      comparator: range_relative_to_hrmax
      min_pct_hrmax: 0.88
      max_pct_hrmax: 0.98
      mandatory: false

    - key: avg_hr
      comparator: range_relative_to_hrmax
      min_pct_hrmax: 0.75
      max_pct_hrmax: 0.90

    - key: rpe
      comparator: range
      min: 7
      max: 9

    - key: avg_power_relative_to_baseline
      comparator: min
      min_ratio: 1.03

    - key: pace_relative_to_baseline
      comparator: min
      min_ratio: 1.03
```

#### 16.14.3 Krafttraining allgemein

**Wichtige fachliche Einschränkung:**  
Mit den aktuell genannten Parametern ist Krafttrainingsqualität nur eingeschränkt beurteilbar. Wirklich gute Kraftbewertung braucht später zusätzlich:
- Satzanzahl
- Wiederholungen
- verwendete Last
- Volumenlast
- Übungstypen
- Satz-RPE oder Reps in Reserve (RIR)

Bis dahin sollte die Qualität **nur vorsichtig** bewertet werden.

```yaml
training_type_example_strength_general:
  strategy: at_least_n_rules
  min_rules_required: 2
  mandatory_gates:
    - key: duration_min
      comparator: min
      threshold: 20

  parameters:
    - key: duration_min
      comparator: range
      min: 35
      max: 90
      weight: 0.40

    - key: rpe
      comparator: range
      min: 5
      max: 8
      weight: 0.35

    - key: avg_hr
      comparator: min
      threshold: 85
      weight: 0.10

    - key: active_calories
      comparator: min
      threshold: 120
      weight: 0.05

    - key: max_hr
      comparator: min
      threshold: 110
      weight: 0.10
```

**Interpretation:**  
Hier ist klar: HR und Kalorien sind nur schwache Hilfsmarker. Das System sollte dies in der UI offenlegen.

#### 16.14.4 Gehen / Gesundheitssport

```yaml
training_type_example_walking:
  strategy: weighted_score
  mandatory_gates:
    - key: duration_min
      comparator: min
      threshold: 10

  parameters:
    - key: duration_min
      weight: 0.35
      comparator: range
      min: 20
      max: 60

    - key: pace
      weight: 0.20
      comparator: range_relative_to_baseline
      min_ratio: 0.95
      max_ratio: 1.20

    - key: avg_hr
      weight: 0.20
      comparator: range_relative_to_hrmax
      min_pct_hrmax: 0.50
      max_pct_hrmax: 0.72

    - key: cadence
      weight: 0.15
      comparator: range_relative_to_baseline
      min_ratio: 0.95
      max_ratio: 1.15

    - key: elevation_gain
      weight: 0.10
      comparator: max
      threshold: 150
```

### 16.15 Label-Mapping

Der 0–100 Score sollte immer zusätzlich in ein erklärbares Label übersetzt werden.

```yaml
quality_label_thresholds_default:
  excluded: 0
  poor: 1-49
  acceptable: 50-64
  good: 65-79
  very_good: 80-89
  excellent: 90-100
```

Empfehlung:
- Trainingstyp-spezifisch überschreibbar
- zusätzlich `goal_mode`-abhängig feinjustierbar

### 16.16 Confidence-Score

Neben dem Qualitäts-Score braucht jede Session einen Vertrauenswert.

```yaml
confidence_score:
  components:
    required_data_completeness: 0.40
    optional_data_completeness: 0.15
    sensor_reliability_profile: 0.15
    baseline_availability: 0.15
    training_type_specificity: 0.15
```

**Beispiel**
- Laufen mit Dauer, Distanz, Pace, Avg-HR, Max-HR, RPE → hohe Confidence
- Krafttraining nur mit Dauer und Kalorien → niedrige Confidence

### 16.17 Trennung von Qualität, Dosis und Regelmäßigkeit

Für die Gesamtanalyse des Nutzers sollten drei Kennzahlen parallel geführt werden:

```yaml
session_metrics:
  quality_score:
    meaning: "Wie gut war die einzelne Einheit relativ zum Ziel des Trainingstyps?"
  load_score:
    meaning: "Wie belastend war die Einheit?"
  consistency_score:
    meaning: "Wie regelmäßig wurde trainiert?"
```

**Wichtige Folge:**  
Eine harte, sehr belastende Einheit kann `load_score` hoch, aber `quality_score` nur mittel haben, wenn sie nicht zum Trainingsziel passte.

### 16.18 Neue Visualisierungen speziell für Trainingsqualität

#### TQ1. Rule Fulfillment Breakdown
**Typ:** gestapelter Horizontalbalken pro Session  
**Inhalt:** erfüllt / teilweise erfüllt / nicht erfüllt / nicht verfügbar  
**Nutzen:** höchste Erklärbarkeit für den Nutzer

#### TQ2. Parameter Contribution Chart
**Typ:** Balkendiagramm  
**Inhalt:** Beitrag jedes Parameters zum `quality_score`  
**Nutzen:** zeigt, warum eine Einheit gut oder schwach bewertet wurde

#### TQ3. Training Type Quality Trend
**Typ:** Linienchart  
**Inhalt:** 7d / 28d gleitender Qualitätsmittelwert pro Trainingstyp  
**Nutzen:** erkennt, ob ein Typ systematisch zu leicht, zu hart oder inkonsistent trainiert wird

#### TQ4. Quality vs Load Quadrant
**Typ:** Scatterplot  
**Achsen:** `quality_score` × `load_score`  
**Quadranten:**
- hoch Qualität / hoch Last
- hoch Qualität / niedrig Last
- niedrig Qualität / hoch Last
- niedrig Qualität / niedrig Last

**Nutzen:**  
Zeigt besonders wertvoll, ob der Nutzer „hart, aber unsauber“ trainiert.

#### TQ5. Confidence Overlay
**Typ:** Punkt- oder Linien-Overlay  
**Inhalt:** Qualitätswerte werden nach Confidence visuell abgeschwächt  
**Nutzen:** verhindert Fehlinterpretationen bei dünner Datenlage

#### TQ6. Weekly Rule Heatmap
**Typ:** Heatmap  
**Achsen:** Woche × Regelgruppe  
**Nutzen:** identifiziert wiederkehrende Defizite, z. B. „zu kurz“, „zu geringe Intensität“, „fehlender RPE-Eintrag“

### 16.19 Regelbasierte Aussagen ohne KI

Die Engine kann bereits sehr gute nicht-KI-basierte Aussagen erzeugen.

#### Beispiele
- „Deine Laufeinheiten sind regelmäßig vorhanden, bleiben aber in 4 der letzten 6 Wochen unter dem Zielbereich für Dauer.“
- „Die Intensität deiner Intervall-Einheiten ist meist passend, jedoch fehlen häufig belastbare RPE-Daten; die Bewertung ist daher nur eingeschränkt sicher.“
- „Beim Krafttraining ist die aktuelle Qualitätsbewertung nur orientierend, da zentrale Kraftparameter wie Satzanzahl, Wiederholungen und Last bisher nicht erfasst werden.“
- „Du erreichst hohe Belastungswerte, aber die Zielkriterien des gewählten Trainingstyps werden nur teilweise erfüllt. Das spricht eher für Belastung als für zielgenaue Qualität.“

### 16.20 Empfehlungen ohne KI

#### Automatische Empfehlungen
```yaml
rule_based_recommendations:
  - trigger: "quality_score_28d < 60 and frequency_28d >= threshold"
    message: "Du trainierst regelmäßig, triffst aber die Qualitätskriterien des Typs noch nicht stabil. Prüfe Zieltempo, Dauer und Intensitätssteuerung."

  - trigger: "confidence_score < 50"
    message: "Die Bewertung ist nur eingeschränkt belastbar. Ergänze – wenn möglich – RPE oder Herzfrequenzdaten."

  - trigger: "training_type == strength and missing_strength_specific_metrics == true"
    message: "Für Krafttraining sollten später Satzanzahl, Wiederholungen und Last ergänzt werden, da Puls- und Kaloriendaten nur begrenzt aussagekräftig sind."

  - trigger: "high_load_low_quality_pattern == true"
    message: "Mehr Belastung führt aktuell nicht automatisch zu besserer Trainingsqualität. Wahrscheinlich ist die Steuerung des Reizes noch zu ungenau."
```

### 16.21 API-/Backend-Contract für Coding Agents

```yaml
POST /activity/{id}/evaluate-quality

request:
  activity_id: uuid
  profile_id: uuid
  training_type_id: uuid
  evaluation_mode: default

response:
  quality_score: 0-100
  quality_label: good
  load_score: 0-100
  confidence_score: 0-100
  strategy_used: weighted_score
  mandatory_rules_passed: true
  rules_passed_count: 5
  rules_total_count: 7
  parameter_breakdown:
    - key: duration_min
      raw_value: 42
      normalized_score: 100
      weight: 0.25
      passed: true
      contribution: 25.0
      explanation: "liegt im Zielbereich 30-75 min"
    - key: avg_hr
      raw_value: 146
      normalized_score: 82
      weight: 0.20
      passed: true
      contribution: 16.4
      explanation: "leicht oberhalb des idealen Bereichs"
  warnings:
    - "hrmax_is_estimated"
  exclusion_reason: null
```

### 16.22 Admin-UI für Trainingstyp-Regeln

Die Admin-Oberfläche sollte je Trainingstyp editierbar machen:

```yaml
admin_quality_rule_editor:
  fields:
    - strategy
    - min_rules_required
    - label_thresholds
    - missing_data_policy
    - mandatory_gate_mode
    - parameter_rows[]
  parameter_rows:
    - source_field
    - comparator
    - thresholds
    - scoring_curve
    - weight
    - required
    - mandatory
    - rationale_text
```

**Zusätzlicher Praxisnutzen:**  
Wenn `rationale_text` gepflegt wird, kann die UI dem Nutzer später direkt erklären, warum diese Regel existiert.

### 16.23 Fachliches Fazit zur Trainingsscore-Erweiterung

Die von dir beschriebene Architektur ist **grundsätzlich sehr gut anschlussfähig**, weil sie sportartspezifische Regeln pro Trainingstyp erlaubt. Fachlich optimal wird sie aber erst dann, wenn:

1. **Qualität, Last und Confidence getrennt werden**
2. **Parameter pro Trainingstyp unterschiedlich gewichtet werden**
3. **Mandatory Gates vor den eigentlichen Score geschaltet werden**
4. **relative, personenbezogene Zielbereiche absolute Schwellen möglichst oft ersetzen**
5. **Krafttraining später eigene Strukturmetriken erhält**
6. **RPE systematisch erfasst wird**
7. **fehlende Daten nicht nur den Score, sondern auch die Confidence beeinflussen**

---

## 17. Quellen / fachliche Fundierung

Die Architektur oben orientiert sich an den folgenden belastbaren Quellen und konsensnahen Leitlinien:

1. **Bourdon et al. – Monitoring Athlete Training Loads: Consensus Statement**  
   Kernaussage: Interne und externe Last sollten gemeinsam betrachtet werden; idealerweise werden objektive und subjektive Werkzeuge kombiniert.  
   Link: https://pubmed.ncbi.nlm.nih.gov/28463642/  
   Zusätzlich: https://journals.humankinetics.com/view/journals/ijspp/12/s2/article-pS2-161.pdf

2. **Halson – Monitoring Training Load to Understand Fatigue in Athletes**  
   Kernaussage: Lastmonitoring hilft, Anpassung, Müdigkeit und Risiko von Fehlsteuerung besser zu erkennen.  
   Link: https://pmc.ncbi.nlm.nih.gov/articles/PMC4213373/

3. **Haddad et al. – Session-RPE Method for Training Load Monitoring: Validity, Ecological Usefulness, and Influencing Factors**  
   Kernaussage: sRPE ist ein praxistauglicher interner Lastmarker, der Intensität und Dauer integriert.  
   Link: https://pubmed.ncbi.nlm.nih.gov/29163016/  
   Zusätzlich: https://pmc.ncbi.nlm.nih.gov/articles/PMC5673663/

4. **Coyne et al. – The Current State of Subjective Training Load Monitoring**  
   Kernaussage: subjektive und objektive Lastmaße sind nicht austauschbar; subjektive Maße erfassen zusätzliche psychophysiologische Dimensionen.  
   Link: https://pmc.ncbi.nlm.nih.gov/articles/PMC6301906/  
   Update/Follow-up: https://pmc.ncbi.nlm.nih.gov/articles/PMC9012875/

5. **ACSM – Monitoring Aerobic Exercise Intensity / Exercise Intensity Guidance**  
   Kernaussage: Intensität sollte über mehrere Verfahren überwacht werden, darunter Herzfrequenz und RPE.  
   Link: https://acsm.org/monitoring-aerobic-exercise-intensity/  
   Zusätzlich: https://acsm.org/wp-content/uploads/2025/02/Exercise-intensity-infographic-PDF.pdf

6. **ACSM – We Can and Should Do Better When Estimating Cardiorespiratory Fitness**  
   Kernaussage: geschätzte HRmax und indirekte Intensitätssteuerung haben individuelle Fehler; reine HR-Grenzwerte sind daher begrenzt präzise.  
   Link: https://acsm.org/estimating-cardiorespiratory-fitness/

7. **Tanaka et al. – Age-predicted maximal heart rate revisited**  
   Kernaussage: HRmax-Schätzformeln sind populationsbasiert und individuell ungenau; 208 − 0.7 × Alter ist robuster als 220 − Alter, bleibt aber eine Schätzung.  
   Link: https://pubmed.ncbi.nlm.nih.gov/11153730/

8. **ACSM Position Stand – Progression Models in Resistance Training for Healthy Adults**  
   Kernaussage: Krafttraining sollte über echte Struktur- und Progressionsmerkmale gesteuert werden; Pulsdaten allein reichen dafür nicht.  
   Link: https://pubmed.ncbi.nlm.nih.gov/19204579/