# 🗺️ 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é) |