---
stepsCompleted: ['step-01-validate-prerequisites', 'step-02-design-epics', 'step-03-create-stories', 'step-04-final-validation']
inputDocuments:
  - prd.md
  - architecture.md
  - ux-design-specification.md
status: complete
completedAt: '2026-01-17T00:00:00.000Z'
workflowType: 'epics-and-stories'
---

# chartbastan - Epic Breakdown

## Overview

This document provides the complete epic and story breakdown for chartbastan, decomposing the requirements from the PRD, UX Design if it exists, and Architecture requirements into implementable stories.

## Requirements Inventory

### Functional Requirements

FR1: Le système doit collecter des données depuis Twitter (60% pondération), Reddit (25% pondération) et RSS (15% pondération) avec fusion intelligente et pondération
FR2: Le système doit analyser le sentiment des tweets en temps réel en utilisant VADER/textblob pour analyser 1000+ tweets en < 1 seconde
FR3: Le système doit calculer l'énergie collective selon la formule : Score = (Positif - Négatif) × Volume × Viralité avec pondération temporelle
FR4: Le système doit effectuer un backtesting sur 100+ matchs historiques (Ligue 1, Premier League, Champions League) avec seuil de précision ≥ 60%
FR5: Le système doit afficher un dashboard temps réel avec visualisations interactives (D3.js) et Confidence Meter (0-100%)
FR6: Le système doit implémenter un système de gamification avec classement, badges et parrainage (invite 3 amis = 1 mois premium gratuit)
FR7: Le système doit supporter un modèle freemium : version gratuite (1-2 prédictions/jour) + Premium (19.99€/mois) avec métriques avancées
FR8: Le système doit fournir une API publique avec documentation et accès pour développeurs tiers (Phase 2+)
FR9: Le système doit envoyer des notifications push pour changements majeurs d'énergie collective
FR10: Le système doit afficher un Confidence Meter visuel (0-100%) avec code couleur intuitif (🟢 >70% / 🟡 50-70% / 🔴 <50%)
FR11: Le système doit visualiser l'énergie collective (graphique de vague/diagramme de chaleur) sur 24h avant match
FR12: Le système doit afficher un historique temporel (Flashback des 24h avant match)
FR13: Le système doit permettre la comparaison Énergie vs Stats Traditionnelles
FR14: Le système doit afficher un calendrier énergétique de matchs
FR15: Le système doit permettre le partage automatique de réussites avec format pré-rempli
FR16: Le système doit afficher des badges et réalisations partageables
FR17: Le système doit permettre l'authentification utilisateur (Better Auth v1.4.4)
FR18: Le système doit différencier les permissions gratuit vs premium (RBAC)
FR19: Le système doit gérer les limites de prédictions par utilisateur (gratuit: 1-2/jour, premium: illimité)
FR20: Le système doit stocker les prédictions, matchs, utilisateurs et scores d'énergie dans une base de données (SQLite Phase 1)
FR21: Le système doit gérer une queue asynchrone (RabbitMQ) pour découpler scraping et analyse
FR22: Le système doit fournir une landing page avec capture d'emails (Mailchimp gratuit)
FR23: Le système doit permettre l'onboarding progressif optionnel en 3 étapes pour nouveaux utilisateurs
FR24: Le système doit afficher un historique personnel avec ROI pour chaque utilisateur
FR25: Le système doit permettre la navigation one-thumb zone avec barre de navigation en bas (mobile) et tabs en haut (desktop)

### NonFunctional Requirements

NFR1: Performance - Dashboard mis à jour en < 3 secondes
NFR2: Performance - Analyse de 1000+ tweets en < 1 seconde
NFR3: Disponibilité - Uptime > 99.5% pour l'API FastAPI principale
NFR4: Scalabilité - Système de queue asynchrone (RabbitMQ) pour gérer les pics de charge
NFR5: Précision - Taux de précision ≥ 60% (seuil de validation, < 55% = révision requise)
NFR6: Rate Limiting - Gestion robuste des limites API Twitter (1000 req/heure gratuit)
NFR7: Qualité Frontend - Next.js 16 responsive avec Lighthouse score > 90
NFR8: Fiabilité - Scraping Twitter stable sur 24h sans interruption
NFR9: Transparence - Confidence Meter précis à ±5% du taux de réussite réel
NFR10: Performance Mobile - Load time < 2s sur 3G, transitions fluides à 60fps
NFR11: Accessibilité - WCAG 2.1 AA compliance (contraste minimum 4.5:1)
NFR12: Responsive Design - Mobile-first avec breakpoints adaptatifs (320px-1280px+)
NFR13: Sécurité - HTTPS obligatoire (TLS 1.3), validation Pydantic pour toutes les entrées
NFR14: Sécurité - Secure cookies (HttpOnly, Secure, SameSite), headers de sécurité (CSP, X-Frame-Options)
NFR15: Monitoring - Logging structuré (JSON), Sentry pour tracking erreurs, UptimeRobot pour monitoring basique
NFR16: Documentation - API documentée avec OpenAPI 3.1, Swagger UI intégré (/docs)
NFR17: Compatibilité - Support navigateurs : Chrome, Safari, Firefox, Edge (mobile + desktop)
NFR18: Time-to-Value - Consultation de prédiction en < 3 secondes (ouvrir → voir → comprendre)

### Additional Requirements

**Exigences Techniques de l'Architecture :**

