chartbastan/docs/development-guide.md

# Guide de Développement - ChartBastan

## Prérequis

### Outils Requis

**Frontend:**
- Node.js 20+ [Télécharger](https://nodejs.org/)
- npm (inclus avec Node.js)

**Backend:**
- Python 3.11+ [Télécharger](https://www.python.org/)
- pip (inclus avec Python)

**Optionnels:**
- RabbitMQ [Télécharger](https://www.rabbitmq.com/) - Pour workers asynchrones
- Git - Pour le versioning

### Vérification des Prérequis

```bash
# 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

```bash
git clone <repository-url>
cd chartbastan
```

### 2. Installer les Dépendances du Backend

```bash
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

```bash
cd ../chartbastan

# Installer les dépendances
npm install
```

### 4. Configurer les Variables d'Environnement

**Backend (.env):**

```bash
cd ../backend

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

Contenu du fichier `.env`:

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

```bash
cd ../chartbastan

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

Contenu du fichier `.env.local`:

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

---

## Démarrage de l'Application

### Démarrer le Backend

```bash
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**

```bash
# Windows
.\run_server.bat

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

### Démarrer le Frontend

```bash
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

```bash
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

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

```bash
cd chartbastan/src/app
mkdir nouvelle-page
```

Créer `nouvelle-page/page.tsx`:

```typescript
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`:

```python
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`:

```python
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`:

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

Utiliser dans une page:

```typescript
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é

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

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

**Problème:** Dépendances manquantes

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

### Frontend Ne Démarre Pas

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

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

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

**Problème:** Dépendances manquantes

```bash
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

```bash
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

```bash
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`