mitai-jinkendo/CLAUDE.md

Mitai Jinkendo – Entwickler-Kontext für Claude Code

Pflicht-Lektüre für Claude Code

VOR jeder Implementierung lesen: | Architektur-Regeln | .claude/rules/ARCHITECTURE.md | | Coding-Regeln | .claude/rules/CODING_RULES.md | | Lessons Learned | .claude/rules/LESSONS_LEARNED.md |

Claude Code Verantwortlichkeiten

Issue-Management (Gitea):

• ✅ Neue Issues/Feature Requests in Gitea anlegen
• ✅ Issue-Dokumentation in docs/issues/ pflegen
• ✅ Issues mit Labels, Priority, Aufwandsschätzung versehen
• ✅ Bestehende Issues aktualisieren (Status, Beschreibung)
• ✅ Issues bei Fertigstellung schließen
• 🎯 Gitea: http://192.168.2.144:3000/Lars/mitai-jinkendo/issues

Dokumentation:

• Code-Änderungen in CLAUDE.md dokumentieren
• Versions-Updates bei jedem Feature/Fix
• Library-Dateien bei größeren Änderungen aktualisieren

Entwicklung:

• Alle Änderungen auf develop Branch
• Production Deploy nur nach expliziter Freigabe
• Migration 001-999 Pattern einhalten

Projekt-Übersicht

Mitai Jinkendo (身体 Jinkendo) – selbst-gehostete PWA für Körper-Tracking mit KI-Auswertung. Teil der Jinkendo-App-Familie (人拳道). Domains: jinkendo.de / .com / .life

Tech-Stack

Komponente	Technologie
Frontend	React 18 + Vite + PWA (Node 20)
Backend	FastAPI Python 3.12
Datenbank	PostgreSQL 16 Alpine
Container	Docker + Docker Compose
Auth	Token-basiert + bcrypt
KI	OpenRouter API (claude-sonnet-4)

Ports: Prod 3002/8002 · Dev 3099/8099 – nie ändern!

Verzeichnisstruktur

backend/
├── main.py          # App-Setup + Router-Registration (~75 Zeilen)
├── db.py            # PostgreSQL Connection Pool
├── db_init.py       # DB-Init + Migrations-System (automatisch beim Start)
├── auth.py          # Hash, Verify, Sessions, Feature-Access-Control
├── models.py        # Pydantic Models
├── feature_logger.py # Strukturiertes JSON-Logging (Phase 2)
├── migrations/      # SQL-Migrationen (XXX_*.sql Pattern)
└── routers/         # 14 Router-Module
    auth · profiles · weight · circumference · caliper
    activity · nutrition · photos · insights · prompts
    admin · stats · exportdata · importdata

frontend/src/
├── App.jsx          # Root, Auth-Gates, Navigation
├── app.css          # CSS-Variablen + globale Styles
├── context/         # AuthContext · ProfileContext
├── pages/           # Alle Screens
└── utils/
    api.js           # ALLE API-Calls – Token automatisch injiziert
    calc.js · interpret.js · Markdown.jsx · guideData.js

.claude/
├── settings.json
├── commands/        # /deploy /merge-to-prod /refactor /ui-responsive etc.
└── docs/
    ├── BACKLOG.md
    ├── functional/  # Fachliche Specs (TRAINING_TYPES, AI_PROMPTS, RESPONSIVE_UI)
    └── technical/   # MEMBERSHIP_SYSTEM.md

Aktuelle Version: v0.9h+ → v0.9i (Phase 0c Complete + Chart Endpoints) 🎯 28.03.2026

Status: Phase 0c Backend KOMPLETT - Frontend Charts in Arbeit Branch: develop Nächster Schritt: Frontend Chart Integration → Testing → Prod Deploy v0.9i

Updates (28.03.2026 - Phase 0c Multi-Layer Architecture Complete) 🆕

Phase 0c: Multi-Layer Data Architecture ✅ COMPLETED

Gitea: Issue #53 - CLOSED Dokumentation: docs/issues/issue-53-phase-0c-multi-layer-architecture.md

Ziel erreicht: Single Source of Truth für Datenberechnungen - nutzbar für KI-Platzhalter UND Chart-Endpoints.

1. Data Layer Migration (97 Funktionen)

• ✅ body_metrics.py (438 → 831 Zeilen, 20 Funktionen)
  • Weight trends: 7d/28d/90d slopes, goal projections
  • Body composition: FM/LBM changes, recomposition quadrants
  • Circumferences: Delta-Berechnungen, Fortschritts-Scores
• ✅ nutrition_metrics.py (483 → 1093 Zeilen, 16 Funktionen)
  • Energy balance, protein adequacy, macro consistency
  • Intake volatility, nutrition scoring
• ✅ activity_metrics.py (277 → 906 Zeilen, 20 Funktionen)
  • Training volume, quality sessions, load monitoring
  • Monotony/Strain scores, ability balance
• ✅ recovery_metrics.py (291 → 879 Zeilen, 16 Funktionen)
  • Sleep metrics, HRV/RHR baselines, recovery scoring
• ✅ scores.py (NEU, 584 Zeilen, 14 Funktionen)
  • Focus weights, goal progress, category scores
• ✅ correlations.py (NEU, 504 Zeilen, 11 Funktionen)
  • Lag correlations, plateau detection, top drivers

2. Chart Endpoints API (20 neue Endpoints)

• ✅ Ernährung (E1-E5): 4 Endpoints
  • /charts/energy-balance - Kalorien-Timeline vs. TDEE
  • /charts/macro-distribution - Protein/Carbs/Fat (Pie)
  • /charts/protein-adequacy - Protein vs. Ziel (Timeline)
  • /charts/nutrition-consistency - Konsistenz-Score (Bar)
