veza/GUIDE_DEMARRAGE_INTEGRATION.md

# 🚀 Guide de Démarrage - Test Intégration Veza

**Objectif**: Lancer l'environnement complet pour tester l'intégration backend ↔ frontend dans le navigateur.

---

## 📋 État des Lieux

### Infrastructure (Docker Compose)
- **PostgreSQL**: Port `5432` (user: `veza`, password: `password`, db: `veza`)
- **Redis**: Port `6379` (pour CSRF, cache, rate limiting)
- **RabbitMQ**: Ports `5672` (AMQP) et `15672` (Management UI)

### Services
- **Backend Go**: Port `8080` (`veza-backend-api/`)
- **Frontend React**: Port `3000` (`apps/web/`) - configuré dans `vite.config.ts`
- **Chat Server Rust**: Port `8081` (optionnel pour tests)
- **Stream Server Rust**: Port `8082` (optionnel pour tests)

### Commandes Disponibles

#### Makefile (Racine)
```bash
make help              # Affiche toutes les commandes
make setup             # Installation complète (deps + tools)
make infra-up          # Démarrer infrastructure Docker
make infra-down        # Arrêter infrastructure Docker
make db-migrate        # Exécuter migrations DB
make dev               # Démarrer TOUT (infra + backends + frontend)
make dev-backend       # Démarrer backends uniquement
make status            # Vérifier santé des services
```

#### Frontend (`apps/web/`)
```bash
npm run dev            # Démarrer Vite dev server (port 3000)
npm run build          # Build production
npm run typecheck      # Vérifier types TypeScript
npm run test           # Tests unitaires
npm run test:e2e       # Tests E2E Playwright
```

#### Backend (`veza-backend-api/`)
```bash
go run cmd/api/main.go # Démarrer serveur (port 8080)
make run               # Build + run
make dev               # Run en mode dev
```

---

## 🎯 Démarrage Rapide (Recommandé)

### Option 1: Tout-en-un avec Makefile

```bash
# 1. Installation initiale (une seule fois)
make setup

# 2. Démarrer l'infrastructure Docker
make infra-up

# 3. Exécuter les migrations
make db-migrate

# 4. Démarrer TOUT (infra + backends + frontend)
make dev
```

**Résultat**: 
- ✅ Infrastructure Docker démarrée
- ✅ Backend Go sur http://localhost:8080
- ✅ Frontend React sur http://localhost:3000
- ✅ Hot reload activé si outils installés (air, cargo-watch)

**Accès**:
- Frontend: http://localhost:3000
- Backend API: http://localhost:8080/api/v1
- Swagger: http://localhost:8080/docs
- RabbitMQ UI: http://localhost:15672 (veza/password)

---

### Option 2: Démarrage Manuel (Plus de contrôle)

#### Étape 1: Infrastructure Docker

```bash
# Démarrer Postgres, Redis, RabbitMQ
make infra-up

# Vérifier que tout est prêt
make status
```

#### Étape 2: Migrations Base de Données

```bash
make db-migrate
```

#### Étape 3: Backend Go

```bash
cd veza-backend-api

# Créer fichier .env si inexistant
cat > .env << EOF
APP_ENV=development
JWT_SECRET=dev-secret-key-minimum-32-characters-long-for-testing
DATABASE_URL=postgres://veza:password@localhost:5432/veza?sslmode=disable
REDIS_URL=redis://localhost:6379
CORS_ALLOWED_ORIGINS=http://localhost:3000,http://localhost:5173
APP_PORT=8080
LOG_LEVEL=INFO
EOF

# Démarrer le serveur
go run cmd/api/main.go

# OU avec hot reload (si air installé)
air
```

**Vérification Backend**:
```bash
curl http://localhost:8080/health
# Devrait retourner: {"status":"ok"}
```

#### Étape 4: Frontend React

```bash
cd apps/web

# Installer dépendances (si pas déjà fait)
npm install

# Démarrer Vite dev server
npm run dev
```

**Vérification Frontend**:
- Ouvrir http://localhost:3000 dans le navigateur
- La page devrait se charger

---

## ⚙️ Configuration Requise

### Variables d'Environnement Backend

**Fichier**: `veza-backend-api/.env`

```bash
# REQUIS
APP_ENV=development
JWT_SECRET=dev-secret-key-minimum-32-characters-long-for-testing
DATABASE_URL=postgres://veza:password@localhost:5432/veza?sslmode=disable

# REQUIS pour CSRF (en développement, Redis peut être optionnel)
REDIS_URL=redis://localhost:6379

# REQUIS pour CORS (en développement, defaults locaux OK)
CORS_ALLOWED_ORIGINS=http://localhost:3000,http://localhost:5173

# Optionnel
APP_PORT=8080
LOG_LEVEL=INFO
UPLOAD_DIR=uploads
```

### Variables d'Environnement Frontend

**Fichier**: `apps/web/.env` (optionnel, valeurs par défaut OK)

```bash
# Optionnel - Valeurs par défaut utilisées si non défini
VITE_API_URL=http://127.0.0.1:8080/api/v1
VITE_WS_URL=ws://127.0.0.1:8081/ws
VITE_STREAM_URL=ws://127.0.0.1:8082/stream
VITE_UPLOAD_URL=http://127.0.0.1:8080/upload
```

**Note**: Les valeurs par défaut dans `apps/web/src/config/env.ts` sont correctes pour le développement local.

