Lars
f81171a1f5
- Mark issue #53 as completed - Create issue #55: Dynamic Aggregation Methods - Update CLAUDE.md with Phase 0c achievements - Document 97 migrated functions + 20 new chart endpoints
842 lines
36 KiB
Markdown
842 lines
36 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` |
|
||
|
||
## 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:
|
||
```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 (真観)
|
||
```
|