# 🎯 PLAN LOGIQUE - Refonte du Système Chartbastan **Date** : 2026-01-17 **Auteur** : AI Agent **Objectif** : Structurer le développement selon les Epics et créer des User Stories précises --- ## 📊 Analyse de la Situation Actuelle ### 🐛 Problèmes Identifiés #### Problème 1 : Base de données partagée MAL configurée - **Description** : Le backend utilise `../chartbastan.db` (chemin relatif) au lieu d'un chemin absolu - **Impact** : Le frontend (Next.js) et le backend (FastAPI) utilisent potentiellement deux fichiers différents - **Solution** : Créer une configuration centralisée dans `config_db.py` #### Problème 2 : Pas de vérification des matchs existants - **Description** : Le script `run_all_system.py` crée des matchs à chaque exécution sans vérifier s'ils existent déjà - **Impact** : Doublons dans la base de données si on exécute plusieurs fois - **Solution** : Vérifier l'existence avant création, et proposer l'option de nettoyage #### Problème 3 : Pas de mise à jour des résultats réels (actual_winner) - **Description** : Le modèle `Match` a un champ `actual_winner` mais il n'est jamais utilisé - **Impact** : Impossible de comparer les prédictions aux résultats réels pour le backtesting - **Solution** : Créer un endpoint ou un script pour mettre à jour le vainqueur après le match #### Problème 4 : Pas de régénération des prédictions - **Description** : Une fois qu'une prédiction est créée, elle n'est jamais mise à jour même si de nouvelles données arrivent - **Impact** : Les prédictions restent statiques et ne reflètent pas l'énergie dynamique - **Solution** : Implémenter la suppression/régénération des prédictions obsolètes --- ## 🎯 Stratégie de Refonte ### Phase 1 : Stabiliser l'Infrastructure (Semaine 1) **Objectif** : Créer une base technique solide et partagée **Tâches** : - [ ] Créer `config_db.py` avec configuration centralisée (chemin absolu, validation) - [ ] Mettre à jour `database.py` pour utiliser `config_db.py` - [ ] Mettre à jour tous les scripts Python pour importer `DATABASE_URL` depuis `config_db.py` - [ ] Mettre à jour `.env` pour utiliser la même logique - [ ] Tester que frontend et backend accèdent bien à la même base **Critères de Succès** : - ✅ Un seul fichier de configuration centralisé - ✅ Frontend et backend utilisent la même base de données - ✅ Pas de chemins relatifs fragiles --- ### Phase 2 : Structurer le Backend FastAPI (Semaine 2) **Objectif** : Organiser le code backend selon les Epics **Tâches par Epic** : #### Epic 2 : Data Collection & Energy Analysis - [ ] **Tâche 2.1** : Créer endpoint `POST /api/v1/matches` pour créer des matchs manuellement - [ ] **Tâche 2.2** : Créer endpoint `GET /api/v1/matches` avec filtres (ligue, équipe, date) - [ ] **Tâche 2.3** : Créer endpoint `PUT /api/v1/matches/{id}` pour mettre à jour un match - [ ] **Tâche 2.4** : Créer endpoint `PATCH /api/v1/matches/{id}/result` pour mettre à jour le vainqueur - [ ] **Tâche 2.5** : Créer script de scraping réel Twitter (si API disponible) - [ ] **Tâche 2.6** : Créer script de scraping réel Reddit (si API disponible) - [ ] **Tâche 2.7** : Créer script de scraping RSS - [ ] **Tâche 2.8** : Intégrer les scrapers dans le pipeline (ou utiliser RabbitMQ) #### Epic 3 : Prediction System & Backtesting - [ ] **Tâche 3.1** : Créer endpoint `POST /api/v1/predictions/regenerate` pour régénérer une prédiction - [ ] **Tâche 3.2** : Créer endpoint `DELETE /api/v1/predictions/{id}` pour supprimer une prédiction - [ ] **Tâche 3.3** : Implémenter la mise à jour automatique du vainqueur quand un match se termine - [ ] **Tâche 3.4** : Créer endpoint `GET /api/v1/backtesting/stats` pour les stats globales - [ ] **Tâche 3.5** : Créer endpoint `GET /api/v1/backtesting/match/{id}` pour stats d'un match spécifique #### Epic 4 : User Authentication & Access Control - [ ] **Tâche 4.1** : Créer endpoint `GET /api/v1/auth/me` pour profil utilisateur connecté - [ ] **Tâche 4.2** : Créer endpoint `PUT /api/v1/auth/me` pour mettre à jour le profil - [ ] **Tâche 4.3** : Implémenter la déconnexion côté backend (DELETE session) - [ ] **Tâche 4.4** : Créer endpoint `POST /api/v1/auth/forgot-password` (optionnel) #### Epic 5 : Dashboard & Core Visualizations - [ ] **Tâche 5.1** : Créer endpoint `GET /api/v1/dashboard/summary` pour dashboard utilisateur - [ ] **Tâche 5.2** : Créer endpoint `GET /api/v1/energy/timeline/{match_id}` pour l'évolution 24h - [ ] **Tâche 5.3** : Créer endpoint `GET /api/v1/energy/live/{match_id}` pour l'énergie temps réel #### Epic 6 : User Experience & Engagement - [ ] **Tâche 6.1** : Créer endpoint `POST /api/v1/newsletter/subscribe` - [ ] **Tâche 6.2** : Créer endpoint `POST /api/v1/onboarding/start` et `complete` #### Epic 7 : Gamification & Social Features - [ ] **Tâche 7.1** : Créer endpoint `POST /api/v1/referral/generate` pour générer code - [ ] **Tâche 7.2** : Créer endpoint `POST /api/v1/referral/track` pour tracker parrainages - [ ] **Tâche 7.3** : Créer endpoint `POST /api/v1/badges/unlock/{id}` pour débloquer manuellement #### Epic 8 : Notifications & Alerts - [ ] **Tâche 8.1** : Créer endpoint `GET /api/v1/notifications` - [ ] **Tâche 8.2** : Créer endpoint `PUT /api/v1/notifications/{id}/read` pour marquer comme lu - [ ] **Tâche 8.3** : Créer endpoint `POST /api/v1/notifications/preferences` #### Epic 9 : Advanced Features & API (Phase 2+) - [ ] **Tâche 9.1** : Créer endpoint `GET /api/v1/public/matches` (API publique read-only) --- ### Phase 3 : Structurer le Frontend Next.js (Semaine 3-4) **Objectif** : Organiser le code frontend selon les Epics **Tâches par Epic** : #### Epic 4 : User Authentication & Access Control - [ ] **Tâche 4.1** : Créer `lib/auth.ts` centralisé avec API calls - [ ] **Tâche 4.2** : Créer composant `Login.tsx` robust avec validation - [ ] **Tâche 4.3** : Créer composant `Register.tsx` robust avec validation - [ ] **Tâche 4.4** : Créer hook `useAuth()` pour gestion session #### Epic 5 : Dashboard & Core Visualizations - [ ] **Tâche 5.1** : Créer composant `ConfidenceMeter.tsx` avec code couleur dynamique - [ ] **Tâche 5.2** : Créer composant `EnergyWave.tsx` (visualisation D3.js) - [ ] **Tâche 5.3** : Créer composant `PredictionCard.tsx` avec détails complets - [ ] **Tâche 5.4** : Créer composant `MatchList.tsx` avec filtres et tri - [ ] **Tâche 5.5** : Créer composant `DashboardLayout.tsx` avec navigation optimisée #### Epic 7 : Gamification & Social Features - [ ] **Tâche 7.1** : Créer composant `Leaderboard.tsx` - [ ] **Tâche 7.2** : Créer composant `BadgeCard.tsx` - [ ] **Tâche 7.3** : Créer composant `ReferralSystem.tsx` --- ## 🎯 User Stories (Draft) Basées sur le PRD, les user stories suivantes sont à créer : ### Épic 4 : User Authentication & Access Control **User Story 4.1 : Création de compte** - **En tant que** : Nouvel utilisateur - **Je veux** : Créer un compte sur Chartbastan - **Pour que** : Je puisse accéder au dashboard et consulter les prédictions - **Critères de succès** : - Je peux m'inscrire avec email et mot de passe - Mon compte est créé et je suis automatiquement connecté - Un email de confirmation m'est envoyé (optionnel) **User Story 4.2 : Connexion** - **En tant que** : Utilisateur enregistré - **Je veux** : Me connecter à mon compte Chartbastan - **Pour que** : Je puisse accéder au dashboard personnalisé - **Critères de succès** : - Je peux me connecter avec mes identifiants - Je reste connecté entre les sessions - En cas d'erreur, un message clair est affiché ### Épic 5 : Dashboard & Core Visualizations **User Story 5.1 : Consultation des prédictions** - **En tant que** : Utilisateur connecté - **Je veux** : Voir les prédictions des matchs à venir - **Pour que** : Je puisse préparer mes paris ou simplement suivre les matchs - **Critères de succès** : - Je vois une liste de matchs avec leurs prédictions - Chaque match affiche : équipes, date, ligue, confidence, vainqueur prédit - Le Confidence Meter utilise un code couleur (vert >70%, jaune 50-70%, rouge <50%) **User Story 5.2 : Visualisation de l'énergie collective** - **En tant que** : Utilisateur connecté - **Je veux** : Comprendre l'évolution de l'énergie collective avant un match - **Pour que** : Je puisse décider si l'énergie monte ou descend - **Critères de succès** : - Je vois un graphique de l'énergie sur les 24 dernières heures - Le graphique est interactif (hover pour voir les valeurs exactes) - Je peux zoomer si nécessaire ### Épic 7 : Gamification & Social Features **User Story 7.1 : Classement** - **En tant que** : Utilisateur connecté - **Je veux** : Me comparer aux autres utilisateurs - **Pour que** : Je puisse voir mon rang et motiver ma progression - **Critères de succès** : - Je vois le Top 100 utilisateurs classés par précision - Mon rang personnel est mis en évidence si je suis dans le Top 100 - Le classement est mis à jour en temps réel **User Story 7.2 : Badges et Réalisations** - **En tant que** : Utilisateur connecté - **Je veux** : Voir mes badges et mes accomplissements - **Pour que** : Je puisse me vanter et motiver ma progression - **Critères de succès** : - Je vois tous mes badges débloqués - Je vois les critères pour débloquer les prochains badges - Les badges sont visibles sur mon profil --- ## 🎯 Roadmap de Priorisation ### Sprint 1 (Semaine 1) : Infrastructure & Base 1. **Priorité CRITIQUE** : Configuration centralisée de la base de données 2. Fixer le problème des doublons de matchs 3. Créer endpoints CRUD pour les matchs 4. Mettre à jour les épics existantes avec les nouvelles tâches ### Sprint 2 (Semaine 2) : Backend Core 1. Créer le système de gestion des matchs (CRUD complet) 2. Implémenter la mise à jour du vainqueur 3. Créer le système de régénération des prédictions 4. Tester le backtesting complet ### Sprint 3 (Semaine 3-4) : Frontend UX 1. Refaire le dashboard selon l'Epic 5 2. Implémenter ConfidenceMeter dynamique 3. Créer le composant EnergyWave avec D3.js 4. Optimiser la navigation mobile (bottom bar + swipes) ### Sprint 4 (Semaine 5-6) : Gamification 1. Implémenter le système de badges complet 2. Créer le classement fonctionnel 3. Implémenter le système de parrainage 4. Créer le système de partage de réussites --- ## 📊 Métriques de Succès Pour chaque Sprint, les métriques suivantes seront suivies : - **Taux de complétion** : % de tâches terminées vs planifiées - **Nombre de bugs** : Bugs découverts et corrigés - **Couverture de tests** : % de code couvert par des tests - **Performance** : Temps de réponse des endpoints < 3s - **Qualité du code** : Respect des conventions (snake_case pour Python, camelCase pour JS) --- ## 🚀 Prochaines Étapes 1. ✅ Créer ce plan logique 2. ⏳ Mettre à jour les épics existantes avec les nouvelles tâches structurées 3. ⏳ Créer les User Stories détaillées basées sur ce plan 4. ⏳ Réorganiser le code backend selon la nouvelle structure 5. ⏳ Créer le système de tests automatisés --- **Note** : Ce plan est un document vivant qui sera mis à jour au fur et à mesure de l'avancement du projet. Les User Stories et Epics seront créées en référence à ce plan.