---

## 🔍 Vérification de l'Intégration

### 1. Vérifier Backend

```bash
# Health check
curl http://localhost:8080/health

# Swagger UI
open http://localhost:8080/docs

# Test endpoint API
curl http://localhost:8080/api/v1/auth/check-username?username=test
```

### 2. Vérifier Frontend

```bash
# Ouvrir dans le navigateur
open http://localhost:3000

# Vérifier console navigateur (F12)
# Devrait voir: connexion API réussie
```

### 3. Test Complet d'Intégration

1. **Ouvrir** http://localhost:3000
2. **Tester Register/Login**:
   - Créer un compte
   - Se connecter
   - Vérifier que le token est stocké
3. **Tester API**:
   - Ouvrir DevTools → Network
   - Vérifier que les requêtes incluent `Authorization: Bearer <token>`
   - Vérifier que les mutations incluent `X-CSRF-Token`
4. **Tester Upload Track**:
   - Uploader un fichier audio
   - Vérifier progression
   - Vérifier que le track apparaît dans la liste

---

## 🐛 Dépannage

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

```bash
# Vérifier ports occupés
lsof -i :8080  # Backend
lsof -i :3000  # Frontend
lsof -i :5432  # Postgres
lsof -i :6379  # Redis

# Tuer processus si nécessaire
kill -9 <PID>
```

### Problème: Backend ne démarre pas

```bash
# Vérifier variables d'environnement
cd veza-backend-api
cat .env

# Vérifier connexion DB
docker compose exec postgres psql -U veza -d veza -c "SELECT 1;"

# Vérifier connexion Redis
docker compose exec redis redis-cli ping

# Vérifier logs
go run cmd/api/main.go 2>&1 | tee backend.log
```

### Problème: Frontend ne se connecte pas au backend

```bash
# Vérifier URL API dans frontend
cd apps/web
grep -r "VITE_API_URL" src/

# Vérifier CORS
curl -v -H "Origin: http://localhost:3000" \
     -H "Access-Control-Request-Method: GET" \
     -X OPTIONS \
     http://localhost:8080/api/v1/auth/me

# Devrait retourner headers CORS
```

### Problème: Erreur CSRF

```bash
# Vérifier que Redis est démarré
docker compose ps redis

# Vérifier connexion Redis depuis backend
docker compose exec redis redis-cli ping

# Si Redis down, backend devrait loguer un warning (en dev)
# En production, backend refuse de démarrer
```

### Problème: Migrations échouent

```bash
# Réinitialiser DB (⚠️ DESTRUCTIF)
docker compose down -v
docker compose up -d postgres
make db-migrate

# OU manuellement
docker compose exec postgres psql -U veza -d veza -c "DROP SCHEMA public CASCADE; CREATE SCHEMA public;"
make db-migrate
```

---

## 📊 Commandes Utiles

### Vérifier État des Services

```bash
# État Docker
docker compose ps

# Logs en temps réel
docker compose logs -f

# Logs d'un service spécifique
docker compose logs -f postgres
docker compose logs -f redis

# Santé des services
make status
```

### Accès aux Bases de Données

```bash
# Postgres shell
make db-shell
# OU
docker compose exec postgres psql -U veza -d veza

# Redis shell
make redis-shell
# OU
docker compose exec redis redis-cli
```

### Arrêter Tout

```bash
# Arrêter infrastructure Docker
make infra-down

# Arrêter tout (infra + apps)
# Ctrl+C dans le terminal où make dev tourne
# OU
pkill -f "go run\|vite\|cargo"
make infra-down
```

---

## 🎯 Workflow Recommandé

### Première Installation

```bash
# 1. Installer dépendances système
make setup

# 2. Démarrer infrastructure
make infra-up

# 3. Migrations
make db-migrate

# 4. Vérifier
make status
```

### Développement Quotidien

```bash
# Option A: Tout en un (recommandé)
make dev

# Option B: Séparé (plus de contrôle)
# Terminal 1: Infrastructure
make infra-up

# Terminal 2: Backend
cd veza-backend-api && go run cmd/api/main.go

# Terminal 3: Frontend
cd apps/web && npm run dev
```

### Tests d'Intégration

```bash
# Backend + Frontend doivent tourner
# Puis dans apps/web:
npm run test:e2e
```

---

## ✅ Checklist de Vérification

Avant de tester l'intégration, vérifier:

- [ ] Infrastructure Docker démarrée (`make infra-up`)
- [ ] Migrations exécutées (`make db-migrate`)
- [ ] Backend Go démarré sur port 8080
- [ ] Frontend React démarré sur port 3000
- [ ] Variables d'environnement backend configurées (`.env`)
- [ ] CORS_ALLOWED_ORIGINS inclut `http://localhost:3000`
- [ ] Redis accessible (pour CSRF)
- [ ] Postgres accessible (pour données)

**Test rapide**:
```bash
# Backend
curl http://localhost:8080/health

# Frontend
curl http://localhost:3000
```

---

## 🎉 Prêt à Tester !

Une fois tout démarré:

1. **Ouvrir** http://localhost:3000 dans le navigateur
2. **Tester** le flow complet:
   - Register → Login → Upload Track → Créer Playlist
3. **Vérifier** DevTools → Network pour voir les requêtes API
4. **Vérifier** que CORS et CSRF fonctionnent correctement

**Bon développement ! 🚀**