47 KiB
| stepsCompleted | inputDocuments | status | completedAt | workflowType | |||||||
|---|---|---|---|---|---|---|---|---|---|---|---|
|
|
complete | 2026-01-17T00:00:00.000Z | 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 --turbopackpuisnpx 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