179 lines
6.9 KiB
Markdown
179 lines
6.9 KiB
Markdown
# Mitai Jinkendo – Entwickler-Kontext für Claude Code
|
||
|
||
## Projekt-Übersicht
|
||
**Mitai Jinkendo** (身体 Jinkendo) ist eine selbst-gehostete PWA für Körper-Tracking (Gewicht, Körperfett, Umfänge, Ernährung, Aktivität) mit KI-Auswertung. Teil der **Jinkendo**-App-Familie (人拳道 – Der menschliche Weg der Kampfkunst).
|
||
|
||
**Produktfamilie:** mitai · miken · ikigai · shinkan · kenkou (alle unter jinkendo.de)
|
||
|
||
## Tech-Stack
|
||
| Komponente | Technologie | Version |
|
||
|-----------|-------------|---------|
|
||
| Frontend | React 18 + Vite + PWA | Node 20 |
|
||
| Backend | FastAPI (Python) | Python 3.12 |
|
||
| Datenbank | SQLite (v9a) → PostgreSQL (v9b geplant) | - |
|
||
| Container | Docker + Docker Compose | - |
|
||
| Webserver | nginx (Reverse Proxy) | Alpine |
|
||
| Auth | Token-basiert + bcrypt | - |
|
||
| KI | OpenRouter API (claude-sonnet-4) | - |
|
||
|
||
## Ports
|
||
| Service | Prod | Dev |
|
||
|---------|------|-----|
|
||
| Frontend | 3002 | 3099 |
|
||
| Backend | 8002 | 8099 |
|
||
|
||
## Verzeichnisstruktur
|
||
```
|
||
mitai-jinkendo/
|
||
├── backend/
|
||
│ ├── main.py # FastAPI App, alle Endpoints (~2000 Zeilen)
|
||
│ ├── requirements.txt
|
||
│ └── Dockerfile
|
||
├── frontend/
|
||
│ ├── src/
|
||
│ │ ├── App.jsx # Root, Auth-Gates, Navigation
|
||
│ │ ├── app.css # Globale Styles, CSS-Variablen
|
||
│ │ ├── context/
|
||
│ │ │ ├── AuthContext.jsx # Session, Login, Logout
|
||
│ │ │ └── ProfileContext.jsx # Aktives Profil
|
||
│ │ ├── pages/ # Alle Screens
|
||
│ │ └── utils/
|
||
│ │ ├── api.js # Alle API-Calls (injiziert Token automatisch)
|
||
│ │ ├── calc.js # Körperfett-Formeln
|
||
│ │ ├── interpret.js # Regelbasierte Auswertung
|
||
│ │ ├── Markdown.jsx # Eigener MD-Renderer
|
||
│ │ └── guideData.js # Messanleitungen
|
||
│ └── public/ # Icons (Jinkendo Ensō-Logo)
|
||
├── .gitea/workflows/
|
||
│ ├── deploy-prod.yml # Auto-Deploy bei Push auf main
|
||
│ ├── deploy-dev.yml # Auto-Deploy bei Push auf develop
|
||
│ └── test.yml # Build-Test bei jedem Push
|
||
├── docker-compose.yml # Produktion (Ports 3002/8002)
|
||
├── docker-compose.dev-env.yml # Development (Ports 3099/8099)
|
||
└── CLAUDE.md # Diese Datei
|
||
```
|
||
|
||
## Aktuelle Version: v9a
|
||
|
||
### Was implementiert ist:
|
||
- ✅ Multi-User mit E-Mail + Passwort Login (bcrypt)
|
||
- ✅ Auth-Middleware auf ALLE Endpoints (44 Endpoints geschützt)
|
||
- ✅ Rate Limiting (Login: 5/min, Reset: 3/min)
|
||
- ✅ CORS konfigurierbar via ALLOWED_ORIGINS in .env
|
||
- ✅ Admin/User Rollen, KI-Limits, Export-Berechtigungen
|
||
- ✅ Gewicht, Umfänge, Caliper (4 Formeln), Ernährung, Aktivität
|
||
- ✅ FDDB CSV-Import (Ernährung), Apple Health CSV-Import (Aktivität)
|
||
- ✅ KI-Analyse: 6 Einzel-Prompts + 3-stufige Pipeline (parallel)
|
||
- ✅ Konfigurierbare Prompts mit Template-Variablen
|
||
- ✅ Verlauf mit 5 Tabs + Zeitraumfilter + KI pro Sektion
|
||
- ✅ Dashboard mit Kennzahlen, Zielfortschritt, Combo-Chart
|
||
- ✅ Assistent-Modus (Schritt-für-Schritt Messung)
|
||
- ✅ PWA (iPhone Home Screen), Jinkendo Ensō-Logo
|
||
- ✅ E-Mail (SMTP) für Password-Recovery
|
||
- ✅ Admin-Panel: User verwalten, KI-Limits, E-Mail-Test
|
||
- ✅ Multi-Environment: Prod (mitai.jinkendo.de) + Dev (dev.mitai.jinkendo.de)
|
||
- ✅ Gitea CI/CD mit Auto-Deploy auf Raspberry Pi 5
|
||
|
||
### Was in v9b kommt:
|
||
- 🔲 PostgreSQL Migration (aktuell noch SQLite)
|
||
- 🔲 Selbst-Registrierung mit E-Mail-Bestätigung
|
||
- 🔲 Freemium Tier-System (free/basic/premium/selfhosted)
|
||
- 🔲 14-Tage Trial automatisch
|
||
- 🔲 Einladungslinks für Beta-Nutzer
|
||
- 🔲 Admin kann Tiers manuell setzen
|
||
|
||
### Was in v9c kommt:
|
||
- 🔲 OAuth2-Grundgerüst für Fitness-Connectoren
|
||
- 🔲 Strava Connector
|
||
- 🔲 Withings Connector (Waage)
|
||
- 🔲 Garmin Connector
|
||
|
||
## Deployment
|
||
|
||
### Infrastruktur
|
||
```
|
||
Internet → privat.stommer.com (Fritz!Box DynDNS)
|
||
→ Synology NAS (Reverse Proxy + Let's Encrypt)
|
||
→ Raspberry Pi 5 (192.168.2.49, Docker)
|
||
```
|
||
|
||
### Git Workflow
|
||
```
|
||
develop branch → Auto-Deploy → dev.mitai.jinkendo.de (Port 3099/8099)
|
||
main branch → Auto-Deploy → mitai.jinkendo.de (Port 3002/8002)
|
||
```
|
||
|
||
### Deployment-Befehle (manuell falls nötig)
|
||
```bash
|
||
# Prod
|
||
cd /home/lars/docker/bodytrack
|
||
docker compose -f docker-compose.yml build --no-cache
|
||
docker compose -f docker-compose.yml up -d
|
||
|
||
# Dev
|
||
cd /home/lars/docker/bodytrack-dev
|
||
docker compose -f docker-compose.dev-env.yml build --no-cache
|
||
docker compose -f docker-compose.dev-env.yml up -d
|
||
```
|
||
|
||
## Datenbank-Schema (SQLite, v9a)
|
||
### Wichtige Tabellen:
|
||
- `profiles` – Nutzer (role, pin_hash/bcrypt, email, auth_type, ai_enabled)
|
||
- `sessions` – Auth-Tokens mit Ablaufdatum
|
||
- `weight_log` – Gewichtseinträge (profile_id, date, weight)
|
||
- `circumference_log` – 8 Umfangspunkte
|
||
- `caliper_log` – Hautfaltenmessung, 4 Methoden
|
||
- `nutrition_log` – Kalorien + Makros (aus FDDB-CSV)
|
||
- `activity_log` – Training (aus Apple Health oder manuell)
|
||
- `ai_insights` – KI-Auswertungen (scope = prompt-slug)
|
||
- `ai_prompts` – Konfigurierbare Prompts mit Templates (11 Prompts)
|
||
- `ai_usage` – KI-Calls pro Tag pro Profil
|
||
|
||
## Auth-Flow (v9a)
|
||
```
|
||
Login-Screen → E-Mail + Passwort → Token im localStorage
|
||
Token → X-Auth-Token Header → Backend require_auth()
|
||
Profile-Id → aus Session (nicht aus Header!)
|
||
SHA256 Passwörter → automatisch zu bcrypt migriert beim Login
|
||
```
|
||
|
||
## API-Konventionen
|
||
- Alle Endpoints: `/api/...`
|
||
- Auth-Header: `X-Auth-Token: <token>`
|
||
- Responses: immer JSON
|
||
- Fehler: `{"detail": "Fehlermeldung"}`
|
||
- Rate Limit überschritten: HTTP 429
|
||
|
||
## Umgebungsvariablen (.env)
|
||
```
|
||
OPENROUTER_API_KEY= # KI-Calls
|
||
OPENROUTER_MODEL=anthropic/claude-sonnet-4
|
||
SMTP_HOST= # E-Mail
|
||
SMTP_PORT=587
|
||
SMTP_USER=
|
||
SMTP_PASS=
|
||
SMTP_FROM=
|
||
APP_URL=https://mitai.jinkendo.de
|
||
ALLOWED_ORIGINS=https://mitai.jinkendo.de
|
||
DATA_DIR=/app/data
|
||
PHOTOS_DIR=/app/photos
|
||
```
|
||
|
||
## Wichtige Hinweise für Claude Code
|
||
1. **Ports immer 3002/8002 (Prod) oder 3099/8099 (Dev)** – nie ändern
|
||
2. **npm install** (nicht npm ci) – kein package-lock.json vorhanden
|
||
3. **SQLite safe_alters** – neue Spalten immer via safe_alters Liste
|
||
4. **Pipeline-Prompts** haben slug-Prefix `pipeline_` – nie als Einzelanalyse zeigen
|
||
5. **dayjs.week()** braucht Plugin – stattdessen native JS ISO-Wochenberechnung
|
||
6. **useNavigate()** nur in React-Komponenten, nicht in Helper-Functions
|
||
7. **api.js nutzen** für alle API-Calls – injiziert Token automatisch
|
||
8. **bcrypt** für alle neuen Passwort-Operationen verwenden
|
||
9. **session=Depends(require_auth)** als separater Parameter – nie in Header() einbetten
|
||
|
||
## Code-Style
|
||
- React: Functional Components, Hooks
|
||
- CSS: Inline-Styles + globale CSS-Variablen (var(--accent), var(--text1), etc.)
|
||
- API-Calls: immer über `api.js` (injiziert Token automatisch)
|
||
- Kein TypeScript (bewusst, für Einfachheit)
|
||
- Python: keine Type-Hints Pflicht, aber bei neuen Funktionen erwünscht
|