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)
   ```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.