chartbastan/docs/development-guide.md

Guide de Développement - ChartBastan

Prérequis

Outils Requis

Frontend:

• Node.js 20+ Télécharger
• npm (inclus avec Node.js)

Backend:

• Python 3.11+ Télécharger
• pip (inclus avec Python)

Optionnels:

• RabbitMQ Télécharger - Pour workers asynchrones
• Git - Pour le versioning

Vérification des Prérequis

# Vérifier Node.js
node --version  # Doit être 20+

# Vérifier npm
npm --version

# Vérifier Python
python --version  # Doit être 3.11+

# Vérifier pip
pip --version

---

Installation et Configuration

1. Cloner le Repository

git clone <repository-url>
cd chartbastan

2. Installer les Dépendances du Backend

cd backend

# Optionnel: Créer un environnement virtuel
python -m venv venv

# Activer l'environnement (Windows)
.\venv\Scripts\activate

# Activer l'environnement (Linux/Mac)
source venv/bin/activate

# Installer les dépendances
pip install -r requirements.txt

3. Installer les Dépendances du Frontend

cd ../chartbastan

# Installer les dépendances
npm install

4. Configurer les Variables d'Environnement

Backend (.env):

cd ../backend

# Créer le fichier .env
touch .env

Contenu du fichier .env:

# Base de données
DATABASE_URL=sqlite:///./chartbastan.db

# Twitter API (optionnel, pour le scraping)
TWITTER_BEARER_TOKEN=your_bearer_token_here

# Reddit API (optionnel, pour le scraping)
REDDIT_CLIENT_ID=your_client_id
REDDIT_CLIENT_SECRET=your_client_secret

# RabbitMQ (optionnel, pour workers)
RABBITMQ_URL=amqp://guest:guest@localhost:5672

Frontend (.env.local):

cd ../chartbastan

# Créer le fichier .env.local
touch .env.local

Contenu du fichier .env.local:

# URL de l'API backend
NEXT_PUBLIC_API_URL=http://localhost:8000

---

Démarrage de l'Application

Démarrer le Backend

cd backend

# Optionnel: Activer l'environnement virtuel
.\venv\Scripts\activate  # Windows
# ou
source venv/bin/activate  # Linux/Mac

# Démarrer le serveur FastAPI
python -m uvicorn app.main:app --reload --port 8000

Le serveur FastAPI démarre sur:

• API: http://localhost:8000
• Documentation Swagger: http://localhost:8000/docs
• Documentation ReDoc: http://localhost:8000/redoc

Alternative: Scripts de démarrage

# Windows
.\run_server.bat

# Linux/Mac
chmod +x run_server.sh
./run_server.sh

Démarrer le Frontend

cd chartbastan

# Démarrer le serveur de développement
npm run dev

Le serveur Next.js démarre sur:

• Application: http://localhost:3000

Vérifier que Tout Fonctionne

1. Ouvrir http://localhost:3000
2. Vous devriez voir la page d'accueil de ChartBastan
3. Tester les fonctionnalités (login, matchs, prédictions)

---

Tests Locaux

Tests Frontend

cd chartbastan

# Linter
npm run lint

# Type checking
npm run type-check

# Tests unitaires
npm run test

# Build de production
npm run build

Tests Backend

cd backend

# Linter
flake8 .

# Formatage
black .

# Tests unitaires
pytest tests/ -v

---

Commandes de Développement

Frontend (chartbastan/)

Commande	Description
npm run dev	Démarrer le serveur de développement (port 3000)
npm run build	Build de production
npm run start	Démarrer le serveur de production
npm run lint	Exécuter ESLint
npm run type-check	Vérifier les types TypeScript
npm run test	Exécuter les tests Vitest

Backend (backend/)

Commande	Description
python -m uvicorn app.main:app --reload --port 8000	Démarrer le serveur FastAPI
flake8 .	Linting du code Python
black .	Formatage du code Python
pytest tests/	Exécuter les tests unitaires
alembic upgrade head	Appliquer toutes les migrations

---

Tâches de Développement Courantes

1. Ajouter une Nouvelle Page (Frontend)

cd chartbastan/src/app
mkdir nouvelle-page

Créer nouvelle-page/page.tsx:

export default function NouvellePage() {
  return <div>Contenu de la nouvelle page</div>;
}

Accéder à: http://localhost:3000/nouvelle-page

2. Ajouter un Nouvel Endpoint API (Backend)

Créer backend/app/api/new_endpoint.py:

from fastapi import APIRouter

router = APIRouter()