- Starter Template : Initialiser le projet avec `create-next-app@latest chartbastan --typescript --eslint --tailwind --app --src-dir --turbopack` puis `npx shadcn@canary init` (Epic 1 Story 1)
- Infrastructure : FastAPI backend (Python) + Next.js 16 frontend avec SQLite Phase 1
- ORM FastAPI : SQLAlchemy 2.0.45 avec Alembic pour migrations
- ORM Next.js : Drizzle ORM v0.44.7 avec better-sqlite3 et Drizzle Kit pour migrations
- Authentification : Better Auth v1.4.4 (compatible Next.js 16)
- API Design : RESTful avec OpenAPI 3.1, documentation automatique FastAPI
- Gestion d'erreurs : Format standardisé avec codes d'erreur, logging avec contexte
- Rate Limiting : Limites différenciées (Gratuit: 10 req/min, Premium: 100 req/min)
- State Management Frontend : Zustand v5.0.9 + React Query (TanStack Query)
- Hosting Phase 1 : Vercel (frontend gratuit) + Railway/Render (backend 10-20€/mois)
- CI/CD : GitHub Actions avec lint + type check + build automatique
- Monitoring Phase 1 : Console logs structurés (JSON), Sentry (plan gratuit), UptimeRobot (gratuit)
- Conventions de nommage : Python (snake_case), TypeScript (camelCase/PascalCase), Database (snake_case)
- Structure projet : Feature-based organization avec co-location, Server Components par défaut

**Exigences UX Additionnelles :**

- Responsive Design : Mobile-first (320px-768px), tablette (768px-1023px), desktop (1024px+)
- Navigation : Bottom bar mobile (4 onglets), top tabs desktop, navigation constante
- Interactions : Swipe gauche/droite entre onglets, pull-to-refresh, tap-to-tooltip
- Visualisations : Confidence Meter avec couleurs sémantiques, Energy Wave graphique sur 24h
- Feedback : Toast notifications (success/error/warning/info), skeleton screens, progress bars
- Onboarding : Optionnel en 3 étapes, bouton "Passer" visible, disponible depuis profil
- Partage : Format pré-rempli avec image générée, destinations WhatsApp/Twitter/Facebook
- Accessibilité : Touch targets min 44x44px (Apple HIG) / 48x48px (Material Design), focus visible, ARIA labels
- Design System : shadcn/ui + Tailwind CSS v4.0 avec palette Cool Slate Blue, typographie Inter + JetBrains Mono
- Composants Custom : ConfidenceMeter, MatchListItem, EnergyWave, MatchCard, PredictionResult, ShareButton
- Publicité : Placement réfléchi (haut/bas, sidebar desktop), qualité contrôlée, clairement identifiée "Sponsorisé", bouton X visible

**Exigences de Gestion des API Externes :**

- Rate Limiting Twitter : Gestion proactive des limites (1000 req/heure), priorisation dynamique (matchs VIP)
- Modes dégradés : Si Twitter down, utiliser Reddit + RSS uniquement avec confiance réduite
- Monitoring : Alertes prédictives quand utilisation > 90% pendant 10 minutes consécutives
- Optimisation : Scraper uniquement tweets avec engagement élevé (>10 retweets/likes)

**Exigences de Backtesting :**

- Validation sur 100+ matchs historiques avec seuil de précision ≥ 60%
- Si précision < 55% = REVISER l'approche
- Preuve publique publiée (Medium, Reddit) avec résultats transparents

**Exigences de Gamification :**

- Système de classement (Top 100 utilisateurs)
- Programme de parrainage (invite 3 amis = 1 mois premium GRATUIT)
- Badges et réalisations partageables
- Historique personnel avec ROI détaillé

**Exigences de Notifications :**

- Notifications push pour changements majeurs d'énergie collective
- Notifications pour prédictions confirmées (si correcte uniquement)
- Alertes programmées pour utilisateurs premium (ex: "Énergie de l'équipe X s'effondre -3% en 30 min")

### FR Coverage Map

FR1: Epic 2 - Collecte multi-sources (Twitter 60%, Reddit 25%, RSS 15%)
FR2: Epic 2 - Analyse de sentiment en temps réel (VADER/textblob)
FR3: Epic 2 - Calcul d'énergie collective avec pondération temporelle
FR4: Epic 3 - Backtesting sur 100+ matchs historiques avec validation précision ≥ 60%
FR5: Epic 5 - Dashboard temps réel avec visualisations interactives (D3.js)
FR6: Epic 7 - Système de gamification (classement, badges, parrainage)
FR7: Epic 4 - Modèle freemium (gratuit 1-2/jour, Premium 19.99€/mois)
FR8: Epic 9 - API publique avec documentation (Phase 2+)
FR9: Epic 8 - Notifications push pour changements majeurs d'énergie
FR10: Epic 5 - Confidence Meter visuel avec code couleur intuitif
FR11: Epic 5 - Visualisation énergie collective (graphique vague/diagramme chaleur 24h)
FR12: Epic 5 - Historique temporel (Flashback 24h avant match)
FR13: Epic 9 - Comparaison Énergie vs Stats Traditionnelles (Phase 2+)
FR14: Epic 9 - Calendrier énergétique de matchs (Phase 2+)
FR15: Epic 7 - Partage automatique de réussites avec format pré-rempli
FR16: Epic 7 - Badges et réalisations partageables
FR17: Epic 4 - Authentification utilisateur (Better Auth v1.4.4)
FR18: Epic 4 - Permissions différenciées gratuit vs premium (RBAC)
FR19: Epic 4 - Gestion limites de prédictions par utilisateur
FR20: Epic 1 - Base de données SQLite pour stockage (prédictions, matchs, utilisateurs, scores)
FR21: Epic 2 - Queue asynchrone RabbitMQ pour découplage scraping/analyse
FR22: Epic 6 - Landing page avec capture d'emails (Mailchimp)
FR23: Epic 6 - Onboarding progressif optionnel en 3 étapes
FR24: Epic 6 - Historique personnel avec ROI pour chaque utilisateur
FR25: Epic 5 - Navigation one-thumb zone (bottom bar mobile, top tabs desktop)

## Epic List

### Epic 1: Foundation & Project Setup

Établir l'infrastructure technique de base du projet pour permettre le développement des fonctionnalités suivantes. Les utilisateurs bénéficieront d'une application stable et performante grâce à cette fondation solide.

**FRs couverts:** FR20

**Exigences techniques couvertes:**
- Starter template (create-next-app + shadcn/ui)
- Configuration base de données SQLite
- Infrastructure FastAPI + Next.js 16
- CI/CD basique
- Structure projet et conventions de nommage

