# 🎯 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.
