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

# Fachliche Anforderungen: Schlaf-Modul
**Modul:** v9d  
**Status:** Fachlich freigegeben, technische Implementierung ausstehend  
**Letzte Aktualisierung:** März 2026

---

## 1. Überblick

Das Schlaf-Modul ist ein eigenständiges Tracking-Modul für tägliche Schlafdaten.
Es ergänzt die bestehenden Körper-, Ernährungs- und Aktivitäts-Module um eine
zentrale Gesundheitsdimension. Schlaf wird sowohl manuell erfasst als auch aus
Apple Health / Garmin importiert. Korrelationen mit Ruhepuls, Training und Gewicht
fließen in die KI-Analyse ein.

---

## 2. Erfasste Daten

### 2.1 Pflichtfelder (Schnelleingabe)
- **Datum** – welche Nacht (Standard: letzte Nacht)
- **Schlafdauer** – in Stunden und Minuten (berechnet aus Ein-/Aufwachzeit oder direkt)
- **Schlafqualität** – subjektiv 1–5 (1 = sehr schlecht, 5 = sehr gut)

### 2.2 Optionale Felder (Detaileingabe)
- **Einschlafzeit** – Uhrzeit (z.B. 23:15)
- **Aufwachzeit** – Uhrzeit (z.B. 06:45)
- **Aufwach-Häufigkeit** – wie oft in der Nacht aufgewacht (0–10+)
- **Schlafphasen** – Dauer in Minuten je Phase:
  - Tiefschlaf
  - REM-Schlaf
  - Leichtschlaf
  - Wach (in Bett)
- **Notiz** – Freitext (z.B. "Stress, schlechte Nacht", "früh ins Bett")

### 2.3 Abgeleitete Felder (automatisch berechnet)
- **Schlafdauer** – aus Einschlafzeit + Aufwachzeit wenn nicht direkt eingegeben
- **Schlafeffizienz** – Schlafdauer / Zeit im Bett × 100% (wenn Phasen vorhanden)
- **Tiefschlaf-Anteil %** – Tiefschlaf / Gesamtschlaf × 100%
- **REM-Anteil %** – REM / Gesamtschlaf × 100%

---

## 3. Erfassungs-Modi

### 3.1 Schnelleingabe (≤ 30 Sekunden)
Minimaler Aufwand für den täglichen Gebrauch:
```
Datum:        [gestern / heute Nacht]
Schlafdauer:  [7] h [30] min
Qualität:     ★★★★☆  (1-5 Sterne)
[Speichern]
```

### 3.2 Detaileingabe (alle Felder)
Vollständige Erfassung für Power-User oder wenn Gerätedaten vorliegen:
```
Datum:           [22.03.2026]
Eingeschlafen:   [23:15]
Aufgewacht:      [06:45]
Schlafdauer:     [7h 30min] (automatisch berechnet)
Qualität:        ★★★★☆
Aufwachungen:    [1]
Tiefschlaf:      [95] min
REM-Schlaf:      [110] min
Leichtschlaf:    [230] min
Wach im Bett:    [15] min
Notiz:           [...]
[Speichern]
```

### 3.3 Morgendlicher Check-in
- Beim Öffnen der App morgens optional: "Wie hast du geschlafen?"
- Zeigt Schnelleingabe direkt auf dem Dashboard
- Kann in den Einstellungen aktiviert/deaktiviert werden
- Reminder-Logik: nur anzeigen wenn noch kein Eintrag für die letzte Nacht

### 3.4 Import (Apple Health / Garmin)
- Beim CSV/Health-Import werden Schlafdaten automatisch erkannt und zugeordnet
- Importierte Daten befüllen alle verfügbaren Felder (Phasen wenn vorhanden)
- Manuelle Eingabe ergänzt oder überschreibt Importdaten für denselben Tag
- Quelle wird gespeichert (manuell / apple_health / garmin)

---