### Epic 2: Data Collection & Energy Analysis

Permettre au système de collecter et analyser les données des réseaux sociaux pour calculer l'énergie collective des supporters. Les utilisateurs bénéficieront de prédictions basées sur l'analyse en temps réel du sentiment collectif.

**FRs couverts:** FR1, FR2, FR3, FR21

**Exigences techniques couvertes:**
- Scraping Twitter, Reddit, RSS avec pondération (60%/25%/15%)
- Analyse de sentiment (VADER/textblob) - 1000+ tweets en < 1 seconde
- Calcul d'énergie collective (formule avec pondération temporelle)
- Queue RabbitMQ pour traitement asynchrone
- Gestion rate limiting Twitter (1000 req/heure)
- Modes dégradés (Reddit + RSS si Twitter down)

### Epic 3: Prediction System & Backtesting

Créer un système de prédiction validé scientifiquement avec backtesting. Les utilisateurs bénéficieront de prédictions fiables avec un taux de précision ≥ 60% validé sur 100+ matchs historiques.

**FRs couverts:** FR4

**Exigences techniques couvertes:**
- Système de calcul de prédictions
- Backtesting sur 100+ matchs historiques (Ligue 1, Premier League, Champions League)
- Validation précision ≥ 60% (seuil de validation)
- Si précision < 55% = révision de l'approche

### Epic 4: User Authentication & Access Control

Permettre aux utilisateurs de s'inscrire, se connecter et accéder à l'application selon leur niveau (gratuit ou premium). Les utilisateurs bénéficieront d'un système d'authentification sécurisé et d'un accès différencié selon leur abonnement.

**FRs couverts:** FR17, FR18, FR19

**Exigences techniques couvertes:**
- Authentification (Better Auth v1.4.4)
- Inscription/connexion utilisateur
- Permissions gratuit vs premium (RBAC)
- Gestion limites de prédictions (gratuit: 1-2/jour, premium: illimité)
- Rate limiting différencié (Gratuit: 10 req/min, Premium: 100 req/min)

### Epic 5: Dashboard & Core Visualizations

Permettre aux utilisateurs de consulter les prédictions avec des visualisations claires et intuitives. Les utilisateurs bénéficieront d'un dashboard temps réel avec Confidence Meter et visualisations d'énergie pour prendre des décisions éclairées.

**FRs couverts:** FR5, FR10, FR11, FR12, FR25

**Exigences UX couvertes:**
- Dashboard temps réel avec visualisations interactives (D3.js)
- Confidence Meter visuel (0-100%) avec code couleur (🟢 >70% / 🟡 50-70% / 🔴 <50%)
- Visualisation énergie collective (graphique vague/diagramme chaleur sur 24h)
- Historique temporel (Flashback 24h avant match)
- Navigation one-thumb zone (bottom bar mobile, top tabs desktop)
- Composants custom: ConfidenceMeter, MatchListItem, EnergyWave, MatchCard

### Epic 6: User Experience & Engagement

Créer une expérience utilisateur complète avec onboarding et suivi personnel. Les utilisateurs bénéficieront d'une interface intuitive, d'un guidage progressif et d'un suivi de leur performance personnelle.

**FRs couverts:** FR22, FR23, FR24

**Exigences UX couvertes:**
- Landing page avec capture d'emails (Mailchimp gratuit)
- Onboarding progressif optionnel en 3 étapes
- Historique personnel avec ROI pour chaque utilisateur
- Design system shadcn/ui + Tailwind CSS v4.0
- Feedback patterns (toast notifications, skeleton screens)

### Epic 7: Gamification & Social Features

Engager les utilisateurs et créer de la viralité via gamification et partage social. Les utilisateurs bénéficieront d'un système de classement, de badges, de parrainage et de partage de leurs réussites.

**FRs couverts:** FR6, FR15, FR16

**Exigences couvertes:**
- Système de classement (Top 100 utilisateurs)
- Programme de parrainage (invite 3 amis = 1 mois premium GRATUIT)
- Badges et réalisations partageables
- Partage automatique de réussites avec format pré-rempli
- Composants custom: ShareButton, PredictionResult

### Epic 8: Notifications & Alerts

Alerter les utilisateurs des changements importants et des confirmations de prédictions. Les utilisateurs bénéficieront de notifications pertinentes pour ne manquer aucune opportunité importante.

**FRs couverts:** FR9

**Exigences couvertes:**
- Notifications push pour changements majeurs d'énergie collective
- Notifications pour prédictions confirmées (si correcte uniquement)
- Alertes programmées pour utilisateurs premium
- Gestion des préférences de notifications

### Epic 9: Advanced Features & API (Phase 2+)

Fournir des fonctionnalités avancées et une API publique pour développeurs tiers. Les utilisateurs avancés et développeurs bénéficieront d'analyses comparatives et d'un accès API pour intégrations.

**FRs couverts:** FR8, FR13, FR14

**Exigences techniques couvertes:**
- API publique avec documentation OpenAPI 3.1
- Comparaison Énergie vs Stats Traditionnelles
- Calendrier énergétique de matchs
- Documentation Swagger UI intégrée (/docs)

---

## Epic 1: Foundation & Project Setup

Établir l'infrastructure technique de base du projet pour permettre le développement des fonctionnalités suivantes. Les utilisateurs bénéficieront d'une application stable et performante grâce à cette fondation solide.

### Story 1.1: Initialiser le projet Next.js avec starter template

As a développeur,
I want initialiser le projet Next.js 16 avec create-next-app et shadcn/ui,
So that j'ai une base solide et moderne pour développer l'application.

**Acceptance Criteria:**

**Given** un environnement de développement avec Node.js 20.9+ installé
**When** j'exécute `npx create-next-app@latest chartbastan --typescript --eslint --tailwind --app --src-dir --turbopack`
**Then** le projet Next.js 16 est créé avec TypeScript, ESLint, Tailwind CSS, App Router, structure `src/` et Turbopack activé
**And** le projet compile sans erreurs
**And** la commande `npm run dev` démarre le serveur de développement