• ✅ Aktivität (A1-A8): 7 Endpoints
  • /charts/training-volume - Wöchentliches Volumen (Bar)
  • /charts/training-type-distribution - Typen-Verteilung (Pie)
  • /charts/quality-sessions - Qualitäts-Rate (Bar)
  • /charts/load-monitoring - Acute/Chronic Load + ACWR (Line)
  • /charts/monotony-strain - Monotonie & Strain (Bar)
  • /charts/ability-balance - Fähigkeiten-Balance (Radar)
  • /charts/volume-by-ability - Volumen pro Fähigkeit (Bar)
• ✅ Erholung (R1-R5): 5 Endpoints
  • /charts/recovery-score - Recovery Timeline (Line)
  • /charts/hrv-rhr-baseline - HRV & RHR vs. Baseline (Multi-Line)
  • /charts/sleep-duration-quality - Schlaf Dauer + Qualität (Multi-Line)
  • /charts/sleep-debt - Kumulative Schlafschuld (Line)
  • /charts/vital-signs-matrix - Aktuelle Vitalwerte (Bar)
• ✅ Korrelationen (C1-C4): 4 Endpoints
  • /charts/weight-energy-correlation - Gewicht ↔ Energie (Scatter)
  • /charts/lbm-protein-correlation - Magermasse ↔ Protein (Scatter)
  • /charts/load-vitals-correlation - Load ↔ HRV/RHR (Scatter)
  • /charts/recovery-performance - Top Treiber (Bar)

3. Statistik

Data Layer:    +3140 Zeilen (6 Module, 97 Funktionen)
Chart Endpoints: 329 → 2246 Zeilen (+1917 Zeilen, 20 neue Endpoints)
Commits:       7 systematische Commits (6 Module + 1 Chart Expansion)

4. Technische Details

• Single Source of Truth: Alle Berechnungen in data_layer/, keine Duplikation
• Chart.js Format: Alle Responses Chart.js-kompatibel
• Confidence System: Jeder Endpoint prüft Datenqualität
• Flexible Zeitfenster: Query-Parameter für 7-365 Tage
• Metadata: Confidence, Data Points, Zusatzinfos pro Chart

5. Commits

5b7d7ec fix: Phase 0c - update all in-function imports to use data_layer
285184b fix: add missing statistics import and update focus_weights function
a441537 debug: add detailed logging to get_nutrition_avg
ffa99f1 fix: correct confidence thresholds for 30-89 day range
5b4688f chore: remove debug logging from placeholder_resolver
782f79f feat: Phase 0c - Complete chart endpoints (E1-E5, A1-A8, R1-R5, C1-C4)

6. Betroffene Dateien

