Lars
bf87e03100
- Mark Sleep Module as complete (Phase 2b) - Mark Rest Days as complete (Phase 2a) - Mark Extended Vitals as complete (Phase 2d) - Add migration details (010-014) - HF-Zonen + Recovery Score marked as next (Phase 2e) Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
359 lines
14 KiB
Markdown
359 lines
14 KiB
Markdown
# 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: v9c (komplett) 🚀 Production seit 21.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 Dev 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):**
|
||
- Ruhepuls + HRV (morgens)
|
||
- Blutdruck (Systolisch/Diastolisch + Puls)
|
||
- VO2 Max (Apple Watch)
|
||
- SpO2 (Blutsauerstoffsättigung)
|
||
- Atemfrequenz
|
||
- Unregelmäßiger Herzschlag & AFib-Warnungen
|
||
- CSV Import: Omron (Blutdruck) + Apple Health (alle Vitals)
|
||
- Trend-Analyse (7d/14d/30d)
|
||
|
||
- 🔲 **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)
|
||
- Migration 014: Extended vitals (BP, VO2 Max, SpO2, respiratory_rate)
|
||
|
||
📚 Details: `.claude/docs/functional/TRAINING_TYPES.md`
|
||
|
||
📚 Details: `.claude/docs/technical/MEMBERSHIP_SYSTEM.md` · `.claude/docs/architecture/FEATURE_ENFORCEMENT.md`
|
||
|
||
## Feature-Roadmap
|
||
|
||
> Vollständiges Backlog: `.claude/docs/BACKLOG.md`
|
||
> Beim Implementieren: verlinkte Dok-Datei zuerst lesen!
|
||
|
||
| Version | Feature | Dokumentation |
|
||
|---------|---------|---------------|
|
||
| v9c | Membership (aktiv) | `technical/MEMBERSHIP_SYSTEM.md` ✅ |
|
||
| v9d | Schlaf-Modul | `functional/SLEEP_MODULE.md` (ausstehend) |
|
||
| v9d | Trainingstypen + HF | `functional/TRAINING_TYPES.md` ✅ |
|
||
| v9e | Ziele + Vitalwerte | `functional/GOALS_VITALS.md` (ausstehend) |
|
||
| v9f | KI-Prompt Flexibilisierung | `functional/AI_PROMPTS.md` ✅ |
|
||
| v9g | Meditation + Selbstwahrnehmung | `functional/MEDITATION.md` (ausstehend) |
|
||
| v9h | Connectoren + Stripe | ausstehend |
|
||
| — | Responsive UI | `functional/RESPONSIVE_UI.md` ✅ |
|
||
|
||
## 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
|
||
|
||
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 (真観)
|
||
```
|