**Given** le projet Next.js est initialisé
**When** j'exécute `npx shadcn@canary init` dans le répertoire du projet
**Then** shadcn/ui est configuré avec Tailwind v4
**And** le fichier `components.json` est créé avec la configuration
**And** le style "new-york" est configuré par défaut
**And** les CSS variables pour theming sont configurées

### Story 1.2: Configurer la base de données SQLite avec Drizzle ORM

As a développeur,
I want configurer SQLite avec Drizzle ORM dans Next.js,
So que je peux stocker et récupérer des données pour l'application.

**Acceptance Criteria:**

**Given** le projet Next.js est initialisé
**When** j'installe `drizzle-orm`, `better-sqlite3` et `drizzle-kit`
**Then** les packages sont installés avec les versions spécifiées (Drizzle v0.44.7)
**And** la configuration Drizzle est créée dans `src/lib/db.ts`
**And** la connexion SQLite fonctionne
**And** le fichier de base de données `.db` est créé (ou spécifié dans config)

**Given** Drizzle est configuré
**When** j'exécute la commande de génération de schéma
**Then** Drizzle Kit est configuré avec le chemin vers la base de données
**And** les migrations peuvent être générées avec `drizzle-kit generate`

### Story 1.3: Configurer FastAPI backend avec SQLAlchemy

As a développeur,
I want configurer le backend FastAPI avec SQLAlchemy et SQLite,
So que je peux créer des APIs pour l'analyse de données et les prédictions.

**Acceptance Criteria:**

**Given** Python 3.11+ est installé
**When** je crée le répertoire `backend/` avec structure FastAPI
**Then** FastAPI est installé avec les dépendances (SQLAlchemy 2.0.45, Alembic, Pydantic)
**And** le fichier `backend/app/main.py` existe avec une instance FastAPI
**And** la configuration SQLAlchemy est créée dans `backend/app/database.py`
**And** la connexion SQLite partage la même base de données que Next.js (ou une base séparée configurée)

**Given** FastAPI est configuré
**When** je démarre le serveur avec `uvicorn app.main:app --reload`
**Then** le serveur démarre sans erreurs
**And** l'endpoint `/docs` affiche la documentation Swagger UI
**And** la connexion à la base de données SQLite fonctionne

### Story 1.4: Configurer CI/CD basique avec GitHub Actions

As a développeur,
I want configurer un pipeline CI/CD basique,
So que les changements sont validés automatiquement avant déploiement.

**Acceptance Criteria:**

**Given** le projet est dans un repository GitHub
**When** je crée `.github/workflows/ci.yml`
**Then** le workflow exécute `npm run lint` et `npm run type-check` sur les PRs
**And** le workflow exécute `npm run build` pour vérifier que le build fonctionne
**And** le workflow s'exécute sur les branches `main` et les pull requests
**And** les erreurs de lint ou de build bloquent le merge

**Given** le backend FastAPI existe
**When** le workflow CI s'exécute
**Then** les tests Python (si existants) sont exécutés
**And** le linting Python (flake8/black) est vérifié

---

## Epic 2: Data Collection & Energy Analysis

Permettre au système de collecter et analyser les données des réseaux sociaux pour calculer l'énergie collective des supporters. Les utilisateurs bénéficieront de prédictions basées sur l'analyse en temps réel du sentiment collectif.

### Story 2.1: Implémenter le scraper Twitter avec rate limiting

As a développeur,
I want implémenter un scraper Twitter avec gestion des rate limits,
So que je peux collecter des tweets sur les matchs de football sans dépasser les limites API.

**Acceptance Criteria:**

**Given** une clé API Twitter est configurée
**When** le scraper Twitter est exécuté
**Then** il collecte des tweets pour un match donné avec mots-clés pertinents
**And** il respecte la limite de 1000 requêtes/heure
**And** il gère les erreurs de rate limit avec retry avec backoff exponentiel
**And** les tweets collectés sont stockés avec timestamp, texte, engagement (retweets, likes)

**Given** le scraper détecte un rate limit
**When** la limite est atteinte (>90% utilisation)
**Then** une alerte est loggée
**And** le scraper passe en mode priorisation (matchs VIP uniquement)
**And** les données collectées sont sauvegardées avant arrêt

### Story 2.2: Implémenter le scraper Reddit

As a développeur,
I want implémenter un scraper Reddit,
So que je peux collecter des discussions Reddit sur les matchs de football.

**Acceptance Criteria:**

**Given** les credentials Reddit API sont configurés
**When** le scraper Reddit est exécuté
**Then** il collecte des posts et commentaires de subreddits pertinents (r/soccer, r/football, etc.)
**And** il extrait le texte, upvotes, et timestamp
**And** les données sont stockées avec format cohérent avec Twitter

**Given** le scraper Reddit fonctionne
**When** il rencontre une erreur
**Then** l'erreur est loggée sans arrêter le processus global
**And** le scraper continue avec les autres sources

### Story 2.3: Implémenter le scraper RSS

As a développeur,
I want implémenter un scraper RSS,
So que je peux collecter des articles de sources RSS sur les matchs.

**Acceptance Criteria:**

**Given** des URLs RSS sont configurées (sources sportives)
**When** le scraper RSS est exécuté
**Then** il parse les flux RSS et extrait les articles pertinents
**And** il extrait le titre, contenu, date de publication
**And** les données sont stockées avec format cohérent

**Given** une source RSS est indisponible
**When** le scraper tente de la lire
**Then** l'erreur est loggée
**And** le scraper continue avec les autres sources RSS

### Story 2.4: Implémenter l'analyse de sentiment avec VADER

As a développeur,
I want implémenter l'analyse de sentiment avec VADER/textblob,
So que je peux analyser le sentiment des tweets collectés en temps réel.

**Acceptance Criteria:**

