HabitForge/ROADMAP.md

🗺️ HabitForge - Roadmap

État des lieux et vision future du projet

---

📋 Ce qui est fait ✅

🏗️ Infrastructure

Fonctionnalité	Statut	Détails
Docker (simple SQLite)	✅	docker-compose.yml - déploiement rapide
Docker Dev (PostgreSQL + CloudBeaver)	✅	docker-compose.dev.yml - DB admin UI
Docker Prod (Nginx + Gunicorn + Backup)	✅	docker-compose.prod.yml - prêt production
Environnements (.env)	✅	.env.development, .env.staging, .env.production
Alembic Migrations	✅	9 migrations, support SQLite & PostgreSQL
Rate Limiting	✅	SlowAPI avec config par env
Git LFS	✅	GIFs des exercices stockés via LFS

🔐 Authentification

Fonctionnalité	Statut	Détails
JWT Auth (OAuth2 Password Flow)	✅	Access + Refresh tokens
Registration	✅	POST /api/auth/register
Login	✅	POST /api/auth/token
Token Refresh	✅	POST /api/auth/refresh
Password Hashing (Argon2)	✅	Passlib + argon2-cffi
Google OAuth (configuré)	✅	Client ID/Secret dans config

🎯 Challenges & Tracking (Core)

Fonctionnalité	Statut	Détails
CRUD Challenges	✅	Création, lecture, modification, suppression
Types de périodes	✅	Jour, Semaine, Mois, Année
Unités variées	✅	reps, minutes, pages, km
Jours de repos	✅	Configuration par défi
Fréquence custom	✅	Jours spécifiques de la semaine
Icônes (FontAwesome)	✅	15+ icônes disponibles
Images d'exercice (GIFs)	✅	15 exercices animés
Descriptions	✅	Texte descriptif par défi
Réordonnancement (Drag & Drop)	✅	SortableJS
Suivi quotidien	✅	Reps, completed, notes
Statistiques	✅	Reps totales, streak, taux de complétion
Heatmap de consistance	✅	Vue calendrier

📊 Health Dashboard

Fonctionnalité	Statut	Détails
Métriques quotidiennes	✅	Steps, calories, distance, sleep, HR, SpO2
Widgets Weight & BMI	✅	Jauges semi-circulaires Canvas
Graphiques d'historique	✅	Chart.js (7j, 30j, 365j)
Périodes (day/week/month/year)	✅	Navigation par date
Sessions d'entraînement	✅	Liste + résumé par type
Contexte utilisateur	✅	Mood score, tags, notes

📱 Android Companion App

Fonctionnalité	Statut	Détails
Lecture Health Connect	✅	Tous les types de données supportés
Sync manuelle	✅	Bouton Sync Now
Auto-sync configurable	✅	1h, 3h, 6h, 12h, 24h
Authentification JWT	✅	Mêmes credentials que le web
Historique des syncs	✅	Succès/échec, compteurs
Test de connexion serveur	✅	Ping + temps de réponse
Validation schéma données	✅	DataCompatibilityValidator
Indicateur statut serveur	✅	Online/Auth/Timeout/Offline
Configuration serveur	✅	URL + credentials

🔄 Intégrations & Data Pipeline

Fonctionnalité	Statut	Détails
Health Connect → Raw Storage	✅	15 tables raw avec déduplication
Raw → Aggregation Service	✅	Agrégation on-demand par jour/semaine/mois
Health Analytics API	✅	/api/analytics/daily, /api/analytics/range
Readiness Score	✅	Score mental + physique avec recommandations
Source filtering	✅	Filtrage par source de données
Zepp Data Import	✅	Script CSV → DB (activité, sommeil, HR, workouts)
Provider abstraction	✅	HealthProviderFactory (extensible)
Sync logs	✅	Traçabilité complète des batchs

🎨 Frontend

Fonctionnalité	Statut	Détails
Design Mobile-First	✅	Tailwind CSS responsive
Dark Mode	✅	Toggle avec persistance localStorage
Jauges Canvas	✅	Animations semi-circulaires
Graphiques Chart.js	✅	Steps, calories, HR, poids
Drag & Drop	✅	Réordonnancement challenges
Modal détails métriques	✅	Weight/BMI détaillé
Page login	✅	Auth + redirection
Navigation par onglets	✅	Challenges, Health, Settings