• backend/data_layer/*.py (6 Module komplett refactored)
• backend/routers/charts.py (329 → 2246 Zeilen)
• backend/placeholder_resolver.py (Imports aktualisiert, Debug-Logging entfernt)

---

Updates (28.03.2026 - Goal System Enhancement Complete) 🆕

Auto-Population & Time-Based Tracking ✅

• ✅ Auto-Population von start_date/start_value:
  • Automatische Ermittlung aus erster historischer Messung (on/after Startdatum)
  • Windowing-Logik: Findet nächste verfügbare Messung am oder nach gewähltem Datum
  • Auto-Adjustment: Startdatum wird auf tatsächliches Messdatum gesetzt
  • Funktioniert für alle Goal-Typen (weight, body_fat, lean_mass, vo2max, strength, bp, rhr)
• ✅ Time-Based Tracking (Behind Schedule):
  • Linear Progress Model: expected = (elapsed_days / total_days) × 100
  • Deviation Calculation: actual_progress - expected_progress
  • Negativ = behind schedule, Positiv = ahead of schedule
  • User-Feedback: "Warum 'behind schedule'?" → Zeitbasierte Abweichung implementiert
• ✅ Hybrid Goal Display:
  • Goals MIT target_date: Zeit-basierte Abweichung (±% voraus/zurück)
  • Goals OHNE target_date: Einfacher Fortschritt (% erreicht)
  • Kombinierte Sortierung für aussagekräftige Rankings
  • Platzhalter: {{top_3_goals_behind_schedule}}, {{top_3_goals_on_track}}
• ✅ Timeline Visualization:
  • Start → Ziel Datumsanzeige in Ziellisten
  • Format: "Start: 92.0 kg (22.02.26) → Ziel: 85.0 kg (31.05.26)"
  • Fortschrittsbalken mit Prozentanzeige

Bug Fixes (28.03.2026) ✅

• ✅ PostgreSQL Date Arithmetic: ORDER BY ABS(date - %s::date) statt EXTRACT(EPOCH)
• ✅ JSON Date Serialization: serialize_dates() für Python date → ISO strings
• ✅ start_date nicht gespeichert: update_goal() Logik komplett überarbeitet
• ✅ start_date fehlte in SELECT: get_active_goals() + get_goals_grouped() ergänzt
• ✅ Edit-Form Datum-Fallback: goal.start_date || '' statt || today
• ✅ Behind Schedule Logik: Von "lowest progress" zu "time-based deviation"
• ✅ Fehlende created_at: Backup-Datum für Goals ohne start_date

Betroffene Dateien:

• backend/routers/goals.py: serialize_dates(), _get_historical_value_for_goal_type(), create_goal(), update_goal(), list_goals(), get_goals_grouped()
• backend/goal_utils.py: get_active_goals() SELECT ergänzt (start_date, created_at)
• backend/placeholder_resolver.py: _format_goals_behind(), _format_goals_on_track() komplett überarbeitet (hybrid logic)
• frontend/src/pages/GoalsPage.jsx: Timeline-Display, handleEditGoal() fix

Letzte Updates (27.03.2026 - Dynamic Focus Areas v2.0 Complete)

Dynamic Focus Areas v2.0 System ✅

• ✅ Migration 031-032: Vollständiges dynamisches System
  • focus_area_definitions - 26 Basis-Bereiche in 7 Kategorien (admin-erweiterbar)
  • goal_focus_contributions - Many-to-Many (Goals ↔ Focus Areas) mit Gewichtung
  • user_focus_area_weights - User-spezifische Präferenzen (dynamisch)
• ✅ Backend: routers/focus_areas.py (~350 Zeilen)
  • CRUD für Focus Area Definitions (Admin only)
  • User preferences mit Auto-Normalisierung zu Prozenten
  • Stats endpoint (Progress per Focus Area)
• ✅ Frontend: Komplett überarbeitet
  • GoalsPage: Dynamische Kacheln (nur Bereiche mit Gewicht > 0)
  • Edit-Modus: Alle 26 Bereiche mit Schiebereglern (gruppiert nach Kategorie)
  • Ziel-Formular: Nur gewichtete Focus Areas zur Auswahl (cleaner UX)
  • AdminFocusAreasPage: Volle CRUD-UI für Admin
• ✅ Architektur-Verbesserungen:
  • Kein Goal Mode mehr (ersetzt durch dynamische Focus Areas)
  • M:N Relationship: Ein Ziel zahlt auf 1-n Focus Areas ein
  • Contribution Weights: Prozentuale Gewichtung pro Zuordnung
  • User-extensible: Admin kann beliebige neue Bereiche hinzufügen

Bug Fixes (alle deployed) ✅

• ✅ Focus Contributions speichern: focus_contributions fehlte in API-Payload (GoalsPage:232)
• ✅ Focus Area Filtering: Nur gewichtete Areas im Ziel-Formular (bessere UX)
• ✅ Vitals Baseline Fix: Parameter mismatch in dynamischer Query-Generierung behoben

Custom Goals Page (Capture/Eigene Ziele) ✅

• ✅ Custom Goals Page (Capture/Eigene Ziele):
  • Neue Seite für tägliche Werterfassung individueller Ziele
  • Dedizierte UI für custom goals (ohne automatische Datenquelle)
  • Verhindert Verwechslung mit automatischem Tracking (Gewicht, Aktivität, etc.)
  • Clean UX: Zielauswahl → Schnellerfassung → Verlauf (letzte 5 Einträge)
  • Navigation: Capture Hub + direkter Link
• ✅ UX-Improvements Progress Modal:
  • Volle Breite Eingabefelder, Labels als Überschriften, linksbündiger Text
  • Progress-Button nur bei custom goals sichtbar (source_table IS NULL)
• ✅ Architektur-Klarstellung:
  • Analysis/Goals → Strategisch (Ziele definieren, Prioritäten setzen)
  • Capture/Custom Goals → Taktisch (tägliche Ist-Wert-Erfassung)
  • History → Auswertung (Zielerreichungs-Analysen)

Updates (27.03.2026 - Phase 1 Fixes)

• ✅ Abstraction Layer: goal_utils.py für zukunftssichere Phase 0b Platzhalter
• ✅ Primary Goal Toggle Fix: is_primary Update funktioniert korrekt
• ✅ Lean Mass Berechnung: Magermasse current_value wird berechnet
• ✅ VO2Max Fix: Spaltenname vo2_max (statt vo2max) korrigiert
• ✅ Keine Doppelarbeit: Phase 0b Platzhalter (120+) müssen bei v2.0 nicht umgeschrieben werden

Phase 0a Completion (26.03.2026) 🎯

• ✅ Phase 0a: Minimal Goal System: Strategic + Tactical Layers implementiert
• ✅ Migration 022: goal_mode, goals, training_phases, fitness_tests tables
• ✅ Backend Router: goals.py mit vollständigem CRUD (490 Zeilen)
• ✅ Frontend: GoalsPage mit mobile-friendly Design (570 Zeilen)
• ✅ Navigation: Goals Preview (Dashboard) + Ziele Button (Analysis)
• ✅ Basis geschaffen: Für 120+ goal-aware Platzhalter (Phase 0b)
• ✅ Dokumentation: issue-50, NEXT_STEPS_2026-03-26.md, GOALS_SYSTEM_UNIFIED_ANALYSIS.md

Frühere Updates (26.03.2026 - Vormittag)

• ✅ circ_summary erweitert: Best-of-Each Strategie mit Altersangaben
• ✅ Stage Outputs Fix: Debug-Info für Experten-Modus
• ✅ Collapsible JSON: Stage-Rohdaten aufklappbar
• ✅ Gitea #28 geschlossen: AI-Prompts Flexibilisierung
• ✅ Gitea #44 geschlossen: Analysen löschen behoben
• ✅ Gitea #47 erstellt: Wertetabelle Optimierung

Implementiert ✅

• Login (E-Mail + bcrypt), Auth-Middleware alle Endpoints, Rate Limiting
• Gewicht · Umfänge · Caliper · Ernährung · Aktivität + CSV-Imports
• KI-Analyse: 6 Prompts + 3-stufige Pipeline
• Dashboard · Verlauf · Assistent-Modus · Fotos
• Admin-Panel · E-Mail (SMTP) · PWA
• PostgreSQL 16 · Modulare Router-Architektur
• Membership-System: Tiers · Coupons · Access-Grants · Admin-UI
• Export: CSV · JSON · ZIP
• Feature-Enforcement (komplett): Alle 11 Features mit Monitoring, UI-Badges + Blocking
• Ernährungs-Modul (erweitert):
  • Manuelles Erfassungsformular mit Upsert-Logik (verhindert Duplikate)
  • Import-Historie (CSV-Importe gruppiert nach Datum)
  • Bearbeiten/Löschen von Einträgen (inline)
  • Datumsfilter (7/30/90/365 Tage, Alle)
  • Zwei-Ebenen-Layout: Eingabe (Einzelerfassung/Import) + Auswertung (Charts)

Feature-Enforcement Status (4-Phasen-Modell)

• ✅ Phase 1: Cleanup (Feature-Konsolidierung, Migration)
• ✅ Phase 2: Non-blocking Monitoring (JSON-Logs, alle 11 Features)
• ✅ Phase 3: Frontend Display (Usage-Badges, Quota-Übersicht, Hover-Tooltips)
• ✅ Phase 4: Enforcement (HTTP 403 bei Limit-Überschreitung, alle Features)

Abgedeckte Features: weight_entries, circumference_entries, caliper_entries, activity_entries, nutrition_entries, photos, ai_calls, ai_pipeline, data_export, data_import

Bug-Fixes (v9c)

• ✅ BUG-001: TypeError in /api/nutrition/weekly (datetime.date vs string handling)
• ✅ BUG-002: Ernährungs-Daten Tab fehlte – importierte Einträge nicht sichtbar
• ✅ BUG-003: Korrelations-Chart Extrapolation (gestrichelte Linien für fehlende Werte)
• ✅ BUG-004: Import-Historie Refresh (Force remount via key prop)
• ✅ BUG-005: Login → leere Seite (window.location.href='/' nach login)
• ✅ BUG-006: Email-Verifizierung → leere Seite (window.location.href='/' statt navigate)
• ✅ BUG-007: Doppelklick Verifizierungslink → generischer JSON-Fehler (Error-Parsing + bessere Backend-Meldung)
• ✅ BUG-008: Dashboard infinite loading bei API-Fehlern (.catch() handler in load())

v9c Finalisierung ✅ (Deployed to Production 21.03.2026)

• ✅ Selbst-Registrierung: POST /api/auth/register, E-Mail-Verifizierung, Auto-Login
• ✅ Trial-System UI: Countdown-Banner im Dashboard (3 Urgency-Level)
• ✅ Migrations-System: Automatische Schema-Migrationen beim Start (db_init.py)
• ✅ Navigation-Fixes: Alle Login/Verify-Flows funktionieren korrekt
• ✅ Error-Handling: JSON-Fehler sauber formatiert, Dashboard robust bei API-Fehlern

v9d – Phase 1b ✅ (Deployed to Production 21.03.2026)

Trainingstypen-System mit lernendem Mapping:

• ✅ 29 Trainingstypen in 7 Kategorien (inkl. Geist & Meditation)
• ✅ Lernendes Mapping-System (DB-basiert):
  • Tabelle activity_type_mappings statt hardcoded
  • 40+ Standard-Mappings (Deutsch + English)
  • Auto-Learning: Bulk-Kategorisierung speichert Mappings
  • User-spezifische + globale Mappings
  • Admin-UI für Mapping-Verwaltung (inline editing)
  • Coverage-Stats (% zugeordnet vs. unkategorisiert)
• ✅ Apple Health Import:
  • Deutsche Workout-Namen unterstützt
  • Automatisches Mapping via DB
  • Duplikat-Erkennung (date + start_time)
  • Update statt Insert bei Reimport
• ✅ UI-Features:
  • TrainingTypeSelect in ActivityPage
  • Farbige Typ-Badges in Aktivitätsliste
  • TrainingTypeDistribution Chart in History
  • Bulk-Kategorisierung (selbstlernend)
  • Admin-CRUD für Trainingstypen
  • Admin-CRUD für Activity-Mappings (inline editing)

Migrations:

• Migration 004: training_types Tabelle + 23 Basis-Typen
• Migration 005: Extended types (Gehen, Tanzen, Geist & Meditation)
• Migration 006: abilities JSONB column (Platzhalter für v9f)
• Migration 007: activity_type_mappings (lernendes System)

Dokumentation:

• .claude/docs/functional/AI_PROMPTS.md (erweitert um Fähigkeiten-Mapping)
• .claude/docs/technical/CENTRAL_SUBSCRIPTION_SYSTEM.md

v9d – Phase 2 ✅ (Deployed to Production 23.03.2026)

Vitalwerte & Erholung:

• ✅ Schlaf-Modul (v9d Phase 2b):

  • Tabelle sleep_log mit JSONB sleep_segments
  • Schlafphasen (Deep, REM, Light, Awake)
  • Apple Health CSV Import
  • Schlaf-Statistiken & Trends
  • Schlafschuld-Berechnung

• ✅ Ruhetage (v9d Phase 2a):

  • Tabelle rest_days (Multi-Dimensional Rest)
  • 3 Typen: Kraft-Ruhe, Cardio-Ruhe, Entspannung
  • Quick Mode Presets + Custom Entry
  • Validierung gegen geplante Aktivitäten
  • Dashboard Widget mit aktuellen Ruhetagen

• ✅ Vitalwerte erweitert (v9d Phase 2d):

  • 3-Tab Architektur: Baseline (morgens) / Blutdruck (mehrfach täglich) / Import
  • Baseline Vitals: Ruhepuls, HRV, VO2 Max, SpO2, Atemfrequenz
  • Blutdruck: Systolisch/Diastolisch + Puls, WHO/ISH-Klassifizierung
  • Context-Tagging: 8 Kontexte (nüchtern, nach Essen, Training, Stress, etc.)
  • Inline-Editing: Alle Messungen direkt in der Liste bearbeitbar
  • Smart Upsert: Baseline lädt existierende Einträge automatisch
  • CSV Import: Omron (Deutsch) + Apple Health (Deutsch/Englisch)
  • Mobile-optimiert: Volle Breite Felder, Sektions-Überschriften
  • Unregelmäßiger Herzschlag & AFib-Warnungen
  • Trend-Analyse (7d/14d/30d)

Bugfixes (23.03.2026):

• ✅ Import-Zählung korrigiert (skipped vs. updated)

• ✅ Deutsche Spaltennamen für CSV-Imports (Ruhepuls, Herzfrequenzvariabilität, etc.)

• ✅ Dezimalwerte-Parsing (safe_int/safe_float für Apple Health Exports)

• ✅ Error-Details in Import-Response (erste 10 Fehler im Frontend sichtbar)

• 🔲 HF-Zonen + Erholungsstatus (v9d Phase 2e):

  • HF-Zonen-Verteilung pro Training
  • Recovery Score basierend auf Ruhepuls + HRV + Schlaf
  • Übertraining-Warnung

Migrations:

• Migration 010: sleep_log Tabelle (JSONB segments)
• Migration 011: rest_days Tabelle (Kraft, Cardio, Entspannung)
• Migration 012: Unique constraint rest_days (profile_id, date, rest_type)
• Migration 013: vitals_log Tabelle (Ruhepuls, HRV) - deprecated
• Migration 014: Extended vitals (BP, VO2 Max, SpO2, respiratory_rate) - deprecated
• Migration 015: Vitals Refactoring - Trennung in vitals_baseline + blood_pressure_log

📚 Details: .claude/docs/functional/TRAINING_TYPES.md

📚 Details: .claude/docs/technical/MEMBERSHIP_SYSTEM.md · .claude/docs/architecture/FEATURE_ENFORCEMENT.md

Feature: Unified Prompt System ✅ (Completed 26.03.2026)

Gitea: Issue #28 (AI-Prompts Flexibilisierung) - CLOSED

AI-Prompts Flexibilisierung - Komplett überarbeitet:

• ✅ Unified Prompt System (4 Phasen):
  • Phase 1: DB-Migration - Schema erweitert
    • ai_prompts um type, stages, output_format, output_schema erweitert
    • Alle Prompts zu 1-stage Pipelines migriert
    • Pipeline-Configs in ai_prompts konsolidiert
  • Phase 2: Backend Executor
    • prompt_executor.py - universeller Executor für base + pipeline
    • Dynamische Placeholder-Auflösung ({{stage_N_key}})
    • JSON-Output-Validierung
    • Multi-stage parallele Ausführung
    • Reference (Basis-Prompts) + Inline (Templates) Support
  • Phase 3: Frontend UI Consolidation
    • UnifiedPromptModal - ein Editor für beide Typen
    • AdminPromptsPage - Tab-Switcher entfernt, Type-Filter hinzugefügt
    • Stage-Editor mit Add/Remove/Reorder
    • Mobile-ready Design
  • Phase 4: Cleanup & Docs
    • Deprecated Komponenten entfernt (PipelineConfigModal, PromptEditModal)
    • Old endpoints behalten für Backward-Compatibility

Features:

• Unbegrenzte dynamische Stages (keine 3-Stage Limitierung mehr)
• Mehrere Prompts pro Stage (parallel)
• Zwei Prompt-Typen: base (wiederverwendbar) + pipeline (Workflows)
• Inline-Templates oder Referenzen zu Basis-Prompts
• JSON-Output erzwingbar pro Prompt
• Cross-Module Korrelationen möglich

Debug & Development Tools (26.03.2026):

• ✅ Comprehensive Debug System:
  • Test-Button in Prompt-Editor mit Debug-Modus
  • Shows resolved/unresolved placeholders
  • Displays final prompts sent to AI
  • Per-stage debug info for pipelines
  • Export debug data as JSON
• ✅ Placeholder Export (per Test):
  • Button in Debug-Viewer
  • Exports all placeholders with values per execution
• ✅ Global Placeholder Export:
  • Settings → "📊 Platzhalter exportieren"
  • All 32 placeholders with current values
  • Organized by category
  • Includes metadata (description, example)
• ✅ Batch Import/Export:
  • Admin → "📦 Alle exportieren" (all prompts as JSON)
  • Admin → "📥 Importieren" (upload JSON, create/update)
  • Dev→Prod sync in 2 clicks

Placeholder System Enhancements:

• ✅ 6 New Placeholder Functions:
  • {{sleep_avg_duration}} - Average sleep duration (7d)
  • {{sleep_avg_quality}} - Deep+REM percentage (7d)
  • {{rest_days_count}} - Rest days count (30d)
  • {{vitals_avg_hr}} - Average resting heart rate (7d)
  • {{vitals_avg_hrv}} - Average HRV (7d)
  • {{vitals_vo2_max}} - Latest VO2 Max value
• ✅ 7 Reconstructed Placeholders:
  • {{caliper_summary}}, {{circ_summary}}
  • {{goal_weight}}, {{goal_bf_pct}}
  • {{nutrition_days}}
  • {{protein_ziel_low}}, {{protein_ziel_high}}
  • {{activity_detail}}
• Total: 32 active placeholders across 6 categories

Bug Fixes (26.03.2026):

• ✅ PIPELINE_MASTER Response: Analysis page now uses unified executor
  • Fixed: Old /insights/run endpoint sent raw template to AI
  • Now: /prompts/execute with proper stage processing
• ✅ Age Calculation: Handle PostgreSQL DATE objects
  • Fixed: calculate_age() expected string, got date object
  • Now: Handles both strings and date objects
• ✅ Sleep Quality 0%: Lowercase stage names
  • Fixed: Checked ['Deep', 'REM'], but stored as ['deep', 'rem']
  • Now: Correct case-sensitive matching
• ✅ SQL Column Name Errors:
  • Fixed: bf_jpl → body_fat_pct
  • Fixed: brust → c_chest, etc.
  • Fixed: protein → protein_g
• ✅ Decimal × Float Type Error:
  • Fixed: protein_ziel_low/high calculations
  • Now: Convert Decimal to float before multiplication

Migrations:

• Migration 020: Unified Prompt System Schema

Backend Endpoints:

• POST /api/prompts/execute - Universeller Executor (with save=true param)
• POST /api/prompts/unified - Create unified prompt
• PUT /api/prompts/unified/{id} - Update unified prompt
• GET /api/prompts/export-all - Export all prompts as JSON
• POST /api/prompts/import - Import prompts from JSON (with overwrite option)
• GET /api/prompts/placeholders/export-values - Export all placeholder values

UI:

• Admin → KI-Prompts: Type-Filter (Alle/Basis/Pipeline)
• Neuer Prompt-Editor mit dynamischem Stage-Builder
• Inline editing von Stages + Prompts
• Test-Button mit Debug-Viewer (always visible)
• Export/Import Buttons (📦 Alle exportieren, 📥 Importieren)
• Settings → 📊 Platzhalter exportieren

📚 Details: .claude/docs/functional/AI_PROMPTS.md

Related Gitea Issues:

• Gitea #28: AI-Prompts Flexibilisierung - ✅ CLOSED (26.03.2026)
• Gitea #42, #43: Enhanced Debug UI - 🔲 OPEN (Future enhancement)
• Gitea #44: BUG - Analysen löschen - ✅ CLOSED (26.03.2026)
• Gitea #45: KI Prompt-Optimierer - 🔲 OPEN (Future feature)
• Gitea #46: KI Prompt-Ersteller - 🔲 OPEN (Future feature)
• Gitea #47: Wertetabelle Optimierung - 🔲 OPEN (Refinement, siehe docs/issues/issue-50)

Feature: Comprehensive Value Table ✅ (Completed 26.03.2026)

Gitea: Basis-Implementierung abgeschlossen. Issue #47 (Wertetabelle Optimierung) für Refinement offen.

AI-Analyse Transparenz - Vollständige Platzhalter-Anzeige:

• ✅ Metadata Collection System:

  • Alle genutzten Platzhalter mit Werten während Ausführung gesammelt
  • Vollständige (nicht gekürzte) Werte aus placeholder_resolver
  • Kategorisierung nach Modul (Profil, Körper, Ernährung, Training, etc.)
  • Speicherung in ai_insights.metadata (JSONB)

• ✅ Expert Mode:

  • Toggle-Button "🔬 Experten-Modus" in Analysis-Seite
  • Normal-Modus: Zeigt nur relevante, gefüllte Werte
  • Experten-Modus: Zeigt alle Werte inkl. Rohdaten und Stage-Outputs

• ✅ Stage Output Extraction:

  • Basis-Prompts mit JSON-Output: Einzelwerte extrahiert
  • Jedes Feld aus Stage-JSON als eigene Zeile
  • Visuelle Kennzeichnung: ↳ für extrahierte Werte
  • Source-Tracking: Welche Stage, welcher Output

• ✅ Category Grouping:

  • Gruppierung nach Kategorien (PROFIL, KÖRPER, ERNÄHRUNG, etc.)
  • Stage-Outputs als eigene Kategorien ("Stage 1 - Body")
  • Rohdaten-Sektion (nur im Experten-Modus)
  • Sortierung: Reguläre → Stage-Outputs → Rohdaten

• ✅ Value Table Features:

  • Drei Spalten: Platzhalter | Wert | Beschreibung
  • Keine Kürzung langer Werte
  • Kategorie-Header mit grauem Hintergrund
  • Empty/nicht verfügbar Werte ausgeblendet (Normal-Modus)

Migrations:

• Migration 021: ai_insights.metadata JSONB column

Backend Endpoints:

• POST /api/prompts/execute - Erweitert um Metadata-Collection
• GET /api/insights/placeholders/catalog - Placeholder-Kategorien

UI:

• Analysis Page: Value Table mit Category-Grouping
• Expert-Mode Toggle (🔬 Symbol)
• Collapsible JSON für Rohdaten
• Delete-Button für Insights (🗑️)

📚 Details: .claude/docs/functional/AI_PROMPTS.md

Phase 0a: Minimal Goal System ✅ (Completed 26.03.2026)

Gitea: Issue #50 (zu erstellen) - COMPLETED Dokumentation: docs/issues/issue-50-phase-0a-goal-system.md, docs/GOALS_SYSTEM_UNIFIED_ANALYSIS.md

Zwei-Ebenen-Ziel-Architektur für goal-aware KI-Analysen:

• ✅ Strategic Layer (Goal Modes):

  • goal_mode in profiles table (weight_loss, strength, endurance, recomposition, health)
  • Bestimmt Score-Gewichtung für alle KI-Analysen
  • UI: 5 Goal Mode Cards mit Icons und Beschreibungen

• ✅ Tactical Layer (Concrete Goals):

  • goals table mit vollständigem Progress-Tracking
  • 8 Goal-Typen: weight, body_fat, lean_mass, vo2max, strength, flexibility, bp, rhr
  • Auto-calculated progress percentage
  • Linear projection für target_date
  • Primary/Secondary goal concept
  • UI: Goal CRUD mit Fortschrittsbalken, mobile-friendly

• ✅ Training Phases Framework:

  • training_phases table (Auto-Detection vorbereitet)
  • 5 Phase-Typen: calorie_deficit, calorie_surplus, deload, maintenance, periodization
  • Status-Flow: suggested → accepted → active → completed
  • Confidence scoring für KI-basierte Erkennung

• ✅ Fitness Tests:

  • fitness_tests table für standardisierte Tests
  • 8 Test-Typen: Cooper, Step Test, Pushups, Plank, VO2Max, Strength (Squat/Bench)
  • Norm-Kategorisierung vorbereitet

Backend:

• Migration 022: goal_mode, goals, training_phases, fitness_tests tables
• Router: routers/goals.py (490 Zeilen) - vollständiges CRUD
• API Endpoints: /api/goals/* (mode, list, create, update, delete, phases, tests)

Frontend:

• GoalsPage: frontend/src/pages/GoalsPage.jsx (570 Zeilen)
• Mobile-friendly Design (full-width inputs, labels above)
• Navigation: Dashboard (Goals Preview Card) + Analysis (🎯 Ziele Button)
• api.js: 15+ neue Goal-Funktionen

Commits:

• 337667f - feat: Phase 0a - Minimal Goal System
• 906a3b7 - fix: Migration 022 tracking
• 75f0a5d - refactor: mobile-friendly design
• 5be52bc - feat: goals navigation + UX

Basis für Phase 0b:

• Foundation für 120+ goal-aware Platzhalter
• Score-Berechnungen abhängig von goal_mode
• Intelligente Coaching-Funktionen
• Automatische Trainingsphasen-Erkennung

Nächste Schritte:

• Option A: Issue #49 - Prompt Page Assignment (6-8h, Quick Win)
• Option B: Phase 0b - Goal-Aware Placeholders (16-20h, Strategic)

📚 Details: docs/NEXT_STEPS_2026-03-26.md

Feature-Roadmap

📋 Detaillierte Roadmap: .claude/docs/ROADMAP.md (Phasen 0-3, Timeline, Abhängigkeiten) 📚 Vollständiges Backlog: .claude/docs/BACKLOG.md 🎯 Gitea Issues: http://192.168.2.144:3000/Lars/mitai-jinkendo/issues

Beim Implementieren: verlinkte Dok-Datei zuerst lesen!

Aktuelle Entwicklung (Phase 0-2, ~10-13 Wochen)

Phase	Fokus	Dauer	Gitea Issues
Phase 0	Infrastruktur (v9f)	4-6 Wochen	#24, #28, #29, #30
Phase 1	Foundation (Charts, Goals)	2-3 Wochen	#26, #25
Phase 2	Engagement (Korrelationen, KI)	3-4 Wochen	#27, #25
Phase 3	Begleitung (Development Routes)	später	-

Phase 0 Issues:

• #24: Quality-Filter (3h, Quick Win) ← Start hier
• #28: AI-Prompts Flexibilisierung (16-20h, kritisch)
• #29: Abilities-Matrix UI (6-8h)
• #30: Responsive UI (8-10h, parallel)

Phase 1 Issues:

• #26: Charts erweitern (8-10h)
• #25: Ziele-System Basis (10-12h)

Phase 2 Issues:

• #27: Korrelationen (6-8h)
• #25: Goals KI-Integration (4h)

Versions-Übersicht

Version	Feature	Dokumentation	Status
v9c	Membership (aktiv)	technical/MEMBERSHIP_SYSTEM.md	✅ Production
v9d	Schlaf-Modul	functional/SLEEP_MODULE.md	✅ Production
v9d	Trainingstypen + HF	functional/TRAINING_TYPES.md	✅ Production
v9e	Ziele + Vitalwerte	functional/GOALS_VITALS.md	🔲 Phase 1
v9f	KI-Prompt Flexibilisierung	functional/AI_PROMPTS.md	🔲 Phase 0
v9g	Meditation + Selbstwahrnehmung	functional/MEDITATION.md	🔲 Phase 3
v9h	Connectoren + Stripe	ausstehend	🔲 Später
—	Responsive UI	functional/RESPONSIVE_UI.md	🔲 Phase 0

Deployment

Internet → Fritz!Box (privat.stommer.com) → Synology NAS → Raspberry Pi 5 (192.168.2.49)

Git Workflow:
  develop → Auto-Deploy → dev.mitai.jinkendo.de  (bodytrack-dev/, Port 3099/8099)
  main    → Auto-Deploy → mitai.jinkendo.de       (bodytrack/, Port 3002/8002)

Gitea: http://192.168.2.144:3000/Lars/mitai-jinkendo
Runner: Raspberry Pi (/home/lars/gitea-runner/)

Manuell:
  cd /home/lars/docker/bodytrack[-dev]
  docker compose -f docker-compose[.dev-env].yml build --no-cache && up -d

Migrations:
  Werden automatisch beim Container-Start ausgeführt (db_init.py)
  Nur nummerierte Dateien: backend/migrations/XXX_*.sql
  Tracking in schema_migrations Tabelle
  📚 Details: .claude/docs/technical/MIGRATIONS.md

Datenbank-Schema (PostgreSQL 16)

profiles          – Nutzer (role, pin_hash/bcrypt, email, tier)
sessions          – Auth-Tokens
weight_log        – Gewicht (profile_id, date, weight)
circumference_log – 8 Umfangspunkte
caliper_log       – Hautfalten, 4 Methoden
nutrition_log     – Kalorien + Makros
activity_log      – Training
photos            – Progress-Fotos
ai_insights       – KI-Auswertungen (scope = prompt-slug)
ai_prompts        – Konfigurierbare Prompts (11 Standard)
ai_usage          – KI-Calls pro Tag pro Profil

v9c neu (Membership):
subscriptions · coupons · coupon_redemptions · features
tier_limits · user_feature_restrictions · user_feature_usage
access_grants · user_activity_log

v9d neu (Training & Vitals):
training_types        – 29 Trainingstypen in 7 Kategorien
activity_type_mappings – Lernendes Mapping-System (Deutsch/Englisch)
sleep_log             – Schlaf mit JSONB segments (Phasen)
rest_days             – Multi-dimensionale Ruhetage (Kraft/Cardio/Entspannung)
vitals_baseline       – Morgenmessung (RHR, HRV, VO2 Max, SpO2, resp_rate)
blood_pressure_log    – Blutdruck mehrfach täglich mit Context-Tagging

Deprecated (v9d Phase 2d):
vitals_log → vitals_log_backup_pre_015 (nach Migration 015)

Infrastruktur:
schema_migrations – Tracking für automatische DB-Migrationen

Feature-Logging (Phase 2):
/app/logs/feature-usage.log  # JSON-Format, alle Feature-Zugriffe

Schema-Datei: backend/schema.sql
Migrationen: backend/migrations/*.sql (automatisch beim Start)

API & Auth

Alle Endpoints:     /api/...
Auth-Header:        X-Auth-Token: <token>
Fehler:             {"detail": "Fehlermeldung"}
Rate Limit:         HTTP 429

Auth-Flow:
  Login → E-Mail + Passwort → Token in localStorage
  Token → X-Auth-Token Header → require_auth()
  Profile-Id → immer aus Session, nie aus Header!
  SHA256 → automatisch zu bcrypt migriert beim Login

Umgebungsvariablen (.env)

DB_HOST/PORT/NAME/USER/PASSWORD  # PostgreSQL
OPENROUTER_API_KEY               # KI
OPENROUTER_MODEL=anthropic/claude-sonnet-4
SMTP_HOST/PORT/USER/PASS/FROM    # E-Mail
APP_URL=https://mitai.jinkendo.de
ALLOWED_ORIGINS=https://mitai.jinkendo.de
PHOTOS_DIR=/app/photos

Kritische Regeln für Claude Code

Must-Do:

1. api.js für ALLE API-Calls nutzen – nie direktes fetch() ohne Token
2. session: dict = Depends(require_auth) als separater Parameter – nie in Header() einbetten
3. bcrypt für alle Passwort-Operationen
4. Neue DB-Spalten nur via Schema-Migration, nicht direkt
5. npm install (nicht npm ci) – kein package-lock.json

Bekannte Fallstricke:

# ❌ FALSCH – führt zu ungeschütztem Endpoint:
def endpoint(x: str = Header(default=None, session=Depends(require_auth))):

# ✅ RICHTIG:
def endpoint(x: str = Header(default=None), session: dict = Depends(require_auth)):

// ❌ FALSCH – dayjs.week() existiert nicht ohne Plugin:
dayjs(date).week()

// ✅ RICHTIG – native ISO-Wochenberechnung:
const w = (d => Math.ceil(((new Date(d.setDate(d.getDate()+4-(d.getDay()||7)))-
  new Date(d.getFullYear(),0,1))/86400000+1)/7))(new Date(date))

# PostgreSQL Boolean (nicht SQLite 0/1):
WHERE active = true   # ✅
WHERE active = 1      # ❌

Design-System (Kurzreferenz)

/* Farben */
--accent: #1D9E75    --accent-dark: #085041    --danger: #D85A30
--bg · --surface · --surface2 · --border · --text1 · --text2 · --text3

