chartbastan/README_TESTING.md
2026-02-01 09:31:38 +01:00

599 lines
20 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters

This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

# 🚀 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)
```bash
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É)
```bash
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** :
```bash
# 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) :
```bash
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** :
```bash
# 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** :
```bash
# 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** :
```bash
# 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** :
```bash
# 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** :
```bash
# 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** :
```bash
# 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
```bash
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` :
```bash
# 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)
```bash
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.