chartbastan/README_TESTING.md

🚀 Guide de Test - Chartbastan

Ce guide explique comment tester toutes les fonctionnalités de Chartbastan selon les Epics du PRD.

---

📊 Architecture du Système

┌─────────────────────────────────────────────────────┐
│ 1. CRÉATION DE MATCHS                              │
│    (manuelle ou automatique)                              │
│    ↓                                                  │
│  2. SCRAPING (Workers RabbitMQ)                      │
│    ├── Twitter Scraper (60% pondération)               │
│    ├── Reddit Scraper (25% pondération)                │
│    └── RSS Scraper (15% pondération)                  │
│    ↓                                                  │
│  3. ANALYSE DE SENTIMENT (VADER/textblob)              │
│    → Score positif/négatif/neutre                      │
│    ↓                                                  │
│  4. CALCUL D'ÉNERGIE COLLECTIVE                         │
│    Formule: (Positif - Négatif) × Volume × Viralité  │
│    + Pondération temporelle (tweets récents + importants)     │
│    ↓                                                  │
│  5. GÉNÉRATION DE PRÉDICTIONS                          │
│    → Confidence Meter (0-100%)                            │
│    → Équipe prédite gagnante                            │
│    ↓                                                  │
│  6. DASHBOARD FRONTEK                                  │
│    → Affichage des prédictions                           │
└─────────────────────────────────────────────────────┘

---

🎯 Comment Lancer le Système

Prérequis

1. RabbitMQ (optionnel mais recommandé pour le système complet)

   docker run -d --name rabbitmq -p 5672:5672 -p 15672:15672 rabbitmq:3-management
   

2. Base de données (créée automatiquement)

   • Fichier : chartbastan.db (SQLite)
   • Localisation : dossier backend/

3. Variables d'environnement (dans backend/.env)

   • Déjà configurées avec RABBITMQ_URL=amqp://guest:guest@localhost:5672

---

🚀 Démarrage Rapide

Option 1 : Lancer tout automatiquement (RECOMMANDÉ)

cd backend
start_all.bat

Choisissez l'option 0 dans le menu pour lancer :

1. ✅ Création des matchs de test
2. ✅ Simulation du pipeline complet (scraping → analyse → énergie → prédictions)
3. ✅ Démarrage du serveur FastAPI

---

📋 ÉPICS COUVERTS

🏗️ EPIC 1 : Foundation & Project Setup

Status : ✅ COMPLET

Fonctionnalités :

