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

┌─────────────────────────────────────────────────────────┐
│                     FRONTEND (SPA)                       │
│  Vanilla JS + Tailwind CSS + Chart.js + SortableJS      │
│  Canvas Gauges • Dark Mode • Mobile-First               │
└─────────────────┬───────────────────────────────────────┘
                  │ REST API (JWT)
┌─────────────────▼───────────────────────────────────────┐
│                   BACKEND (FastAPI)                      │
│                                                          │
│  ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌────────────┐ │
│  │ Auth     │ │Challenges│ │ Health   │ │ Analytics  │ │
│  │ /api/auth│ │/api/chal-│ │ /api/    │ │ /api/      │ │
│  │          │ │ lenges   │ │ health*  │ │ analytics  │ │
│  └──────────┘ └──────────┘ └──────────┘ └────────────┘ │
│  ┌──────────────────────────────────────────────────────┐│
│  │              Health Connect API                       ││
│  │  /api/health-connect/sync • /sync-raw • Raw Storage  ││
│  └──────────────────────────────────────────────────────┘│
│  ┌──────────────────────────────────────────────────────┐│
│  │              Service Layer                            ││
│  │  AuthService • AggregationService • HealthProvider   ││
│  └──────────────────────────────────────────────────────┘│
└─────────────────┬───────────────────────────────────────┘
                  │ SQLAlchemy ORM
┌─────────────────▼───────────────────────────────────────┐
│              DATABASE (PostgreSQL / SQLite)              │
│                                                          │
│  6 Core Tables  │  3 HC Aggregated  │  15 HC Raw Tables │
│  users          │  sync_logs        │  hc_raw_steps     │
│  challenges     │  daily_metrics    │  hc_raw_heart_*   │
│  tracking       │  exercise_sessions│  hc_raw_sleep_*   │
│  daily_health_* │                   │  hc_raw_spo2...   │
│  daily_context  │                   │  (15 total)       │
│  workout_sess.  │                   │                   │
└─────────────────┬───────────────────────────────────────┘
                  │
┌─────────────────▼───────────────────────────────────────┐
│              ANDROID COMPANION APP                       │
│  Health Connect API → Raw Records → POST /sync-raw      │
│  Kotlin • Retrofit • Jetpack • Health Connect SDK       │
│  Auto-sync • Sync History • Connection Test             │
└─────────────────────────────────────────────────────────┘

---

🧩 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é)