**Given** des tweets sont collectés
**When** l'analyseur de sentiment est exécuté
**Then** il analyse 1000+ tweets en < 1 seconde
**And** il calcule un score de sentiment (positif, négatif, neutre) pour chaque tweet
**And** les scores sont stockés avec les tweets

**Given** l'analyseur traite un batch de tweets
**When** le traitement est terminé
**Then** les métriques agrégées sont calculées (total positif, négatif, neutre)
**And** les résultats sont disponibles pour le calcul d'énergie

### Story 2.5: Implémenter le calcul d'énergie collective

As a développeur,
I want implémenter le calcul d'énergie collective selon la formule,
So que je peux générer un score d'énergie pour chaque équipe.

**Acceptance Criteria:**

**Given** les données de sentiment sont disponibles (Twitter, Reddit, RSS)
**When** le calcul d'énergie est exécuté
**Then** il applique la formule : Score = (Positif - Négatif) × Volume × Viralité
**And** il applique la pondération : Twitter 60%, Reddit 25%, RSS 15%
**And** il applique la pondération temporelle (tweets récents plus importants)
**And** le score final est entre 0 et 100

**Given** une source est indisponible (ex: Twitter down)
**When** le calcul d'énergie est exécuté
**Then** il utilise uniquement les sources disponibles avec pondération ajustée
**And** le niveau de confiance est réduit (ex: 58% au lieu de 67%)

### Story 2.6: Configurer RabbitMQ pour queue asynchrone

As a développeur,
I want configurer RabbitMQ pour découpler scraping et analyse,
So que le système peut gérer les pics de charge efficacement.

**Acceptance Criteria:**

**Given** RabbitMQ est installé et configuré
**When** le système envoie des tâches de scraping
**Then** les tâches sont ajoutées à une queue RabbitMQ
**And** les workers consomment les tâches de manière asynchrone
**And** les résultats sont publiés dans une queue de résultats

**Given** un pic de charge survient
**When** plusieurs matchs doivent être analysés simultanément
**Then** les tâches sont distribuées entre plusieurs workers
**And** le système reste stable sans surcharge

---

## Epic 3: Prediction System & Backtesting

Créer un système de prédiction validé scientifiquement avec backtesting. Les utilisateurs bénéficieront de prédictions fiables avec un taux de précision ≥ 60% validé sur 100+ matchs historiques.

### Story 3.1: Créer le modèle de données pour matchs et prédictions

As a développeur,
I want créer les modèles de données pour matchs et prédictions,
So que je peux stocker les informations de matchs et les prédictions générées.

**Acceptance Criteria:**

**Given** la base de données SQLite est configurée
**When** je crée les schémas Drizzle pour `matches` et `predictions`
**Then** la table `matches` contient : id, home_team, away_team, date, league, status
**And** la table `predictions` contient : id, match_id, energy_score, confidence, predicted_winner, created_at
**And** les relations foreign key sont configurées
**And** les migrations sont générées et appliquées

**Given** les modèles SQLAlchemy sont créés dans FastAPI
**When** je synchronise avec la base de données
**Then** les modèles Pydantic pour validation sont créés
**And** les relations entre modèles fonctionnent correctement

### Story 3.2: Implémenter le système de calcul de prédictions

As a développeur,
I want implémenter le système de calcul de prédictions basé sur l'énergie collective,
So que je peux générer des prédictions pour chaque match.

**Acceptance Criteria:**

**Given** les scores d'énergie sont calculés pour deux équipes
**When** le système calcule la prédiction
**Then** il compare les scores d'énergie des deux équipes
**And** il calcule le Confidence Meter (0-100%) basé sur la différence d'énergie
**And** il détermine l'équipe prédite gagnante
**And** la prédiction est stockée dans la base de données

**Given** une prédiction est générée
**When** elle est sauvegardée
**Then** elle est associée au match correspondant
**And** elle contient timestamp, confidence, et équipe prédite

### Story 3.3: Implémenter le système de backtesting

As a développeur,
I want implémenter le système de backtesting sur 100+ matchs historiques,
So que je peux valider que le taux de précision est ≥ 60%.

**Acceptance Criteria:**

**Given** 100+ matchs historiques avec résultats réels sont disponibles
**When** le système de backtesting est exécuté
**Then** il calcule les prédictions pour chaque match historique
**And** il compare les prédictions avec les résultats réels
**And** il calcule le taux de précision global
**And** il génère un rapport détaillé avec : nombre de matchs testés, nombre de prédictions correctes, taux de précision

**Given** le backtesting est terminé
**When** le taux de précision est calculé
**Then** si précision ≥ 60%, le système est validé
**And** si précision < 55%, une alerte indique qu'une révision est nécessaire
**And** les résultats sont exportables (JSON, CSV) pour publication

### Story 3.4: Créer l'endpoint API pour récupérer les prédictions

As a utilisateur,
I want accéder aux prédictions via une API,
So que je peux consulter les prédictions pour les matchs à venir.

**Acceptance Criteria:**

**Given** des prédictions existent dans la base de données
**When** je fais une requête GET `/api/v1/predictions`
**Then** je reçois une liste de prédictions avec match, confidence, équipe prédite
**And** les prédictions sont triées par date de match (prochaines en premier)
**And** la réponse est au format JSON avec structure standardisée

**Given** je fais une requête pour un match spécifique
**When** je fais GET `/api/v1/predictions/{match_id}`
**Then** je reçois les détails complets de la prédiction
**And** la réponse inclut l'énergie collective, confidence, historique

---

## Epic 4: User Authentication & Access Control

Permettre aux utilisateurs de s'inscrire, se connecter et accéder à l'application selon leur niveau (gratuit ou premium). Les utilisateurs bénéficieront d'un système d'authentification sécurisé et d'un accès différencié selon leur abonnement.

### Story 4.1: Configurer Better Auth pour authentification

As a développeur,
I want configurer Better Auth v1.4.4,
So que je peux implémenter l'authentification utilisateur de manière sécurisée.

**Acceptance Criteria:**

