From f81171a1f538d21edb99e7d8afca0b9b3be2cf2b Mon Sep 17 00:00:00 2001 From: Lars Date: Sat, 28 Mar 2026 22:22:16 +0100 Subject: [PATCH] docs: Phase 0c completion + new issue #55 - 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 --- CLAUDE.md | 89 +++++++++- ...ue-53-phase-0c-multi-layer-architecture.md | 10 +- .../issue-55-dynamic-aggregation-methods.md | 168 ++++++++++++++++++ 3 files changed, 263 insertions(+), 4 deletions(-) create mode 100644 docs/issues/issue-55-dynamic-aggregation-methods.md diff --git a/CLAUDE.md b/CLAUDE.md index edb0f0e..dd3436c 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -76,11 +76,94 @@ frontend/src/ └── technical/ # MEMBERSHIP_SYSTEM.md ``` -## Aktuelle Version: v0.9g+ → v0.9h (Goals Complete + Dynamic Focus Areas) 🎯 27.03.2026 +## Aktuelle Version: v0.9h+ → v0.9i (Phase 0c Complete + Chart Endpoints) 🎯 28.03.2026 -**Status:** BEREIT FÜR RELEASE v0.9h +**Status:** Phase 0c Backend KOMPLETT - Frontend Charts in Arbeit **Branch:** develop -**Nächster Schritt:** Testing → Prod Deploy → Code Splitting → Phase 0b (120+ Platzhalter) +**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) 🆕 diff --git a/docs/issues/issue-53-phase-0c-multi-layer-architecture.md b/docs/issues/issue-53-phase-0c-multi-layer-architecture.md index 4dca4aa..ad3d508 100644 --- a/docs/issues/issue-53-phase-0c-multi-layer-architecture.md +++ b/docs/issues/issue-53-phase-0c-multi-layer-architecture.md @@ -1,11 +1,19 @@ # Issue #53: Phase 0c - Multi-Layer Data Architecture -**Status:** 🎯 Ready for Implementation +**Status:** ✅ COMPLETED **Priorität:** High (Strategic) **Aufwand:** 20-27h (5-7 Tage bei 4h/Tag) **Erstellt:** 28. März 2026 +**Abgeschlossen:** 28. März 2026 **Abhängigkeiten:** Phase 0a ✅, Phase 0b ✅ +**Completion Summary:** +- ✅ Data Layer: 97 functions migrated to `data_layer/` (6 modules) +- ✅ Chart Endpoints: 20 new endpoints implemented (E1-E5, A1-A8, R1-R5, C1-C4) +- ✅ Single Source of Truth: All calculations in data_layer, used by KI + Charts +- ✅ Commits: 7 systematic commits (6 module migrations + 1 chart expansion) +- ✅ charts.py: 329 → 2246 lines (+1917 lines) + --- ## Executive Summary diff --git a/docs/issues/issue-55-dynamic-aggregation-methods.md b/docs/issues/issue-55-dynamic-aggregation-methods.md new file mode 100644 index 0000000..e58e730 --- /dev/null +++ b/docs/issues/issue-55-dynamic-aggregation-methods.md @@ -0,0 +1,168 @@ +# Issue #55: Dynamic Aggregation Methods for Goal Types + +**Status:** 📋 Planned +**Priorität:** Low (Nice-to-Have) +**Aufwand:** 2-3h +**Erstellt:** 28. März 2026 +**Abhängigkeiten:** Keine + +--- + +## Problem + +**Aktuell:** +```javascript +// frontend/src/pages/AdminGoalTypesPage.jsx (Lines 28-38) + +const AGGREGATION_METHODS = [ + { value: 'latest', label: 'Letzter Wert' }, + { value: 'avg_7d', label: 'Durchschnitt 7 Tage' }, + { value: 'avg_30d', label: 'Durchschnitt 30 Tage' }, + { value: 'sum_30d', label: 'Summe 30 Tage' }, + { value: 'count_7d', label: 'Anzahl 7 Tage' }, + { value: 'count_30d', label: 'Anzahl 30 Tage' }, + { value: 'min_30d', label: 'Minimum 30 Tage' }, + { value: 'max_30d', label: 'Maximum 30 Tage' }, + { value: 'avg_per_week_30d', label: 'Durchschnitt pro Woche (30d)' } +] +``` + +**Probleme:** +- ❌ Hardcoded im Frontend +- ❌ Backend kennt diese Liste nicht → keine Validierung +- ❌ Neue Aggregationsmethoden erfordern Frontend-Änderung +- ❌ Nicht konsistent mit dynamischer Platzhalter-Liste + +--- + +## Lösung: Backend-definierte Aggregation Methods + +### Konzept + +**Backend definiert** die verfügbaren Methoden: + +```python +# backend/routers/goal_types.py + +AGGREGATION_METHODS = [ + { + "value": "latest", + "label_de": "Letzter Wert", + "label_en": "Latest Value", + "description": "Neuester Messwert im Zeitfenster", + "applicable_to": ["weight", "caliper", "circumference", "vitals"], + "example": "Aktuellstes Gewicht (heute oder letzter Eintrag)" + }, + { + "value": "avg_7d", + "label_de": "Durchschnitt 7 Tage", + "label_en": "7-day Average", + "description": "Mittelwert der letzten 7 Tage", + "applicable_to": ["weight", "nutrition", "vitals", "sleep"], + "example": "Durchschnittskalorien der letzten Woche" + }, + # ... alle Methoden ... +] + +@router.get("/goal-types/aggregation-methods") +def get_aggregation_methods(session: dict = Depends(require_auth)): + """ + Get available aggregation methods for goal types. + + Returns: + List of aggregation method definitions with metadata + """ + return { + "methods": AGGREGATION_METHODS, + "default": "latest" + } +``` + +**Frontend lädt** die Methoden dynamisch: + +```javascript +// frontend/src/pages/AdminGoalTypesPage.jsx + +const [aggregationMethods, setAggregationMethods] = useState([]) + +useEffect(() => { + loadAggregationMethods() +}, []) + +const loadAggregationMethods = async () => { + const data = await api.getAggregationMethods() + setAggregationMethods(data.methods) +} + +// Render: + +``` + +--- + +## Implementierung + +### Phase 1: Backend Endpoint (1h) + +**Datei:** `backend/routers/goal_types.py` + +1. Definiere `AGGREGATION_METHODS` Konstante mit Metadata +2. Erstelle Endpoint `GET /api/goal-types/aggregation-methods` +3. Optional: Validierung bei Goal Type Create/Update + +### Phase 2: Frontend Integration (1h) + +**Datei:** `frontend/src/pages/AdminGoalTypesPage.jsx` + +1. Remove hardcoded `AGGREGATION_METHODS` +2. Add `loadAggregationMethods()` in useEffect +3. Update dropdown to use loaded methods +4. Add `api.getAggregationMethods()` in `api.js` + +### Phase 3: Optional Enhancements (1h) + +- Tooltips mit method.description +- Filtering nach applicable_to (nur relevante Methoden für gewählte Tabelle zeigen) +- Beispiel-Text anzeigen (method.example) + +--- + +## Vorteile + +- ✅ Single Source of Truth im Backend +- ✅ Backend kann Aggregationsmethoden validieren +- ✅ Neue Methoden ohne Frontend-Änderung hinzufügbar +- ✅ Konsistent mit PlaceholderPicker-Architektur +- ✅ Bessere UX (Tooltips, Beispiele, Filtering) + +--- + +## Akzeptanzkriterien + +- [ ] Backend Endpoint `/api/goal-types/aggregation-methods` existiert +- [ ] Frontend lädt Methoden dynamisch beim Laden der Seite +- [ ] Dropdown zeigt alle verfügbaren Methoden +- [ ] Hardcoded Array aus Frontend entfernt +- [ ] Backend validiert aggregation_method bei Create/Update + +--- + +## Related Issues + +- ✅ #54: Dynamic Placeholder System (UI bereits implementiert) +- ✅ #53: Phase 0c Multi-Layer Architecture (abgeschlossen) +- ✅ #50: Goals System (Basis vorhanden) + +--- + +## Notes + +- **Priorität Low**, weil System funktioniert (nur nicht dynamisch) +- **Nice-to-Have** für Admin-UX-Verbesserung +- Kann jederzeit später implementiert werden ohne Breaking Changes