---

🚧 En cours / Planifié

Phase 2 — Améliorations Core (Priorité Haute)

Fonctionnalité	Priorité	Notes
UX Onboarding	🔴 P0	Wizard de bienvenue, premier challenge, connexion appareil
Tests automatisés	🔴 P0	pytest pour backend, tests API, tests modèles
Validation Pydantic stricte	🔴 P0	Schémas request/response complets
Gestion d'erreurs frontend	🔴 P0	Toasts, retry, messages utilisateur
Cache d'agrégation	🟡 P1	Redis ou cache DB pour les requêtes analytics
CI/CD Pipeline	🟡 P1	GitHub Actions: lint, test, build docker
Seed data / Fixtures	🟡 P1	Données de démo pour nouveaux utilisateurs

Phase 3 — Santé & Analytics (Priorité Haute)

Fonctionnalité	Priorité	Notes
Corrélations santé/habitudes	🔴 P0	Impact du sommeil/steps sur la complétion des défis
Dashboard unifié	🔴 P0	Challenges + Santé sur une seule vue
Rapports hebdomadaires	🟡 P1	Email ou résumé in-app
Export données	🟡 P1	CSV/JSON de toutes les métriques
Objectifs de santé	🟡 P1	Cibles steps, sommeil, calories
Alertes / Notifications	🟢 P2	Web push ou email pour streaks, objectifs
ML Scoring avancé	🟢 P2	Prédictions de readiness, recommandations personnalisées

Phase 4 — Social & Gamification

Fonctionnalité	Priorité	Notes
Badges & Achievements	🟡 P1	Badges par streak, total reps, milestones
Niveaux / XP	🟢 P2	Système de progression
Classements	🟢 P2	Leaderboards entre amis
Partage social	🟢 P2	Partage de réussites
Défis de groupe	🔵 P3	Défis multi-utilisateurs

Phase 5 — Mobile & Plateforme

Fonctionnalité	Priorité	Notes
Google Play Store	🟡 P1	Publication companion app
iOS Companion (Swift/KMP)	🔵 P3	Application iOS native ou KMP
PWA	🟡 P1	Service worker, notifications push, offline
Multi-langue (i18n)	🟢 P2	Support FR/EN minimum
Admin panel	🔵 P3	Gestion utilisateurs, monitoring

Phase 6 — Infrastructure

Fonctionnalité	Priorité	Notes
Health endpoint monitoring	🟡 P1	Prometheus + Grafana
DB Connection pooling	🟡 P1	Optimisation PostgreSQL
CDN pour assets statiques	🟢 P2	GIFs, CSS, JS
Kubernetes Helm chart	🔵 P3	Déploiement scalable
Multi-tenant	🔵 P3	Isolation par organisation

---

📐 Architecture Actuelle

