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

```mermaid
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é) |