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` |

## 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: v9d + Issue #28 🚀 Development seit 25.03.2026

### 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`

### Issue #28: Unified Prompt System ✅ (Development 25.03.2026)

**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

**Migrations:**
- Migration 020: Unified Prompt System Schema

**Backend Endpoints:**
- `POST /api/prompts/execute` - Universeller Executor
- `POST /api/prompts/unified` - Create unified prompt
- `PUT /api/prompts/unified/{id}` - Update unified prompt

**UI:**
- Admin → KI-Prompts: Type-Filter (Alle/Basis/Pipeline)
- Neuer Prompt-Editor mit dynamischem Stage-Builder
- Inline editing von Stages + Prompts

📚 Details: `.claude/docs/functional/AI_PROMPTS.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:
```python
# ❌ 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)):
```

```javascript
// ❌ 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))
```

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

## Design-System (Kurzreferenz)
```css
/* 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 (真観)
```