graph TB
    subgraph FRONTEND["🖥️ FRONTEND (SPA)"]
        direction LR
        FE_TECH["Vanilla JS · Tailwind CSS · Chart.js · SortableJS<br/>Canvas Gauges · Dark Mode · Mobile-First"]
    end

    subgraph BACKEND["⚙️ BACKEND (FastAPI)"]
        direction TB
        subgraph ROUTES["Routes API"]
            AUTH["🔐 Auth<br/>/api/auth"]
            CHAL["🎯 Challenges<br/>/api/challenges"]
            HEALTH["❤️ Health<br/>/api/health*"]
            ANALYTICS["📊 Analytics<br/>/api/analytics"]
            HC_API["📱 Health Connect<br/>/api/health-connect/sync-raw"]
        end
        subgraph SERVICES["Service Layer"]
            AUTH_SVC["AuthService"]
            AGG_SVC["AggregationService"]
            HP["HealthProvider"]
        end
        ROUTES --> SERVICES
    end

    subgraph DB["🗄️ DATABASE (PostgreSQL / SQLite)"]
        direction LR
        subgraph CORE["6 Core Tables"]
            CORE_T["users · challenges · tracking<br/>daily_health_metrics<br/>daily_context · workout_sessions"]
        end
        subgraph HC_AGG["3 HC Aggregated"]
            HC_T["sync_logs · daily_metrics<br/>exercise_sessions"]
        end
        subgraph HC_RAW["15 HC Raw Tables"]
            RAW_T["hc_raw_steps · heart_rate · sleep_*<br/>spo2 · weight · calories · distance<br/>exercise · nutrition · hydration · hrv"]
        end
    end

    subgraph ANDROID["📱 ANDROID COMPANION"]
        ANDROID_TECH["Kotlin · Retrofit · Health Connect SDK<br/>Auto-sync · Sync History · Connection Test"]
    end

    FRONTEND -->|"REST API (JWT)"| BACKEND
    BACKEND -->|"SQLAlchemy ORM"| DB
    ANDROID -->|"POST /sync-raw"| HC_API
    ANDROID -.->|"Health Connect API"| HC["🏥 Android Health Connect"]
    HC -->|"Raw Records"| ANDROID

    style FRONTEND fill:#1e293b,stroke:#38bdf8,color:#e2e8f0
    style BACKEND fill:#1e293b,stroke:#10b981,color:#e2e8f0
    style DB fill:#1e293b,stroke:#f59e0b,color:#e2e8f0
    style ANDROID fill:#1e293b,stroke:#a78bfa,color:#e2e8f0
    style HC fill:#1e293b,stroke:#ef4444,color:#e2e8f0
    style ROUTES fill:#0f172a,color:#e2e8f0
    style SERVICES fill:#0f172a,color:#e2e8f0
    style CORE fill:#0f172a,color:#e2e8f0
    style HC_AGG fill:#0f172a,color:#e2e8f0
    style HC_RAW fill:#0f172a,color:#e2e8f0

---

🧩 API Endpoints

Méthode	Endpoint	Description
POST	/api/auth/register	Créer un compte
POST	/api/auth/token	Login (JWT)
POST	/api/auth/refresh	Rafraîchir le token
GET	/api/auth/me	Profil utilisateur
GET	/api/challenges	Liste des défis
POST	/api/challenges	Créer un défi
PUT	/api/challenges/{id}	Modifier un défi
DELETE	/api/challenges/{id}	Supprimer un défi
PUT	/api/challenges/reorder	Réordonner
POST	/api/tracking	Logger une répétition
GET	/api/tracking/{challenge_id}	Historique tracking
GET	/api/health	Health check
GET	/api/health/stats	Stats de santé (période)
GET	/api/health/workouts	Liste workouts
GET	/api/health/workouts/summary	Résumé workouts
POST	/api/health-connect/sync	Sync Health Connect (legacy)
POST	/api/health-connect/sync-raw	Sync données brutes
GET	/api/health-connect/sync/status	Statut sync
GET	/api/analytics/daily	Analytics quotidien
GET	/api/analytics/range	Analytics plage de dates
POST	/api/analytics/context	Mise à jour contexte (mood)
GET	/api/analytics/sources	Sources de données disponibles
GET	/api/static/images	Liste images disponibles

---

🔑 Choix Techniques

Domaine	Choix	Raison
Backend	FastAPI	Performance async, Swagger auto, validation Pydantic
ORM	SQLAlchemy 2.0	Maturité, flexibilité SQLite/PostgreSQL
Auth	JWT + Argon2	Stateless, sécurisé, standard OAuth2
Frontend	Vanilla JS + Tailwind	Zéro build step, rapide, Tailwind CDN
Charts	Chart.js	Léger, bonne API, canvas performant
Mobile	Kotlin natif	Accès direct Health Connect SDK Android
DB	PostgreSQL (prod) / SQLite (dev)	Flexibilité selon environnement
Infra	Docker Compose	Simple, reproductible, 3 profils
LFS	Git LFS	GIFs lourds sans gonfler le repo

---

📈 Métriques du Projet

Métrique	Valeur
Tables DB	25
Endpoints API	22+
Migrations Alembic	9
Modèles Python	25+
Schémas Pydantic	10+
Services	5 (auth, challenge, health, aggregation, provider)
Fichiers Android (Kotlin)	17
Tests	0 ❌ (priorité P0)
Linting	ruff (configuré)