DEMARRAGE.md

# Guide de Démarrage - Simulation Réseau de Files d'Attente

## Projet Universitaire
**Cours**: Modélisation Incertitude et Simulation 2025-2026
**Sujet**: Simulation d'une base de données distribuée avec files d'attente

---

## 🚀 Démarrage Rapide

### Prérequis
- **Python 3.10+** avec pip
- **Node.js 18+** avec npm
- Terminal bash/zsh

### Installation

1. **Cloner le projet** (si applicable)
```bash
cd /Users/hamaba/Documents/projet-reseau-de-files-d-attentes
```

2. **Installer les dépendances**

**Backend (Python):**
```bash
cd apps/backend
python3 -m venv venv
source venv/bin/activate
pip install -r requirements.txt
```

**Frontend (React):**
```bash
# Depuis la racine du projet
npm install
```

### Lancement de l'Application

**Option 1: Lancement Manuel (2 terminaux)**

**Terminal 1 - Backend:**
```bash
cd apps/backend
source venv/bin/activate
uvicorn src.main:app --reload --host 0.0.0.0 --port 8000
```

**Terminal 2 - Frontend:**
```bash
# Depuis la racine
npm run dev
```

**Option 2: Test d'Intégration**
```bash
# Vérifier que tout fonctionne
./test-integration.sh
```

### Accès à l'Application

- **Frontend (Interface Web)**: http://localhost:5173
- **Backend API**: http://localhost:8000
- **Documentation API (Swagger)**: http://localhost:8000/docs
- **Documentation API (ReDoc)**: http://localhost:8000/redoc

---

## 📋 Utilisation

### 1. Interface Web

1. Ouvrir http://localhost:5173 dans votre navigateur
2. **Configuration**:
   - Sélectionner un scénario prédéfini (Scenario 1-5) OU
   - Configurer manuellement les paramètres (λ, μc, p, serveurs)
3. **Exécution**:
   - Cliquer sur "Démarrer la simulation"
   - Observer l'indicateur de statut
4. **Résultats**:
   - Onglet **Métriques**: Tableaux détaillés (simulation + analytique)
   - Onglet **Visualisations**: Diagrammes et graphiques
   - Onglet **Comparaison**: Table comparative + charts
5. **Export**:
   - Boutons "Exporter JSON" ou "Exporter CSV" en haut à droite

### 2. API REST (Tests CLI)

**Lister les scénarios:**
```bash
curl http://localhost:8000/api/scenarios/ | python3 -m json.tool
```

**Exécuter un scénario:**
```bash
curl -X POST http://localhost:8000/api/scenarios/scenario_1/run | python3 -m json.tool
```

**Récupérer les résultats:**
```bash
# Remplacer SESSION_ID par l'ID retourné ci-dessus
curl http://localhost:8000/api/simulation/results/SESSION_ID | python3 -m json.tool
```

**Analyse analytique (Jackson):**
```bash
curl http://localhost:8000/api/analytics/compare/SESSION_ID | python3 -m json.tool
```

### 3. Script de Test Python

```bash
cd apps/backend
source venv/bin/activate
python test_api.py
```

---

## 📊 Les 5 Scénarios

### Scenario 1: Single Fast Server (Test d'Instabilité)
- **But**: Tester l'instabilité avec un seul serveur rapide
- **Config**: λ=0.008, μc=0.1, p=0.5, 1 serveur (μ=1/120)

### Scenario 2: Fast + Slow Server
- **But**: Équilibrer avec 2 serveurs de vitesses différentes
- **Config**: 1 serveur rapide (120ms) + 1 lent (240ms)

### Scenario 3: Three Slow Servers
- **But**: Plusieurs serveurs lents
- **Config**: 3 serveurs à 240ms chacun

### Scenario 4: Fast + Medium Server
- **But**: Comparer avec Scenario 3
- **Config**: 1 rapide (120ms) + 1 moyen (190ms)

### Scenario 5: Parameter Sensitivity
- **But**: Étude de sensibilité (variations de λ et p)
- **Config**: Plusieurs variations disponibles via `/api/scenarios/scenario_5/variations`

---

## 🧪 Tests

### Tests Backend (Unitaires)
```bash
cd apps/backend
source venv/bin/activate
pytest tests/ -v
```

**21 tests** couvrant:
- Génération aléatoire exponentielle
- Simulation discrète
- Analyse analytique (Jackson)
- Little's Law
- Conservation probabilités

### Tests d'Intégration
```bash
./test-integration.sh
```

**8 tests** validant:
- Backend health
- Endpoints API
- Exécution simulation
- Analyse Jackson
- Frontend accessible
- CORS configuré

---

## 🏗️ Architecture