**Given** Better Auth est installé
**When** je configure Better Auth dans Next.js
**Then** la configuration est créée avec support JWT stateless
**And** les routes d'authentification sont configurées (/api/auth/login, /api/auth/register)
**And** les cookies sécurisés sont configurés (HttpOnly, Secure, SameSite)
**And** la connexion à la base de données est établie

**Given** Better Auth est configuré
**When** je teste l'inscription
**Then** un nouvel utilisateur peut s'inscrire avec email et mot de passe
**And** le mot de passe est hashé avec bcrypt
**And** l'utilisateur est créé dans la base de données

### Story 4.2: Implémenter l'inscription et la connexion utilisateur

As a utilisateur,
I want m'inscrire et me connecter à l'application,
So que je peux accéder à mes prédictions personnelles.

**Acceptance Criteria:**

**Given** je suis sur la page d'inscription
**When** je remplis le formulaire avec email et mot de passe valides
**Then** mon compte est créé
**And** je suis automatiquement connecté
**And** je suis redirigé vers le dashboard

**Given** je suis sur la page de connexion
**When** je saisis mes identifiants corrects
**Then** je suis connecté
**And** ma session est créée
**And** je suis redirigé vers le dashboard

**Given** je saisis des identifiants incorrects
**When** je tente de me connecter
**Then** un message d'erreur clair est affiché
**And** je reste sur la page de connexion

### Story 4.3: Implémenter le système de permissions gratuit/premium

As a développeur,
I want implémenter le système RBAC pour différencier gratuit et premium,
So que je peux limiter l'accès selon le type d'abonnement.

**Acceptance Criteria:**

**Given** un utilisateur est créé
**When** il s'inscrit
**Then** il a le rôle "free" par défaut
**And** le champ `is_premium` est à `false` dans la base de données

**Given** un utilisateur premium existe
**When** il accède à une fonctionnalité
**Then** le système vérifie son statut premium
**And** les fonctionnalités premium sont accessibles si `is_premium = true`
**And** les fonctionnalités premium sont bloquées si `is_premium = false`

### Story 4.4: Implémenter la gestion des limites de prédictions

As a utilisateur gratuit,
I want voir mes limites de prédictions quotidiennes,
So que je comprends combien de prédictions je peux consulter.

**Acceptance Criteria:**

**Given** un utilisateur gratuit consulte une prédiction
**When** il accède à une prédiction
**Then** le système vérifie son quota quotidien (1-2 prédictions/jour)
**And** si le quota n'est pas dépassé, la prédiction est affichée
**And** le compteur de prédictions consultées est incrémenté

**Given** un utilisateur gratuit a atteint sa limite
**When** il tente de consulter une prédiction supplémentaire
**Then** un message indique qu'il a atteint sa limite
**And** une option pour passer à Premium est proposée
**And** la prédiction n'est pas affichée

**Given** un utilisateur premium consulte des prédictions
**When** il accède à des prédictions
**Then** aucune limite n'est appliquée
**And** toutes les prédictions sont accessibles

### Story 4.5: Implémenter le rate limiting différencié

As a développeur,
I want implémenter le rate limiting différencié pour gratuit et premium,
So que je peux protéger l'API tout en offrant un meilleur service aux utilisateurs premium.

**Acceptance Criteria:**

**Given** un utilisateur gratuit fait des requêtes API
**When** il dépasse 10 requêtes/minute
**Then** une erreur 429 (Too Many Requests) est retournée
**And** les headers `X-RateLimit-Remaining` et `X-RateLimit-Reset` sont inclus

**Given** un utilisateur premium fait des requêtes API
**When** il fait des requêtes
**Then** la limite est de 100 requêtes/minute
**And** les headers de rate limit sont inclus dans la réponse

---

## Epic 5: Dashboard & Core Visualizations

Permettre aux utilisateurs de consulter les prédictions avec des visualisations claires et intuitives. Les utilisateurs bénéficieront d'un dashboard temps réel avec Confidence Meter et visualisations d'énergie pour prendre des décisions éclairées.

### Story 5.1: Créer le composant ConfidenceMeter

As a utilisateur,
I want voir le niveau de confiance d'une prédiction de manière visuelle,
So que je peux comprendre rapidement la fiabilité de la prédiction.

**Acceptance Criteria:**

**Given** une prédiction avec confidence de 78%
**When** le composant ConfidenceMeter est affiché
**Then** il affiche le pourcentage (78%)
**And** il utilise la couleur verte (🟢) car >70%
**And** une barre de progression visuelle montre le niveau
**And** un tooltip explicatif apparaît au tap/clic

**Given** je tap sur le Confidence Meter
**When** le tooltip s'affiche
**Then** il explique "Sur 100 matchs avec ce score, 78 ont été prédits correctement"
**And** le tooltip disparaît si je tap ailleurs

**Given** une prédiction avec confidence de 45%
**When** le composant est affiché
**Then** il utilise la couleur rouge (🔴) car <50%
**And** le design est cohérent avec les autres niveaux

### Story 5.2: Créer le composant MatchListItem

As a utilisateur,
I want voir une liste de matchs avec leurs prédictions,
So que je peux scanner rapidement les matchs disponibles.

**Acceptance Criteria:**

**Given** des matchs avec prédictions existent
**When** la liste de matchs est affichée
**Then** chaque item affiche : équipes, date/heure, Confidence Meter
**And** les items sont triés par date (prochains en premier)
**And** le design est responsive (mobile-first)

**Given** je tap sur un MatchListItem
**When** l'item est sélectionné
**Then** la card s'expand pour montrer plus de détails
**And** les détails incluent graphique d'énergie, historique

### Story 5.3: Créer le composant EnergyWave pour visualisation 24h

As a utilisateur,
I want voir l'évolution de l'énergie collective sur 24h,
So que je peux comprendre comment le sentiment a évolué avant le match.

**Acceptance Criteria:**