/* Klassen */
.card · .btn · .btn-primary · .btn-secondary · .btn-full
.form-input · .form-label · .form-row · .spinner

/* Abstände */
Seiten-Padding: 16px · Card-Padding: 16-20px · Border-Radius: 12px/8px
Bottom-Padding Mobile: 80px (Navigation)

Vollständige CSS-Variablen und Komponenten-Muster: frontend/src/app.css Responsive Layout-Spec: .claude/docs/functional/RESPONSIVE_UI.md

Dokumentations-Struktur

.claude/
├── BACKLOG.md              ← Feature-Übersicht
├── commands/               ← Slash-Commands (/deploy, /document etc.)
├── docs/
│   ├── functional/         ← Fachliche Specs (WAS soll gebaut werden)
│   ├── technical/          ← Technische Specs (WIE wird es gebaut)
│   └── rules/              ← Verbindliche Regeln
└── library/                ← Ergebnis-Dokumentation (WAS wurde gebaut)

Bereich	Pfad	Inhalt
Architektur-Übersicht	.claude/library/ARCHITECTURE.md	Gesamt-Überblick
Frontend-Dokumentation	.claude/library/FRONTEND.md	Seiten + Komponenten
Auth-Flow	.claude/library/AUTH.md	Sicherheit + Sessions
API-Referenz	.claude/library/API\_REFERENCE.md	Alle Endpoints
Datenbankschema	.claude/library/DATABASE.md	Tabellen + Beziehungen

Library-Dateien werden mit /document generiert und nach größeren Änderungen aktualisiert.

Jinkendo App-Familie

mitai.jinkendo.de    → Körper-Tracker (diese App)
miken.jinkendo.de    → Meditation (眉間)
ikigai.jinkendo.de   → Lebenssinn (生き甲斐)
shinkan.jinkendo.de  → Kampfsport (真観)