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