HabitForge/plans/plan_correction_habitforge.md

Plan de Correction - HabitForge

Date: 2025-12-30
Basé sur: revue_critique_habitforge.md
Objectif: Transformer HabitForge en une application professionnelle et production-ready

---

Vue d'ensemble

Ce plan organise les corrections nécessaires en 5 phases prioritaires, des problèmes critiques de sécurité jusqu'aux améliorations de l'expérience utilisateur.

graph TD
    A[Phase 1: Sécurité & Stabilité] --> B[Phase 2: Architecture & Qualité]
    B --> C[Phase 3: Tests & CI/CD]
    C --> D[Phase 4: Observabilité & Performance]
    D --> E[Phase 5: UX & Documentation]
    
    A --> A1[Configuration env vars]
    A --> A2[Secrets management]
    A --> A3[CORS & Rate limiting]
    A --> A4[PostgreSQL migration]
    A --> A5[HTTPS & Nginx]
    
    B --> B1[Restructuration backend]
    B --> B2[Couche de services]
    B --> B3[Modularisation frontend]
    B --> B4[DX tools]
    
    C --> C1[Tests unitaires]
    C --> C2[Tests intégration]
    C --> C3[GitHub Actions CI/CD]
    
    D --> D1[Logging structuré]
    D --> D2[Health checks]
    D --> D3[Performance DB]
    
    E --> E1[Notifications UI]
    E --> E2[Documentation]

---

Phase 1: Sécurité & Stabilité (Critique)

1.1 Configuration et Environment Variables

Objectif: Éliminer toute configuration hardcodée et sécuriser les secrets.

Étape 1.1.1: Créer le module de configuration

• Créer backend/core/config.py avec pydantic_settings
• Définir la classe Settings avec tous les paramètres
• Configurer le chargement depuis .env
• Générer SECRET_KEY avec token_urlsafe(32) par défaut

Fichiers à créer/modifier:

• backend/core/config.py (nouveau)
• backend/core/__init__.py (nouveau)

Étape 1.1.2: Créer les fichiers d'environnement

• Créer .env.example avec tous les paramètres documentés
• Créer .env.development (gitignored)
• Créer .env.staging (gitignored)
• Créer .env.production (gitignored)

Fichiers à créer:

• .env.example
• .env.development
• .env.staging
• .env.production

Étape 1.1.3: Mettre à jour .gitignore