@router.get("/new-endpoint")
async def get_new_endpoint():
    return {"message": "Hello from new endpoint"}

Enregistrer dans backend/app/main.py:

from app.api import new_endpoint

app.include_router(new_endpoint.router, prefix="/api", tags=["new"])

Accéder à: http://localhost:8000/api/new-endpoint

3. Ajouter un Nouveau Composant (Frontend)

Créer chartbastan/src/components/NewComponent.tsx:

export function NewComponent() {
  return <div>Nouveau composant</div>;
}

Utiliser dans une page:

import { NewComponent } from '@/components/NewComponent';

export default function Page() {
  return <NewComponent />;
}

---

Dépannage

Backend Ne Démarre Pas

Problème: Port 8000 déjà utilisé

# Windows
netstat -ano | findstr :8000
taskkill /PID <PID> /F

# Linux/Mac
lsof -ti:8000 | xargs kill -9

Problème: Dépendances manquantes

cd backend
pip install -r requirements.txt --upgrade

Frontend Ne Démarre Pas

Problème: Port 3000 déjà utilisé

# Windows
netstat -ano | findstr :3000
taskkill /PID <PID> /F

# Linux/Mac
lsof -ti:3000 | xargs kill -9

Problème: Dépendances manquantes

cd chartbastan
rm -rf node_modules
npm install

Erreur de Connexion Frontend-Backend

Vérifier:

1. Backend en cours d'exécution sur http://localhost:8000
2. Frontend .env.local contient NEXT_PUBLIC_API_URL=http://localhost:8000
3. CORS activé sur le backend (voir backend/app/middleware/cors.py)

Erreur de Base de Données

Problème: Base de données non initialisée

cd backend

# Appliquer les migrations
alembic upgrade head

# Optionnel: Générer des données de test
python scripts/generate_historical_matches.py

Erreur de Scraping

Problème: Clés API manquantes

cd backend
# Vérifier le fichier .env
cat .env

# Ajouter les clés API Twitter/Reddit/RSS

---

Outils de Développement

IDE Recommandé

Cursor / VS Code:

• Extensions recommandées:
  • ESLint
  • Prettier
  • Tailwind CSS IntelliSense
  • Prisma (pour Drizzle)
  • Python
  • REST Client

Débogage

Frontend:

• DevTools Chrome/Edge
• React DevTools extension
• Logger dans la console

Backend:

• Logs dans le terminal
• Documentation Swagger: http://localhost:8000/docs
• Debugger Python dans VS Code

Surveillance

Backend:

• Vérifier les logs dans le terminal
• Monitor RabbitMQ (si utilisé): http://localhost:15672

Frontend:

• Network tab DevTools pour appels API
• React DevTools pour state

---

Best Practices

Code Style

Frontend (TypeScript/React):

• Utiliser snake_case pour les variables backend, camelCase pour frontend
• Typage strict avec TypeScript
• Composants réutilisables
• Separation of concerns (UI, logic, data)

Backend (Python):

• Style PEP 8 avec Black
• Type hints pour toutes les fonctions
• Docstrings pour les fonctions complexes
• Séparation des couches (API, service, repository)

Git Workflow

main (production)
  ↑
develop (staging)
  ↑
feature/ma-fonctionnalité (branche de développement)

1. Créer une branche feature/ma-fonctionnalité
2. Développer la fonctionnalité
3. Commit les changements avec des messages clairs
4. Push vers la branche
5. Créer une Pull Request vers develop
6. Review et merge

Commit Messages

feat: ajouter la fonctionnalité X
fix: corriger le bug Y
docs: mettre à jour la documentation
refactor: refactoriser le code Z
test: ajouter des tests pour X

---

Ressources

Documentation

• Frontend: chartbastan/README.md
• Backend: _bmad-output/planning-artifacts/architecture.md
• Implémentation: _bmad-output/implementation-artifacts/
• API: http://localhost:8000/docs (Swagger)

Liens Utiles

• Next.js Docs: https://nextjs.org/docs
• FastAPI Docs: https://fastapi.tiangolo.com/
• React Docs: https://react.dev/
• Tailwind CSS: https://tailwindcss.com/docs
• Drizzle ORM: https://orm.drizzle.team/
• SQLAlchemy: https://docs.sqlalchemy.org/

---

Support

Pour les problèmes ou questions:

• Consulter les artefacts d'implémentation dans _bmad-output/implementation-artifacts/
• Vérifier la documentation Swagger: http://localhost:8000/docs
• Consulter le README principal: chartbastan/README.md