### Backend (Python + FastAPI)
```
apps/backend/src/
├── core/                 # Moteur de simulation
│   ├── simulation.py     # Event-driven simulator
│   ├── queues.py         # M/M/1 queues
│   ├── events.py         # Event types
│   ├── router.py         # Probabilistic routing
│   └── scenarios.py      # 5 scénarios prédéfinis
├── analytics/            # Théorème de Jackson
│   ├── jackson.py        # Analyse analytique
│   └── comparison.py     # Comparaison sim vs analytique
├── api/                  # Endpoints REST
│   ├── simulation.py     # Contrôle simulation
│   ├── scenarios.py      # Scénarios prédéfinis
│   └── analytics.py      # Analyses Jackson
└── models/               # Pydantic models
    ├── config.py         # Configuration
    └── results.py        # Résultats
```

### Frontend (React + TypeScript)
```
apps/web/src/
├── components/
│   ├── Dashboard.tsx           # Layout principal
│   ├── simulation/             # Contrôles simulation
│   │   ├── ScenarioSelector.tsx
│   │   ├── ParameterPanel.tsx
│   │   └── SimulationControl.tsx
│   ├── results/                # Affichage résultats
│   │   ├── ResultsDisplay.tsx
│   │   ├── MetricsCard.tsx
│   │   ├── ComparisonTable.tsx
│   │   └── ExportButton.tsx
│   └── visualization/          # Charts et diagrammes
│       ├── NetworkDiagram.tsx  # D3.js topology
│       ├── UtilizationChart.tsx # Chart.js ρ
│       └── MetricsComparisonChart.tsx # L, W
├── services/
│   └── api.ts                  # API client (axios)
├── store/
│   └── simulationStore.ts      # Zustand state
└── types/
    └── simulation.ts           # TypeScript types
```

---

## 📈 Métriques Calculées

### Simulation (Événementielle)
- **ρ**: Utilisation de chaque file
- **W**: Temps moyen dans le système
- **Wq**: Temps moyen d'attente
- **Ws**: Temps moyen de service
- Compteurs: arrivées, départs

### Analytique (Jackson)
- **λeff**: Taux d'arrivée effectif pour chaque file
- **ρ = λ/μ**: Utilisation (condition stabilité: ρ < 1)
- **L = ρ/(1-ρ)**: Nombre moyen de clients (M/M/1)
- **W = L/λ**: Temps moyen (Little's Law)
- **Wq = W - 1/μ**: Temps d'attente moyen

### Comparaison
- Différence en % pour chaque métrique
- Code couleur: <5% (vert), 5-10% (jaune), >10% (rouge)

---

## 🐛 Dépannage

### Backend ne démarre pas
```bash
# Vérifier le port 8000
lsof -ti:8000 | xargs kill -9

# Relancer
cd apps/backend
source venv/bin/activate
uvicorn src.main:app --reload
```

### Frontend ne démarre pas
```bash
# Vérifier le port 5173
lsof -ti:5173 | xargs kill -9

# Relancer
npm run dev
```

### CORS Errors
Vérifier que l'origine est autorisée dans `apps/backend/src/main.py`:
```python
allow_origins=["http://localhost:5173", "http://localhost:3000"]
```

### Tests échouent
```bash
# Backend
cd apps/backend
source venv/bin/activate
pip install -r requirements.txt
pytest tests/ -v

# Frontend
npm run build
```

---

## 📝 Notes pour le Rapport

### Livrables Générés
- ✅ Code source complet (Git)
- ✅ Simulation fonctionnelle (5 scénarios)
- ✅ Validation analytique (Jackson)
- ✅ Visualisations interactives
- ✅ Export résultats (JSON/CSV)
- ✅ Tests automatisés (21 tests)

### Captures d'Écran Suggérées
1. Dashboard avec configuration
2. Diagramme topologie réseau
3. Graphiques utilisation (ρ)
4. Table comparaison analytique vs simulation
5. Résultats pour chaque scénario (1-5)

### Analyse à Inclure
- Scenario 1: Pourquoi instable (ρ > 1)
- Comparaison scénarios 3 vs 4
- Validation Jackson (différences %)
- Impact paramètres (λ, p) sur performance

---

## 📚 Références Théoriques

- **Jackson's Theorem**: Réseaux ouverts, M/M/1 en série/parallèle
- **Little's Law**: L = λW
- **M/M/1 Queue**: L = ρ/(1-ρ), W = 1/(μ-λ)
- **Simulation Discrète**: Event-driven, file de priorité

---

## 👥 Contact

Pour toute question sur l'implémentation:
1. Consulter `/docs` (Swagger) pour l'API
2. Vérifier les logs: Backend stdout, Frontend console
3. Exécuter `./test-integration.sh` pour diagnostic

---

**Projet complet et fonctionnel! 🎓**