mitai-jinkendo/docs/issues/issue-50-phase-0a-goal-system.md

Phase 0a: Minimal Goal System (Strategic + Tactical)

Status: ✅ ABGESCHLOSSEN (26.03.2026) Labels: feature, enhancement, goal-system Priority: High (Foundation for Phase 0b) Aufwand: 3-4h (geschätzt) / ~4h (tatsächlich)

---

Beschreibung

Implementierung des minimalen Zielsystems als Basis für goal-aware KI-Analysen. Zwei-Ebenen-Architektur:

• Strategic Layer: Goal Modes (beeinflusst Score-Gewichtung)
• Tactical Layer: Konkrete Zielwerte mit Progress-Tracking

---

Implementiert ✅

Strategic Layer (Goal Modes)

• goal_mode in profiles table
• 5 Modi: weight_loss, strength, endurance, recomposition, health
• Bestimmt Score-Gewichtung für alle KI-Analysen
• UI: 5 Goal Mode Cards mit Beschreibungen und Icons

Tactical Layer (Concrete Goals)

• goals table mit vollständigem Tracking:
  • Target/Current/Start values
  • Progress percentage (auto-calculated)
  • Projection date & on-track status
  • Primary/Secondary goal concept
  • 8 Goal-Typen: weight, body_fat, lean_mass, vo2max, strength, flexibility, bp, rhr
• UI:
  • Goal CRUD mit Fortschrittsbalken
  • Mobile-friendly Design (full-width inputs, labels above fields)
  • Inline editing vorbereitet

Training Phases Framework

• training_phases table (Auto-Detection vorbereitet für Phase 2)
• 5 Phase-Typen: calorie_deficit, calorie_surplus, deload, maintenance, periodization
• Status-Flow: suggested → accepted → active → completed → rejected
• Confidence scoring für KI-basierte Erkennung
• JSONB detection_params für Flexibilität

Fitness Tests

• fitness_tests table für standardisierte Tests
• 8 Test-Typen: cooper_12min, step_test, pushups_max, plank_max, flexibility_sit_reach, vo2max_est, strength_1rm_squat, strength_1rm_bench
• Norm-Kategorisierung vorbereitet (age/gender-spezifisch)
• Baseline-Tracking für Fortschrittsmessung

---

Technische Umsetzung

Backend

Migration 022: backend/migrations/022_goal_system.sql

-- Strategic Layer
ALTER TABLE profiles ADD COLUMN goal_mode VARCHAR(50) DEFAULT 'health';

-- Tactical Layer
CREATE TABLE goals (...);
CREATE TABLE training_phases (...);
CREATE TABLE fitness_tests (...);

Router: backend/routers/goals.py (490 Zeilen)

• Vollständiges CRUD für alle 3 Ebenen
• Progress calculation (auto-update current values)
• Linear projection für target_date
• Helper functions für goal-type spezifische Current-Values