• Ajouter .env* (sauf .env.example)
• Ajouter backend/client_secret*.json
• Ajouter data/*.db
• Ajouter __pycache__/, *.pyc, .pytest_cache/
• Ajouter .coverage, htmlcov/
• Ajouter node_modules/, .DS_Store

Fichiers à modifier:

• .gitignore

Étape 1.1.4: Migrer le code vers la configuration centralisée

• Modifier backend/auth.py pour utiliser settings.SECRET_KEY
• Modifier backend/main.py pour utiliser settings.CORS_ORIGINS
• Modifier backend/database.py pour utiliser settings.DATABASE_URL
• Modifier backend/google_fit.py pour utiliser les env vars Google

Fichiers à modifier:

• backend/auth.py
• backend/main.py
• backend/database.py
• backend/google_fit.py

---

1.2 Sécurité des Secrets

Objectif: Supprimer tous les secrets hardcodés du code.

Étape 1.2.1: Nettoyer les secrets Google

• Supprimer backend/client_secret_947199050300-boi4r9r8eekmv61h748lrvjmvp1f2v38.apps.googleusercontent.com.json
• Supprimer backend/client_secret.json du git
• Documenter la configuration des credentials Google dans .env.example

Fichiers à supprimer:

• backend/client_secret_947199050300-boi4r9r8eekmv61h748lrvjmvp1f2v38.apps.googleusercontent.com.json
• backend/client_secret.json

Étape 1.2.2: Supprimer le SECRET_KEY hardcodé

• Remplacer "supersecretkey_change_me_in_production" dans backend/auth.py
• Utiliser settings.SECRET_KEY à la place

Fichiers à modifier:

• backend/auth.py

---

1.3 CORS et Rate Limiting

Objectif: Sécuriser les accès API et prévenir les attaques DoS.

Étape 1.3.1: Configurer CORS sécurisé

• Modifier backend/main.py pour utiliser settings.CORS_ORIGINS
• Supprimer allow_origins=["*"]
• Configurer allow_credentials=True
• Configurer allow_methods et allow_headers explicites

Fichiers à modifier:

• backend/main.py

Étape 1.3.2: Ajouter rate limiting

• Installer slowapi
• Configurer Limiter dans backend/main.py
• Ajouter rate limit sur les endpoints d'authentification
• Ajouter rate limit sur les endpoints de création/modification

Fichiers à modifier:

• requirements.txt
• backend/main.py

---

1.4 Migration PostgreSQL

Objectif: Remplacer SQLite par PostgreSQL pour la production.

Étape 1.4.1: Préparer la migration

• Installer psycopg2-binary dans requirements.txt
• Créer un script de migration des données SQLite vers PostgreSQL
• Documenter le processus de migration

Fichiers à créer/modifier:

• requirements.txt
• scripts/migrate_to_postgres.py (nouveau)

Étape 1.4.2: Configurer PostgreSQL

• Mettre à jour docker-compose.yml pour PostgreSQL
• Créer docker-compose.dev.yml pour développement
• Créer docker-compose.prod.yml pour production
• Configurer les volumes persistants

Fichiers à créer/modifier:

• docker-compose.yml
• docker-compose.dev.yml (nouveau)
• docker-compose.prod.yml (nouveau)

Étape 1.4.3: Exécuter la migration

• Sauvegarder les données SQLite existantes
• Exécuter le script de migration
• Vérifier l'intégrité des données
• Mettre à jour les migrations Alembic si nécessaire

---

1.5 HTTPS et Reverse Proxy

Objectif: Sécuriser les communications en production.

Étape 1.5.1: Configurer Nginx

• Créer nginx/nginx.conf
• Configurer SSL/TLS avec Let's Encrypt
• Configurer le reverse proxy vers FastAPI
• Servir les fichiers statiques via Nginx

Fichiers à créer:

• nginx/nginx.conf (nouveau)
• nginx/Dockerfile (nouveau)

Étape 1.5.2: Configurer Gunicorn

• Installer gunicorn dans requirements.txt
• Créer un script de démarrage avec Gunicorn
• Configurer le nombre de workers

Fichiers à créer/modifier:

• requirements.txt
• scripts/start_prod.sh (nouveau)

Étape 1.5.3: Mettre à jour Docker Compose

• Ajouter le service Nginx dans docker-compose.prod.yml
• Configurer les réseaux Docker
• Configurer les health checks

Fichiers à modifier:

• docker-compose.prod.yml

---

1.6 Backups de Base de Données

Objectif: Automatiser les sauvegardes de la base de données.

Étape 1.6.1: Créer le script de backup

• Créer scripts/backup_db.sh
• Configurer la rotation des backups
• Compresser les backups
• Envoyer les backups vers un stockage externe (optionnel)

Fichiers à créer:

• scripts/backup_db.sh (nouveau)

Étape 1.6.2: Automatiser les backups

• Configurer un cron job dans Docker
• Documenter la procédure de restauration

Fichiers à modifier:

• docker-compose.prod.yml

---

Phase 2: Architecture & Qualité

2.1 Restructuration du Backend

Objectif: Organiser le code backend selon les principes de Clean Architecture.

Étape 2.1.1: Créer la nouvelle structure de dossiers

• Créer backend/api/v1/ pour les routes
• Créer backend/core/ pour la configuration et sécurité
• Créer backend/models/ pour les SQLAlchemy models
• Créer backend/schemas/ pour les Pydantic schemas
• Créer backend/services/ pour la logique métier
• Créer backend/repositories/ pour l'accès aux données
• Créer backend/integrations/ pour les APIs externes

Dossiers à créer:

• backend/api/v1/
• backend/core/
• backend/models/
• backend/schemas/
• backend/services/
• backend/repositories/
• backend/integrations/

Étape 2.1.2: Extraire les routes

• Créer backend/api/v1/auth.py avec les endpoints d'auth
• Créer backend/api/v1/challenges.py avec les endpoints challenges
• Créer backend/api/v1/health.py avec le health check
• Créer backend/api/v1/__init__.py pour l'agrégation

Fichiers à créer:

• backend/api/v1/auth.py
• backend/api/v1/challenges.py
• backend/api/v1/health.py
• backend/api/v1/__init__.py

Étape 2.1.3: Séparer models et schemas

• Déplacer les SQLAlchemy models vers backend/models/
• Créer backend/models/__init__.py
• Extraire les Pydantic schemas vers backend/schemas/
• Créer backend/schemas/__init__.py

Fichiers à créer/modifier:

• backend/models/user.py
• backend/models/challenge.py
• backend/models/tracking.py
• backend/models/__init__.py
• backend/schemas/user.py
• backend/schemas/challenge.py
• backend/schemas/tracking.py
• backend/schemas/__init__.py

Étape 2.1.4: Créer la couche de services

• Créer backend/services/auth_service.py
• Créer backend/services/challenge_service.py
• Créer backend/services/health_service.py
• Créer backend/services/__init__.py

Fichiers à créer:

• backend/services/auth_service.py
• backend/services/challenge_service.py
• backend/services/health_service.py
• backend/services/__init__.py

Étape 2.1.5: Créer la couche de repositories

• Créer backend/repositories/base.py avec le repository de base
• Créer backend/repositories/user_repository.py
• Créer backend/repositories/challenge_repository.py
• Créer backend/repositories/__init__.py

Fichiers à créer:

• backend/repositories/base.py
• backend/repositories/user_repository.py
• backend/repositories/challenge_repository.py
• backend/repositories/__init__.py

Étape 2.1.6: Déplacer les intégrations

• Déplacer backend/google_fit.py vers backend/integrations/
• Déplacer backend/import_zepp.py vers backend/integrations/
• Créer backend/integrations/__init__.py

Fichiers à déplacer/créer:

• backend/integrations/google_fit.py
• backend/integrations/import_zepp.py
• backend/integrations/__init__.py

Étape 2.1.7: Créer les modules core

• Créer backend/core/security.py avec les fonctions de sécurité
• Créer backend/core/deps.py avec les dépendances FastAPI
• Créer backend/core/__init__.py

Fichiers à créer:

• backend/core/security.py
• backend/core/deps.py
• backend/core/__init__.py

Étape 2.1.8: Simplifier main.py

• Nettoyer backend/main.py pour ne contenir que l'initialisation
• Supprimer models.Base.metadata.create_all(bind=database.engine)
• Enregistrer les routers depuis api/v1/
• Configurer le middleware de gestion d'erreurs

Fichiers à modifier:

• backend/main.py

---

2.2 Modularisation du Frontend

Objectif: Découper le fichier monolithique app.js en modules cohérents.

Étape 2.2.1: Créer la structure de modules

• Créer frontend/api/ pour les appels API
• Créer frontend/components/ pour les composants UI
• Créer frontend/utils/ pour les utilitaires
• Créer frontend/state/ pour la gestion d'état

Dossiers à créer:

• frontend/api/
• frontend/components/
• frontend/utils/
• frontend/state/

Étape 2.2.2: Créer le service API

• Créer frontend/api/client.js avec le client HTTP
• Créer frontend/api/auth.js pour les endpoints d'auth
• Créer frontend/api/challenges.js pour les endpoints challenges
• Supprimer le fetch wrapper monkey-patch

Fichiers à créer:

• frontend/api/client.js
• frontend/api/auth.js
• frontend/api/challenges.js

Étape 2.2.3: Extraire les composants UI

• Créer frontend/components/ChallengeList.js
• Créer frontend/components/ChallengeForm.js
• Créer frontend/components/TrackingForm.js
• Créer frontend/components/Charts.js
• Créer frontend/components/Navigation.js

Fichiers à créer:

• frontend/components/ChallengeList.js
• frontend/components/ChallengeForm.js
• frontend/components/TrackingForm.js
• frontend/components/Charts.js
• frontend/components/Navigation.js

Étape 2.2.4: Créer les utilitaires

• Créer frontend/utils/notifications.js pour les toasts
• Créer frontend/utils/storage.js pour localStorage
• Créer frontend/utils/date.js pour les formats de date

Fichiers à créer:

• frontend/utils/notifications.js
• frontend/utils/storage.js
• frontend/utils/date.js

Étape 2.2.5: Créer la gestion d'état

• Créer frontend/state/store.js avec un store simple
• Créer frontend/state/actions.js pour les actions
• Créer frontend/state/reducers.js pour les reducers

Fichiers à créer:

• frontend/state/store.js
• frontend/state/actions.js
• frontend/state/reducers.js

Étape 2.2.6: Simplifier app.js

• Réécrire app.js pour utiliser les modules
• Initialiser l'application
• Gérer le routing basique

Fichiers à modifier:

• frontend/app.js

---

2.3 Expérience Développeur (DX)

Objectif: Améliorer les outils de développement.

Étape 2.3.1: Configurer Ruff (linter/formatter)

• Installer ruff dans requirements.txt
• Créer ruff.toml avec la configuration
• Configurer les règles de linting

Fichiers à créer/modifier:

• requirements.txt
• ruff.toml (nouveau)

Étape 2.3.2: Configurer MyPy (type checking)

• Installer mypy dans requirements.txt
• Créer mypy.ini avec la configuration
• Ajouter les stubs nécessaires

Fichiers à créer/modifier:

• requirements.txt
• mypy.ini (nouveau)

Étape 2.3.3: Configurer pre-commit hooks

• Créer .pre-commit-config.yaml
• Configurer les hooks Ruff et MyPy
• Documenter l'installation

Fichiers à créer:

• .pre-commit-config.yaml

Étape 2.3.4: Créer un Makefile

• Créer Makefile avec les commandes de dev
• Ajouter les cibles: dev, test, lint, format, migrate

Fichiers à créer:

• Makefile

---

Phase 3: Tests & CI/CD

3.1 Tests Backend

Objectif: Mettre en place une couverture de tests minimale.

Étape 3.1.1: Configurer pytest

• Installer pytest, pytest-cov, pytest-asyncio dans requirements.txt
• Créer pytest.ini avec la configuration
• Créer tests/conftest.py avec les fixtures

Fichiers à créer/modifier:

• requirements.txt
• pytest.ini (nouveau)
• tests/conftest.py (nouveau)

Étape 3.1.2: Tests unitaires des services

• Créer tests/unit/test_auth_service.py
• Créer tests/unit/test_challenge_service.py
• Créer tests/unit/test_health_service.py

Fichiers à créer:

• tests/unit/test_auth_service.py
• tests/unit/test_challenge_service.py
• tests/unit/test_health_service.py

Étape 3.1.3: Tests d'intégration API

• Créer tests/integration/test_api_auth.py
• Créer tests/integration/test_api_challenges.py
• Créer tests/integration/test_api_health.py

Fichiers à créer:

• tests/integration/test_api_auth.py
• tests/integration/test_api_challenges.py
• tests/integration/test_api_health.py

Étape 3.1.4: Tests E2E

• Créer tests/e2e/test_user_flow.py
• Tester le flux complet: inscription → login → création challenge → tracking

Fichiers à créer:

• tests/e2e/test_user_flow.py

---

3.2 CI/CD avec GitHub Actions

Objectif: Automatiser les tests et le déploiement.

Étape 3.2.1: Créer le workflow CI

• Créer .github/workflows/ci.yml
• Configurer le job de tests
• Configurer le job de linting
• Configurer le reporting de couverture

Fichiers à créer:

• .github/workflows/ci.yml

Étape 3.2.2: Créer le workflow CD

• Créer .github/workflows/cd.yml
• Configurer le déploiement vers staging
• Configurer le déploiement vers production

Fichiers à créer:

• .github/workflows/cd.yml

---

Phase 4: Observabilité & Performance

4.1 Observabilité

Objectif: Mettre en place le monitoring et le logging.

Étape 4.1.1: Logging structuré

• Installer python-json-logger dans requirements.txt
• Créer backend/core/logging.py
• Configurer le logging JSON
• Remplacer les print() par des logger.info()

Fichiers à créer/modifier:

• requirements.txt
• backend/core/logging.py

Étape 4.1.2: Health check endpoint

• Créer le endpoint /api/health
• Vérifier la connexion à la base de données
• Retourner le statut de l'application

Fichiers à modifier:

• backend/api/v1/health.py

Étape 4.1.3: Métriques Prometheus

• Installer prometheus-fastapi-instrumentator dans requirements.txt
• Configurer l'instrumentation dans main.py
• Exposer le endpoint /metrics

Fichiers à créer/modifier:

• requirements.txt
• backend/main.py

---

4.2 Performance Base de Données

Objectif: Optimiser les requêtes et l'indexation.

Étape 4.2.1: Ajouter des indexes

• Créer une migration Alembic pour les indexes
• Ajouter index sur challenges(user_id, display_order)
• Ajouter index sur challenges(user_id, period_type)
• Ajouter index sur tracking(challenge_id, date)
• Ajouter index sur tracking(date)

Fichiers à créer:

• alembic/versions/xxxx_add_indexes.py

Étape 4.2.2: Eager loading

• Modifier les repositories pour utiliser selectinload
• Éliminer les N+1 queries
• Optimiser les requêtes d'agrégation

Fichiers à modifier:

• backend/repositories/challenge_repository.py

Étape 4.2.3: Pagination

• Ajouter la pagination aux endpoints de liste
• Créer les schemas de pagination
• Documenter les paramètres de pagination

Fichiers à créer/modifier:

• backend/schemas/pagination.py
• backend/api/v1/challenges.py

---

Phase 5: UX & Documentation

5.1 Améliorations UX

Objectif: Améliorer l'expérience utilisateur.

Étape 5.1.1: Notifications/Toasts

• Créer le système de notifications dans frontend/utils/notifications.js
• Ajouter des toasts pour les actions réussies
• Ajouter des toasts pour les erreurs

Fichiers à créer:

• frontend/utils/notifications.js

Étape 5.1.2: Loading states

• Ajouter des spinners pendant les appels API
• Désactiver les boutons pendant le chargement
• Ajouter des indicateurs de progression

Fichiers à modifier:

• frontend/components/ChallengeForm.js
• frontend/components/TrackingForm.js

Étape 5.1.3: Gestion d'erreurs utilisateur

• Afficher des messages d'erreur clairs
• Proposer des solutions aux erreurs courantes
• Logger les erreurs côté client

Fichiers à modifier:

• frontend/api/client.js
• frontend/app.js

---

5.2 Documentation

Objectif: Documenter le projet pour les développeurs.

Étape 5.2.1: Docstrings API

• Ajouter des docstrings à toutes les fonctions
• Documenter les paramètres et les retours
• Utiliser le format Google ou NumPy

Fichiers à modifier:

• Tous les fichiers Python dans backend/

Étape 5.2.2: README amélioré

• Mettre à jour README.md
• Ajouter la section Installation
• Ajouter la section Configuration
• Ajouter la section Développement
• Ajouter la section Déploiement

Fichiers à modifier:

• README.md

Étape 5.2.3: Architecture Decision Records (ADRs)

• Créer docs/adr/
• Documenter les décisions d'architecture majeures
• Utiliser le template ADR standard

Fichiers à créer:

• docs/adr/001-architecture-backend.md
• docs/adr/002-choix-postgresql.md
• docs/adr/003-securite-jwt.md

---

Résumé des Fichiers à Créer

Configuration

• .env.example
• .env.development
• .env.staging
• .env.production
• ruff.toml
• mypy.ini
• pytest.ini
• .pre-commit-config.yaml
• Makefile

Backend - Core

• backend/core/config.py
• backend/core/security.py
• backend/core/deps.py
• backend/core/logging.py
• backend/core/__init__.py

Backend - API

• backend/api/v1/auth.py
• backend/api/v1/challenges.py
• backend/api/v1/health.py
• backend/api/v1/__init__.py

Backend - Models

• backend/models/user.py
• backend/models/challenge.py
• backend/models/tracking.py
• backend/models/__init__.py

Backend - Schemas

• backend/schemas/user.py
• backend/schemas/challenge.py
• backend/schemas/tracking.py
• backend/schemas/pagination.py
• backend/schemas/__init__.py

Backend - Services

• backend/services/auth_service.py
• backend/services/challenge_service.py
• backend/services/health_service.py
• backend/services/__init__.py

Backend - Repositories

• backend/repositories/base.py
• backend/repositories/user_repository.py
• backend/repositories/challenge_repository.py
• backend/repositories/__init__.py

Backend - Integrations

• backend/integrations/google_fit.py
• backend/integrations/import_zepp.py
• backend/integrations/__init__.py

Frontend - API

• frontend/api/client.js
• frontend/api/auth.js
• frontend/api/challenges.js

Frontend - Components

• frontend/components/ChallengeList.js
• frontend/components/ChallengeForm.js
• frontend/components/TrackingForm.js
• frontend/components/Charts.js
• frontend/components/Navigation.js

Frontend - Utils

• frontend/utils/notifications.js
• frontend/utils/storage.js
• frontend/utils/date.js

Frontend - State

• frontend/state/store.js
• frontend/state/actions.js
• frontend/state/reducers.js

Tests

• tests/conftest.py
• tests/unit/test_auth_service.py
• tests/unit/test_challenge_service.py
• tests/unit/test_health_service.py
• tests/integration/test_api_auth.py
• tests/integration/test_api_challenges.py
• tests/integration/test_api_health.py
• tests/e2e/test_user_flow.py

CI/CD

• .github/workflows/ci.yml
• .github/workflows/cd.yml

Docker & Nginx

• docker-compose.dev.yml
• docker-compose.prod.yml
• nginx/nginx.conf
• nginx/Dockerfile

Scripts

• scripts/migrate_to_postgres.py
• scripts/backup_db.sh
• scripts/start_prod.sh

Documentation

• docs/adr/001-architecture-backend.md
• docs/adr/002-choix-postgresql.md
• docs/adr/003-securite-jwt.md

---

Checklist de Validation

Avant de considérer le projet comme "production-ready", vérifier:

Sécurité

• Aucun secret hardcodé dans le code
• CORS configuré avec des origines spécifiques
• Rate limiting activé
• HTTPS configuré en production
• Secrets Google exclus du git

Base de Données

• PostgreSQL utilisé en production
• Backups automatisés en place
• Indexes créés sur les colonnes fréquentes
• N+1 queries éliminées

Architecture

• Backend restructuré avec séparation des responsabilités
• Couche de services créée
• Frontend modularisé
• Configuration centralisée

Tests

• Tests unitaires backend créés
• Tests d'intégration API créés
• Tests E2E créés
• Couverture minimale de 70%

CI/CD

• Pipeline CI configuré
• Pipeline CD configuré
• Tests exécutés automatiquement

Observabilité

• Logging structuré en place
• Health check endpoint créé
• Métriques Prometheus exposées

DX

• Linter configuré (Ruff)
• Type checker configuré (MyPy)
• Pre-commit hooks configurés
• Makefile créé

Documentation

• README à jour
• Docstrings ajoutées
• ADRs créés

---

Notes Importantes

1. Ordre d'exécution: Les phases doivent être exécutées dans l'ordre indiqué. La Phase 1 (Sécurité) est critique et doit être complétée avant tout déploiement en production.

2. Tests continus: À chaque étape, exécuter les tests existants pour s'assurer que rien n'est cassé.

3. Documentation: Mettre à jour la documentation à mesure que des changements sont apportés.

4. Commits: Faire des commits fréquents et descriptifs pour faciliter le rollback si nécessaire.

5. Review: Faire une revue de code après chaque phase majeure.

---

Fin du Plan de Correction