**Given** des données d'énergie sur 24h sont disponibles
**When** le composant EnergyWave est affiché
**Then** il affiche un graphique de ligne montrant l'évolution
**And** l'axe X montre le temps (-24h à maintenant)
**And** l'axe Y montre le niveau d'énergie (0-100)
**And** le graphique est interactif (hover pour voir valeurs précises)

**Given** le graphique est affiché sur mobile
**When** je consulte la visualisation
**Then** le graphique est responsive et lisible
**And** les interactions tactiles fonctionnent (pinch to zoom si nécessaire)

### Story 5.4: Créer le dashboard principal avec navigation

As a utilisateur,
I want accéder au dashboard principal avec navigation intuitive,
So que je peux naviguer facilement entre les sections de l'application.

**Acceptance Criteria:**

**Given** je suis connecté
**When** j'accède au dashboard
**Then** la navigation bottom bar est affichée (mobile) avec 4 onglets : Accueil, Matchs, Historique, Profil
**And** la navigation top tabs est affichée (desktop) avec les mêmes sections
**And** la zone de clic est min 44x44px (mobile) / 48x48px (desktop)

**Given** je suis sur mobile
**When** je swipe gauche/droite
**Then** je navigue entre les onglets
**And** l'animation de transition est fluide (300ms)

**Given** je suis sur le dashboard
**When** je pull-to-refresh
**Then** les prédictions sont rafraîchies
**And** un indicateur de chargement est affiché

### Story 5.5: Implémenter le dashboard temps réel avec D3.js

As a utilisateur,
I want voir les prédictions mises à jour en temps réel,
So que je peux suivre les changements d'énergie collective.

**Acceptance Criteria:**

**Given** le dashboard est affiché
**When** les données d'énergie sont mises à jour
**Then** le dashboard se met à jour automatiquement en < 3 secondes
**And** les visualisations D3.js sont animées de manière fluide
**And** les utilisateurs voient les changements sans rechargement de page

**Given** une mise à jour est en cours
**When** les nouvelles données arrivent
**Then** un indicateur subtil montre que les données sont rafraîchies
**And** les transitions sont fluides (60fps)

---

## Epic 6: User Experience & Engagement

Créer une expérience utilisateur complète avec onboarding et suivi personnel. Les utilisateurs bénéficieront d'une interface intuitive, d'un guidage progressif et d'un suivi de leur performance personnelle.

### Story 6.1: Créer la landing page avec capture d'emails

As a visiteur,
I want voir une landing page attractive avec possibilité de m'inscrire,
So que je peux rejoindre la liste d'attente ou m'inscrire directement.

**Acceptance Criteria:**

**Given** je visite la landing page
**When** la page se charge
**Then** elle affiche le hero avec valeur proposition claire
**And** elle montre les résultats de backtesting (ex: "63% de précision sur 100 matchs")
**And** un formulaire de capture d'email est visible
**And** le design est responsive et moderne

**Given** je saisis mon email dans le formulaire
**When** je soumets le formulaire
**Then** mon email est envoyé à Mailchimp (intégration gratuite)
**And** un message de confirmation est affiché
**And** je peux optionnellement créer un compte directement

### Story 6.2: Implémenter l'onboarding progressif optionnel

As a nouvel utilisateur,
I want suivre un onboarding optionnel pour comprendre l'application,
So que je peux utiliser l'application efficacement dès le début.

**Acceptance Criteria:**

**Given** je suis un nouvel utilisateur
**When** je me connecte pour la première fois
**Then** un écran d'onboarding optionnel est proposé (3 étapes)
**And** un bouton "Passer" est visible sur chaque écran
**And** une progress bar montre l'avancement (1/3, 2/3, 3/3)

**Given** je choisis de suivre l'onboarding
**When** je complète l'étape 1 "Comment ça marche ?"
**Then** une animation visuelle de l'énergie collective est affichée
**And** je peux passer à l'étape suivante ou quitter

**Given** je complète l'onboarding
**When** je termine les 3 étapes
**Then** je suis redirigé vers le dashboard
**And** l'onboarding peut être revu depuis le profil plus tard

### Story 6.3: Implémenter l'historique personnel avec ROI

As a utilisateur,
I want voir mon historique de prédictions consultées avec mon ROI,
So que je peux suivre ma performance personnelle.

**Acceptance Criteria:**

**Given** j'ai consulté plusieurs prédictions
**When** j'accède à la section Historique
**Then** je vois la liste de mes prédictions consultées
**And** chaque prédiction montre : match, date consultée, confidence, résultat (si connu)
**And** mon ROI personnel est calculé et affiché (ex: "+240€ depuis inscription")

**Given** une prédiction que j'ai consultée est confirmée
**When** le résultat du match est connu
**Then** la prédiction est marquée comme correcte ou incorrecte
**And** mon taux de précision personnel est mis à jour
**And** un badge de succès est affiché si la prédiction était correcte

---

## Epic 7: Gamification & Social Features

Engager les utilisateurs et créer de la viralité via gamification et partage social. Les utilisateurs bénéficieront d'un système de classement, de badges, de parrainage et de partage de leurs réussites.

### Story 7.1: Implémenter le système de classement (Top 100)

As a utilisateur,
I want voir le classement des meilleurs utilisateurs,
So que je peux me comparer avec la communauté.

**Acceptance Criteria:**

**Given** plusieurs utilisateurs ont consulté des prédictions
**When** j'accède au classement
**Then** je vois le Top 100 des utilisateurs
**And** le classement est basé sur le taux de précision et le nombre de prédictions consultées
**And** mon rang personnel est mis en évidence si je suis dans le Top 100

**Given** le classement est affiché
**When** je consulte la liste
**Then** chaque utilisateur montre : rang, pseudo (ou anonyme), précision, nombre de prédictions
**And** le design est attrayant et encourage la compétition saine

### Story 7.2: Implémenter le système de badges et réalisations

As a utilisateur,
I want gagner des badges pour mes accomplissements,
So que je peux montrer mes réussites et me motiver.

**Acceptance Criteria:**