## 4. Navigation & Dashboard

### 4.1 Eigene Seite in der Navigation
- Neuer Nav-Eintrag: **Schlaf** (zwischen Verlauf und Analyse)
- Icon: Mond oder Bett-Symbol
- Zeigt: Letzte 7 Tage Übersicht + Verlauf + Eingabe-Button

### 4.2 Dashboard-Widget
- Kompaktes Widget auf dem Dashboard (unter den Hauptkennzahlen)
- Zeigt: Letzte Nacht (Dauer + Qualität) + 7-Tage-Durchschnitt
- Klick öffnet die Schlaf-Seite
- Wenn noch kein Eintrag heute: "Schlaf erfassen" Button

---

## 5. Auswertungen

### 5.1 Schlafdauer-Trend
- Zeitraum wählbar: 7 / 30 / 90 Tage
- Liniengrafik: tägliche Schlafdauer
- Referenzlinie: persönliches Schlafziel (konfigurierbar in Einstellungen)
- Durchschnittslinie: gleitender 7-Tage-Durchschnitt
- Farbcodierung: unter Ziel = orange/rot, über Ziel = grün

### 5.2 Schlafqualität-Trend
- Liniengrafik: tägliche Qualität (1–5)
- 7-Tage-Durchschnitt als Referenzlinie
- Kombiniert mit Schlafdauer in einer Grafik (zwei Y-Achsen)

### 5.3 Schlafphasen-Verteilung
- Balkengrafik: Tiefschlaf / REM / Leichtschlaf / Wach je Nacht
- Durchschnittliche Verteilung über Zeitraum
- Referenzwerte: empfohlene Anteile (Tiefschlaf 15-25%, REM 20-25%)
- Nur sichtbar wenn Phasendaten vorhanden

### 5.4 Schlafschulden-Berechnung
- Definition: Differenz zwischen Schlafziel und tatsächlichem Schlaf (kumuliert)
- Zeitraum: letzte 7 / 14 Tage
- Anzeige: "+2h 15min Schlafschuld" oder "0 – kein Defizit"
- Positiver Saldo (Übererfüllung) wird als Puffer angezeigt

### 5.5 Optimales Schlaffenster
- Berechnung aus Einschlafzeit + Schlafqualität über Zeit
- Erkennt wann Schlaf am besten war (z.B. "Beste Qualität bei Einschlafzeit 22–23 Uhr")
- Mindestdatenbasis: 14 Einträge mit Einschlafzeit

### 5.6 Korrelationen
Alle Korrelationen benötigen mindestens 14 gemeinsame Datenpunkte:

**Schlaf ↔ Ruhepuls:**
- Streudiagramm: Schlafdauer / Qualität vs. Ruhepuls nächster Morgen
- KI-Aussage: "Nach <7h Schlaf ist dein Ruhepuls Ø X bpm höher"

**Schlaf ↔ Trainingsleistung:**
- Vergleich: Trainingsintensität/-volumen nach gut vs. schlecht geschlafenen Nächten
- KI-Aussage: "Nach Nächten mit >7,5h Schlaf trainierst du Ø X% länger/intensiver"

**Schlaf ↔ Gewicht:**
- Korrelation: Schlafdauer vs. Gewichtsentwicklung (wöchentlich)
- KI-Aussage: "In Wochen mit <6h Schlaf im Schnitt +X kg Gewichtsschwankung"

---

## 6. Schlafziel (konfigurierbar)

- In den Einstellungen: "Mein Schlafziel" → Stunden + Minuten
- Standard: 7h 30min
- Wird als Referenzlinie in allen Grafiken angezeigt
- Fließt in Schlafschulden-Berechnung ein
- KI nutzt den Wert als Basis für Schlafmangel-Warnung

---

## 7. KI-Analyse