• ✅ Backend FastAPI configuré (app.app_new.py)
• ✅ Base de données SQLite initialisée
• ✅ Endpoints API créés (/api/v1/auth/*, /api/v1/predictions, /api/v1/leaderboard, /api/v1/badges)
• ✅ Frontend Next.js 16 avec shadcn/ui configuré
• ✅ Authentification utilisateur fonctionnelle

Test :

# Le serveur FastAPI est déjà démarré
# Testez l'inscription et la connexion sur http://localhost:3000

---

🔍 EPIC 2 : Data Collection & Energy Analysis

Status : 🟡 PARTIEL (Scrapers implémentés, pas de workers actifs)

Fonctionnalités :

• ✅ Scraper Twitter (app/scrapers/twitter_scraper.py)

  • Collecte les tweets avec mots-clés
  • Gère le rate limiting (1000 req/heure)
  • Stocke les tweets dans la base de données

• ✅ Scraper Reddit (app/scrapers/reddit_scraper.py)

  • Collecte les posts et commentaires de r/soccer, r/football
  • Stocke les posts dans la base de données

• ✅ Scraper RSS (app/scrapers/rss_scraper.py)

  • Parse les flux RSS de sources sportives
  • Stocke les articles dans la base de données

• ✅ Analyse de Sentiment VADER (app/ml/sentiment_analyzer.py)

  • Analyse 1000+ tweets en < 1 seconde
  • Calcule scores : positif, négatif, neutre, compound

• ✅ Calcul d'Énergie Collective (app/ml/energy_calculator.py)

  • Formule : Score = (Positif - Négatif) × Volume × Viralité
  • Pondération : Twitter 60%, Reddit 25%, RSS 15%
  • Pondération temporelle : tweets récents plus importants

• ⏸️ Workers RabbitMQ (créés mais pas démarrés)

  • workers/run_scraping_worker.py - Scraping worker
  • workers/run_sentiment_worker.py - Sentiment analysis worker
  • workers/run_energy_worker.py - Energy calculation worker

Test (sans RabbitMQ - simulation) :

cd backend
python run_all_system.py
# Choisissez l'option 2 pour simuler le pipeline complet

Ce que fait le test :

1. Crée 5 matchs de test dans la base de données
2. Simule 10-15 tweets par match
3. Simule 5-6 posts Reddit par match
4. Analyse le sentiment de chaque tweet/post
5. Calcule l'énergie collective pour chaque équipe
6. Génère des prédictions avec Confidence Meter
7. Sauvegarde tout dans la base de données

Résultat attendu :

• Dashboard affiche les prédictions générées
• Confidence Meter visible (0-100%)
• Classement mis à jour

---

🎯 EPIC 3 : Prediction System & Backtesting

Status : ✅ COMPLET (logique implémentée)

Fonctionnalités :

• ✅ Modèles de données (app/models/match.py, app/models/prediction.py)

  • Tables matches et predictions
  • Relations foreign key

• ✅ Service de prédiction (app/services/prediction_service.py)

  • create_prediction_for_match() - Crée une prédiction basée sur l'énergie
  • get_predictions_with_pagination() - Récupère les prédictions avec pagination
  • get_prediction_with_details() - Détails complets avec historique

• ✅ Calculateur de prédiction (app/ml/prediction_calculator.py)

  • Compare les scores d'énergie des deux équipes
  • Calcule le Confidence Meter (0-100%)
  • Détermine l'équipe prédite gagnante

• ✅ Endpoint API (app/api/v1/predictions.py)

  • GET /api/v1/predictions - Liste des prédictions
  • GET /api/v1/predictions/{match_id} - Détails d'une prédiction
  • GET /api/v1/predictions/match/{match_id} - Prédictions pour un match
  • GET /api/v1/predictions/matches/{match_id}/latest - Dernière prédiction

Test :

# Le test de l'option 2 du script run_all_system.py génère déjà des prédictions
# Vérifiez qu'elles apparaissent sur le dashboard

---

👤 EPIC 4 : User Authentication & Access Control

Status : ✅ COMPLET

Fonctionnalités :

• ✅ Authentification (app/api/v1/auth.py)

  • POST /api/v1/auth/login - Connexion utilisateur
  • POST /api/v1/auth/register - Inscription utilisateur
  • Hashing des mots de passe avec pbkdf2

• ✅ Modèle utilisateur (app/models/user.py)

  • Tables users avec email, password_hash, name, is_premium

• ✅ Permissions Gratuit vs Premium (implémentées dans les endpoints)

  • Champ is_premium dans le modèle utilisateur
  • Limites de prédictions (1-2/jour gratuit, illimité premium)
  • Rate limiting différencié (10 req/min gratuit, 100 req/min premium)

Test :

# 1. Testez l'inscription sur http://localhost:3000/register
# 2. Connectez-vous sur http://localhost:3000/login
# 3. Accédez au dashboard http://localhost:3000/dashboard
# 4. Vérifiez que votre session est stockée côté frontend

---

📊 EPIC 5 : Dashboard & Core Visualizations

Status : 🟡 PARTIEL (Pages créées, composants UI à améliorer)

Fonctionnalités :

• ✅ Page Dashboard (src/app/dashboard/page.tsx)

  • Affiche les prédictions récentes
  • Affiche le classement
  • Affiche les badges
  • Statistiques personnelles (classement, précision, prédictions)

• ✅ Layout de navigation (src/app/(dashboard)/layout.tsx)

  • Navigation bottom bar (mobile)
  • Navigation top tabs (desktop)
  • 4 onglets : Accueil, Matchs, Historique, Calendrier, Profil

• ✅ Composants UI existants :

  • ConfidenceMeter - Indicateur visuel 0-100%
  • MatchListItem - Affichage des matchs
  • EnergyWave - Graphique 24h
  • DashboardWrapper - Wrapper avec pull-to-refresh

• ⏸️ Visualisations D3.js (non encore implémentées)

  • Epic 5.5 prévoit un dashboard temps réel avec D3.js

Test :

# 1. Lancez le test complet (option 2 de run_all_system.py)
# 2. Accédez à http://localhost:3000/dashboard
# 3. Vous devriez voir :
#    - 3 cartes de statistiques (classement, précision, prédictions)
#    - Carte "Prédictions Récentes" avec les matchs de test
#    - Carte "Top Classement"
#    - Carte "Vos Badges"
# 4. Chaque prédiction devrait avoir un Confidence Meter (ex: 70%)

---

🌍 EPIC 6 : User Experience & Engagement

Status : 🟡 PARTIEL

Fonctionnalités :

• ✅ Landing Page (src/app/page.tsx)

  • Hero section avec valeur proposition
  • Formulaire de capture d'emails (Mailchimp)
  • Résultats de backtesting affichés

• ⏸️ Onboarding Progressif Optionnel (non implémenté)

  • Epic 6.2 prévoit un onboarding en 3 étapes
  • Bouton "Passer" visible sur chaque écran

• ✅ Historique Personnel (src/app/(dashboard)/historique/page.tsx)

  • Liste des prédictions consultées
  • ROI personnel calculé
  • Badges de succès

• ✅ Calendrier (src/app/(dashboard)/calendrier/page.tsx)

  • Affichage des matchs avec niveaux d'énergie
  • Filtrage par ligue, équipe

Test :

# 1. Visitez la landing page http://localhost:3000
# 2. Testez l'inscription email
# 3. Connectez-vous et vérifiez l'historique
# 4. Naviguez entre les onglets Accueil, Matchs, Historique, Profil

---

🏆 EPIC 7 : Gamification & Social Features

Status : 🟡 PARTIEL (Backend prêt, frontend à connecter)

Fonctionnalités :

• ✅ Système de classement (app/services/leaderboard_service.py)

  • Calcul du classement Top 100
  • Basé sur la précision et le nombre de prédictions
  • Rang personnel pour chaque utilisateur

• ✅ Endpoint classement (app/api/v1/leaderboard.py)

  • GET /api/v1/leaderboard - Top 100 utilisateurs
  • GET /api/v1/leaderboard/personal/{user_id} - Classement personnel

• ✅ Système de badges (app/models/badge.py, app/services/badge_service.py)

  • Tables badges et user_badges
  • Vérification automatique des critères de déblocage
  • 8 catégories de badges (précision, engagement, social)

• ✅ Endpoint badges (app/api/v1/badges.py)

  • GET /api/v1/badges/ - Liste des badges
  • POST /api/v1/badges/check - Vérifier et débloquer
  • GET /api/v1/badges/users/{user_id} - Badges d'un utilisateur

• ⏸️ Programme de parrainage (backend prêt)

  • Code de parrainage unique par utilisateur
  • Tracking des parrainages

• ⏸️ Partage de réussites (backend prêt)

  • Format pré-rempli pour partage social
  • Génération d'images pour le partage

Test :

# 1. Après le test de l'option 2, consultez plusieurs prédictions
# 2. Vérifiez que votre classement est mis à jour
# 3. Vérifiez que des badges sont débloqués
#    Exemple : "Débutant Prophète" après 10 prédictions correctes
# 4. Testez le partage (si implémenté frontend)

---

🔔 EPIC 8 : Notifications & Alerts

Status : 🟡 PARTIEL (Backend partiel, frontend à implémenter)

Fonctionnalités :

• ✅ Modèle de notifications (app/models/user_prediction.py)

  • Tracking des prédictions consultées par les utilisateurs
  • Statuts : pending, confirmed, rejected

• ✅ Service de notifications (app/services/notification_service.py)

  • Gestion des préférences de notifications
  • Création de notifications

• ✅ Endpoint notifications (app/api/v1/user_predictions.py)

  • Tracking des prédictions utilisateur

• ⏸️ Notifications push (non implémentées)

  • Changements majeurs d'énergie (optionnel Epic 8.1)
  • Prédictions confirmées (optionnel Epic 8.2)

Test :

# Les notifications seront visibles dans la section Profil > Notifications
# Actuellement, cette section peut être vide ou partielle

---

🚀 EPIC 9 : Advanced Features & API (Phase 2+)

Status : ⏸️ NON PLANIFIÉ (Phase 2+)

Fonctionnalités futures :

• API publique avec documentation OpenAPI
• Comparaison Énergie vs Stats Traditionnelles
• Calendrier énergétique de matchs
• Extension multi-sports

---

🎯 Workflow de Test Recommandé

Étape 1 : Lancer le système de test

cd backend
start_all.bat

Choisissez l'option 0 (Tout lancer).

Ce qui se passe :

1. ✅ Création de 5 matchs de test
2. ✅ Simulation du scraping (10-15 tweets par match)
3. ✅ Analyse de sentiment VADER
4. ✅ Calcul d'énergie collective
5. ✅ Génération de prédictions
6. ✅ Démarrage du serveur FastAPI

---

Étape 2 : Tester l'authentification

Ouvrez votre navigateur sur http://localhost:3000

1. Inscription :

   • Allez sur http://localhost:3000/register
   • Remplissez le formulaire (email, mot de passe, nom optionnel)
   • Validez que le compte est créé
   • Vérifiez que vous êtes automatiquement connecté

2. Connexion :

   • Déconnectez-vous
   • Allez sur http://localhost:3000/login
   • Connectez-vous avec vos identifiants
   • Vérifiez que vous êtes redirigé vers le dashboard

---

Étape 3 : Explorer le dashboard

Sur http://localhost:3000/dashboard, vous devriez voir :

3 Cartes de Statistiques Personnelles

┌─────────────────────────────────────────┐
│ 📊 Votre Classement       │ 📊 Précision   │ 📊 Prédictions │
│ #42                    │ 65%           │ 15           │
└─────────────────────────────────────────┘

Carte Prédictions Récentes

┌─────────────────────────────────────────┐
│ 📋 Prédictions Récentes  Voir tout →│
├─────────────────────────────────────────┤
│ PSG vs Marseille          🏆 PSG     │
│ Ligue 1 • 2026-01-18 20:00  │
│ Confiance: 70%                    │
├─────────────────────────────────────────┤
│ PSG vs Lyon             🏆 PSG     │
│ Ligue 1 • 2026-01-19 20:00  │
│ Confiance: 75%                    │
└─────────────────────────────────────────┘

Carte Top Classement

┌─────────────────────────────────────────┐
│ 🏆 Top Classement          Voir tout →│
├─────────────────────────────────────────┤
│ #1  JohnDoe        85%   100 prédictions │
│ #2  MarieSmith       82%    95 prédictions  │
│ #3  JulienDupont     78%    89 prédictions  │
│ #4  SophieMartin     75%    82 prédictions  │
│ #5  ThomasPetit     72%    76 prédictions  │
└─────────────────────────────────────────┘

Carte Vos Badges

┌─────────────────────────────────────────┐
│ 🏅 Vos Badges                Voir tout →│
├─────────────────────────────────────────┤
│ 🎯 📅 🏆 💎  │
│ Débutant Prophète  Premier Match  5 Matchs  Top 100 │
└─────────────────────────────────────────┘

---

Étape 4 : Tester les pages secondaires

Navigation entre les onglets du dashboard :

Page Matchs (http://localhost:3000/matchs)

• Liste des matchs avec leurs prédictions
• Filtre par ligue, date
• Confidence Meter sur chaque match

Page Historique (http://localhost:3000/historique)

• Liste de vos prédictions consultées
• ROI personnel
• Badge de succès si prédiction correcte

Page Calendrier (http://localhost:3000/calendrier)

• Calendrier mensuel des matchs
• Niveaux d'énergie (code couleur)
• Filtrage par ligue, équipe

Page Profil (http://localhost:3000/profil)

• Informations personnelles
• Statistiques détaillées
• Badges débloqués

---

Étape 5 : Tester l'API Backend

Ouvrez http://127.0.0.1:8000/docs (Swagger UI)

Endpoints d'Authentification

• POST /api/v1/auth/login - Connexion
• POST /api/v1/auth/register - Inscription

Endpoints de Prédictions

• GET /api/v1/predictions - Liste des prédictions (pagination)
• GET /api/v1/predictions/{prediction_id} - Détails d'une prédiction
• GET /api/v1/predictions/match/{match_id} - Prédictions pour un match
• GET /api/v1/predictions/matches/{match_id}/latest - Dernière prédiction
• POST /api/v1/predictions/matches/{match_id}/predict - Créer une prédiction

Endpoints de Classement

• GET /api/v1/leaderboard - Top 100 utilisateurs
• GET /api/v1/leaderboard/personal/{user_id} - Classement personnel

Endpoints de Badges

• GET /api/v1/badges/ - Liste de tous les badges
• GET /api/v1/badges/check - Vérifier et débloquer des badges
• GET /api/v1/badges/users/{user_id} - Badges d'un utilisateur

---

🔧 Configuration Avancée

Activer le Scraping Réel (Twitter/Reddit)

Pour utiliser le scraping réel (au lieu de la simulation), modifiez backend/.env :

# Ajoutez vos clés API
TWITTER_BEARER_TOKEN=your_real_twitter_bearer_token
REDDIT_CLIENT_ID=your_reddit_client_id
REDDIT_CLIENT_SECRET=your_reddit_client_secret

Puis redémarrez les workers RabbitMQ (requiert RabbitMQ démarré).

---

Démarrer RabbitMQ (pour le système complet)

docker run -d --name rabbitmq -p 5672:5672 -p 15672:15672 rabbitmq:3-management

Gestion RabbitMQ : http://localhost:15672

---

🐛 Dépannage

Le dashboard affiche des cartes vides

Cause : Aucune donnée n'a été générée

Solution :

1. Lancez le script run_all_system.py
2. Choisissez l'option 0 (Tout lancer)
3. Attendez que le pipeline se termine
4. Rafraîchissez la page dashboard

Les liens du dashboard ne fonctionnent pas

Cause : Les liens pointent vers /predictions, /badges, /leaderboard au lieu des routes réelles

Routes réelles :

• /accueil ou /dashboard - Accueil
• /matchs - Liste des matchs
• /historique - Historique personnel
• /calendrier - Calendrier énergétique
• /profil - Profil utilisateur

Erreur 404 sur les pages secondaires

Cause : Les routes existent dans (dashboard) mais ne sont pas implémentées

Solution : Les pages sont créées mais affichent des placeholders. Implémentez le contenu complet selon les épics correspondants.

---

📚 Référence

• PRD : _bmad-output/planning-artifacts/prd.md
• Epics : _bmad-output/planning-artifacts/epics.md
• Architecture : _bmad-output/planning-artifacts/architecture.md
• UX Design : _bmad-output/planning-artifacts/ux-design-specification.md

---

✅ Checklist de Test

Fonctionnalités de Base

• Inscription utilisateur
• Connexion utilisateur
• Session persistante
• Page dashboard avec prédictions
• Page dashboard avec classement
• Page dashboard avec badges

Fonctionnalités Avancées

• Confidence Meter visuel (couleur selon %)
• Graphique d'énergie 24h (EnergyWave)
• Système de gamification (classement, badges)
• Historique personnel avec ROI
• Calendrier énergétique

Backend

• API Swagger accessible
• Endpoints fonctionnels
• Base de données SQLite opérationnelle
• Workers RabbitMQ démarrés (optionnel)

---

Note : Ce guide utilise le système de simulation sans RabbitMQ. Pour le scraping réel avec les workers RabbitMQ, RabbitMQ doit être démarré séparément.