**Given** j'ai consulté 10 prédictions correctes
**When** j'atteins cet objectif
**Then** je reçois un badge "Débutant Prophète"
**And** le badge est affiché dans mon profil
**And** une notification de succès est affichée

**Given** j'ai plusieurs badges
**When** j'accède à mon profil
**Then** tous mes badges sont affichés
**And** je peux partager mes badges sur les réseaux sociaux

### Story 7.3: Implémenter le programme de parrainage

As a utilisateur,
I want inviter des amis et gagner des récompenses,
So que je peux bénéficier d'avantages en partageant l'application.

**Acceptance Criteria:**

**Given** je suis connecté
**When** j'accède à la section Parrainage
**Then** je vois mon lien de parrainage unique
**And** je vois combien d'amis j'ai invités
**And** je vois mes récompenses disponibles

**Given** 3 de mes amis s'inscrivent via mon lien
**When** le 3ème ami s'inscrit
**Then** je reçois 1 mois premium GRATUIT
**And** une notification de succès est affichée
**And** mon statut premium est activé automatiquement

### Story 7.4: Implémenter le partage de réussites avec format pré-rempli

As a utilisateur,
I want partager mes prédictions réussies facilement,
So que je peux montrer mes succès et inviter mes amis.

**Acceptance Criteria:**

**Given** une de mes prédictions est confirmée correcte
**When** je consulte le résultat
**Then** un bouton "Partager" est visible
**And** le format de partage est pré-rempli : "J'ai gagné grâce à Chartbastan ! 🏆 Prédiction : PSG 78% → Résultat : 3-0 ✅"

**Given** je tap sur le bouton Partager
**When** le menu de partage s'ouvre
**Then** je peux choisir WhatsApp, Twitter, ou Facebook
**And** une image générée automatiquement est incluse (card visuelle)
**And** le partage s'effectue avec le format pré-rempli

---

## Epic 8: Notifications & Alerts

Alerter les utilisateurs des changements importants et des confirmations de prédictions. Les utilisateurs bénéficieront de notifications pertinentes pour ne manquer aucune opportunité importante.

### Story 8.1: Implémenter les notifications push pour changements majeurs

As a utilisateur,
I want recevoir des notifications pour changements majeurs d'énergie,
So que je ne manque pas les opportunités importantes.

**Acceptance Criteria:**

**Given** l'énergie collective d'une équipe change de manière significative (>10% en 30 min)
**When** le changement est détecté
**Then** une notification push est envoyée aux utilisateurs premium
**And** la notification indique l'équipe, le changement, et le nouveau niveau de confiance
**And** la notification est non-intrusive et informative

**Given** je suis un utilisateur gratuit
**When** un changement majeur survient
**Then** je ne reçois pas de notification (fonctionnalité premium)
**And** je peux voir les changements en ouvrant l'application

### Story 8.2: Implémenter les notifications pour prédictions confirmées

As a utilisateur,
I want recevoir une notification quand ma prédiction est confirmée correcte,
So que je peux célébrer mes succès.

**Acceptance Criteria:**

**Given** j'ai consulté une prédiction
**When** le match se termine et la prédiction est correcte
**Then** je reçois une notification push : "🏆 Votre prédiction PSG 78% est CONFIRMÉE ! Score final : 3-0"
**And** la notification inclut un lien vers les détails
**And** une animation de succès est affichée dans l'app

**Given** ma prédiction est incorrecte
**When** le match se termine
**Then** je ne reçois pas de notification (pour éviter frustration)
**And** je peux voir le résultat dans l'historique si je consulte l'app

### Story 8.3: Implémenter la gestion des préférences de notifications

As a utilisateur,
I want contrôler quelles notifications je reçois,
So que je ne suis pas submergé de notifications non pertinentes.

**Acceptance Criteria:**

**Given** je suis dans les paramètres
**When** j'accède aux préférences de notifications
**Then** je peux activer/désactiver : changements majeurs, confirmations, alertes premium
**And** mes préférences sont sauvegardées
**And** les notifications respectent mes préférences

---

## Epic 9: Advanced Features & API (Phase 2+)

Fournir des fonctionnalités avancées et une API publique pour développeurs tiers. Les utilisateurs avancés et développeurs bénéficieront d'analyses comparatives et d'un accès API pour intégrations.

### Story 9.1: Créer l'API publique avec documentation OpenAPI

As a développeur tiers,
I want accéder à une API publique documentée,
So que je peux intégrer les prédictions dans mes propres applications.

**Acceptance Criteria:**

**Given** l'API publique est implémentée
**When** je consulte `/docs` (Swagger UI)
**Then** je vois la documentation complète de l'API
**And** tous les endpoints sont documentés avec exemples
**And** je peux tester les endpoints directement depuis la documentation

**Given** je fais une requête à l'API publique
**When** j'utilise une clé API valide
**Then** je reçois les données au format JSON
**And** la réponse suit le format standardisé avec `data` et `meta`

### Story 9.2: Implémenter la comparaison Énergie vs Stats Traditionnelles

As a utilisateur premium,
I want comparer les prédictions basées sur l'énergie avec les stats traditionnelles,
So que je peux prendre des décisions plus éclairées.

**Acceptance Criteria:**

**Given** une prédiction existe pour un match
**When** j'accède aux détails avancés
**Then** je vois une comparaison side-by-side : Prédiction Énergie vs Stats Traditionnelles vs Cotes
**And** les différences sont mises en évidence
**And** un graphique comparatif est affiché

### Story 9.3: Implémenter le calendrier énergétique de matchs

As a utilisateur,
I want voir un calendrier avec les matchs et leurs niveaux d'énergie,
So que je peux planifier mes consultations de prédictions.

**Acceptance Criteria:**

**Given** plusieurs matchs sont programmés
**When** j'accède au calendrier énergétique
**Then** je vois un calendrier mensuel avec les matchs
**And** chaque match affiche son niveau d'énergie (code couleur)
**And** je peux filtrer par ligue, équipe, ou niveau d'énergie
**And** je peux cliquer sur un match pour voir les détails