### 7.1 Neue KI-Platzhalter
```
{{schlaf_avg_dauer}}         → "7h 12min (Ø 7 Tage)"
{{schlaf_avg_qualitaet}}     → "3,8/5 (Ø 7 Tage)"
{{schlaf_trend_dauer}}       → "sinkend / stabil / steigend"
{{schlaf_trend_qualitaet}}   → "sinkend / stabil / steigend"
{{schlaf_schulden}}          → "+2h 15min (letzte 7 Tage)"
{{schlaf_ziel}}              → "7h 30min"
{{schlaf_optimum_fenster}}   → "22:00–23:00 Uhr (beste Qualität)"
{{schlaf_tiefschlaf_anteil}} → "18% (Ø letzte 14 Tage)"
{{schlaf_rem_anteil}}        → "22% (Ø letzte 14 Tage)"
{{schlaf_aufwachungen}}      → "1,2x pro Nacht (Ø 7 Tage)"
{{schlaf_korrelation_puls}}  → "Ruhepuls +4 bpm nach <7h Schlaf"
{{schlaf_detail}}            → tabellarische Übersicht letzte 7 Nächte
```

### 7.2 KI-Analyse-Funktionen

**Schlafmangel erkennen und warnen:**
- Trigger: Schlafdurchschnitt letzte 3 Tage < (Schlafziel – 60min)
- KI-Ausgabe: Warnung + konkrete Empfehlung
- Beispiel: "Du schläfst seit 3 Tagen unter deinem Ziel. Schlafschuld: +2h 15min."

**Schlaf ↔ Trainingsleistung korrelieren:**
- Automatische Berechnung sobald genug Daten (14+ Einträge beider Module)
- KI-Ausgabe: narrative Korrelationsbeschreibung mit konkreten Zahlen

**Optimales Schlaffenster empfehlen:**
- Basierend auf historischen Einschlafzeiten + Qualitäten
- KI-Ausgabe: "Deine beste Schlafqualität erzielst du wenn du zwischen 22–23 Uhr einschläfst"

**Schlaf ↔ Gewicht:**
- Wöchentliche Korrelation
- KI-Ausgabe: "In Wochen mit mehr Schlaf zeigt dein Gewicht weniger Schwankungen"

**Schlafphasen-Verteilung kommentieren:**
- Nur wenn Phasendaten vorhanden
- Referenz: Tiefschlaf 15-25%, REM 20-25%, Leichtschlaf 50-60%
- KI-Ausgabe: "Dein Tiefschlaf-Anteil liegt bei X% – das ist [über/unter/im] empfohlenen Bereich"

---

## 8. Abgrenzung & offene Fragen

### In diesem Modul enthalten:
- Tägliche Schlaferfassung (Schnell + Detail)
- Dashboard-Widget + eigene Navigationsseite
- Morgendlicher Check-in (optional)
- Import aus Apple Health / Garmin CSV
- 5 Auswertungsansichten inkl. Korrelationen
- Konfigurierbares Schlafziel
- 12 neue KI-Platzhalter
- 5 KI-Analyse-Funktionen

### Nicht in diesem Modul:
- Automatischer Live-Sync aus Garmin/Apple Watch → v9h (Connectoren)
- Schlaf-Coaching / Schlafhygiene-Tipps → optional später
- Schnarchen / Atemaussetzer (SpO2) → Teil Vitalwerte v9e
- Push-Notification "Schlafenszeit-Reminder" → optional später

### Offene Fragen für technische Planung:
1. Neue DB-Tabelle `sleep_log` oder Erweiterung von `activity_log`?
2. Schlafphasen als separate Spalten oder als JSONB-Feld?
3. Morgendlicher Check-in: Frontend-State oder Backend-Logik (letzte Nacht bereits erfasst?)?
4. Korrelationsberechnung: im Backend (Python) oder im Frontend (JavaScript)?
5. Apple Health Export enthält Schlafphasen-Daten – welches CSV-Format wird erwartet?
EOF