API Endpoints: /api/goals/*

• GET/PUT /mode - Strategic goal mode
• GET /list - All goals with progress
• POST /create - Create goal
• PUT /{id} - Update goal
• DELETE /{id} - Delete goal
• GET/POST /phases - Training phases
• PUT /phases/{id}/status - Accept/reject auto-detected phases
• GET/POST /tests - Fitness tests

Frontend

GoalsPage: frontend/src/pages/GoalsPage.jsx (570 Zeilen)

• Goal Mode Selector: 5 Karten mit Icons, Farben, Beschreibungen
• Goal List: Cards mit Progress-Balken, Projection-Display, Edit/Delete
• Goal Form: Mobile-optimiertes Modal
  • Full-width inputs
  • Labels above fields (not beside)
  • Section headers with emoji (🎯 Zielwert)
  • Unit display as styled badge
  • Primary goal checkbox in highlighted section
  • Text-align: left für Text-Felder, right für Zahlen
• Empty State: Placeholder mit CTA

Navigation Integration:

• Dashboard: Goals Preview Card mit "Verwalten →" Link
• Analysis Page: 🎯 Ziele Button neben Titel (direkter Zugang)
• Route: /goals in App.jsx registriert

api.js: 15+ neue API-Funktionen

// Goal Modes
getGoalMode(), updateGoalMode(mode)

// Goals CRUD
listGoals(), createGoal(data), updateGoal(id, data), deleteGoal(id)

// Training Phases
listTrainingPhases(), createTrainingPhase(data), updatePhaseStatus(id, status)

// Fitness Tests
listFitnessTests(), createFitnessTest(data)

---

Commits

Commit	Beschreibung
337667f	feat: Phase 0a - Minimal Goal System (Strategic + Tactical)
906a3b7	fix: Migration 022 - remove invalid schema_migrations tracking
75f0a5d	refactor: mobile-friendly goal form design
5be52bc	feat: goals navigation + UX improvements

Branch: develop Deployed to: dev.mitai.jinkendo.de ✅

---

Dokumentation

• ✅ docs/GOALS_SYSTEM_UNIFIED_ANALYSIS.md (538 Zeilen)
  • Analyse beider Fachkonzepte (Konzept v2 + GOALS_VITALS.md)
  • Zwei-Ebenen-Architektur erklärt
  • 120+ Placeholder-Kategorisierung für Phase 0b
• ✅ Migration 022 mit vollständigen COMMENT ON statements
• ✅ API-Dokumentation in Router-Docstrings
• ✅ Dieses Issue-Dokument

---

Basis für Phase 0b

Phase 0a bietet die Foundation für:

Phase 0b: Goal-Aware Placeholders (16-20h)

• ✅ 120+ neue Platzhalter die goal_mode berücksichtigen
• ✅ Score-Berechnungen abhängig von Strategic Layer
• ✅ Baseline-Berechnungen (7d/28d/90d Trends)
• ✅ Lag-basierte Korrelationen
• ✅ Confidence Scoring

Beispiel Goal-Mode Impact:

# Gleiche Daten, unterschiedliche Interpretation:
Δ: -5kg FM, -2kg LBM

goal_mode = "weight_loss"
  → body_progress_score = 78/100 (FM↓ gut, LBM↓ tolerierbar)

goal_mode = "strength"
  → body_progress_score = 32/100 (LBM↓ ist KATASTROPHE!)

goal_mode = "health"
  → body_progress_score = 50/100 (neutral, ohne Bias)

---

Testing

✅ Migration erfolgreich auf dev.mitai.jinkendo.de ✅ Goal Mode wechselbar ✅ Goal CRUD funktioniert ✅ Progress calculation korrekt ✅ Mobile UI responsive ✅ Navigation von Dashboard + Analysis

Manuelle Tests durchgeführt:

• Goal Mode ändern
• Ziel erstellen (alle 8 Typen)
• Ziel bearbeiten
• Ziel löschen
• Primary Goal setzen
• Progress-Balken korrekt
• Mobile UI full-width
• Text-Align korrekt

---

Akzeptanzkriterien

• Migration 022 erfolgreich
• Goal Mode in profiles funktioniert
• Goals CRUD vollständig
• Progress-Tracking funktioniert
• Primary Goal Konzept implementiert
• Mobile-friendly UI
• Navigation von 2+ Stellen
• API-Dokumentation vollständig
• Frontend form validation
• Error handling korrekt

---

Nächste Schritte

Empfohlen:

1. Option A: Issue #49 - Prompt Page Assignment (6-8h)

   • Prompts auf Verlaufsseiten zuordnen
   • Quick Win für bessere UX
   • Nutzt bestehendes Unified Prompt System

2. Option B: Phase 0b - Goal-Aware Placeholders (16-20h)

   • 120+ neue Platzhalter
   • Score-Berechnungen mit goal_mode
   • Größter strategischer Impact

Siehe: docs/NEXT_STEPS_2026-03-26.md für detaillierte Planung

---

Lessons Learned

Was gut lief:

• ✅ Zwei-Ebenen-Architektur (Strategic + Tactical) macht Sinn
• ✅ Mobile-first Design von Anfang an
• ✅ Unified Analysis vor Implementierung (beide Fachkonzepte)
• ✅ Migration-System funktioniert einwandfrei

Was zu beachten ist:

• ⚠️ Schema_migrations verwendet filename, nicht version
• ⚠️ Unnötige DO-Blocks in Migrationen vermeiden
• ⚠️ Text-align: right als Default in form-input (für Textfelder überschreiben)

---

Erstellt: 26. März 2026 Status: ✅ COMPLETE - Ready for Phase 0b Related Issues: #49 (Prompt Assignment), #47 (Value Table Refinement)