# 🚀 Prochaines Étapes - Plan d'Action

**Date de création:** 2025-01-27  
**Statut:** En cours de planification

---

## 📋 Vue d'Ensemble

Ce document détaille les prochaines étapes pour finaliser le projet Veza après la fusion des frontends. Chaque section contient des actions concrètes, des fichiers à modifier, et des critères de validation.

---

## 1. 🧪 Tests : Créer les Tests Unitaires et d'Intégration

### 1.1 État Actuel

- ✅ Vitest configuré (`vitest.config.ts`)
- ✅ Playwright configuré (`playwright.config.ts`)
- ✅ MSW configuré pour le mocking API
- ⚠️ Couverture de tests ~40% (objectif: 80%+)
- ⚠️ Tests unitaires manquants pour plusieurs services
- ⚠️ Tests d'intégration partiels

### 1.2 Actions à Réaliser

#### Tests Unitaires (Frontend)

**Priorité 1 - Services critiques**
- [ ] `src/services/apiClient.ts` - Tests pour intercepteurs, retry, error handling
- [ ] `src/services/tokenRefresh.ts` - Tests pour refresh automatique, queue management
- [ ] `src/services/authService.ts` - Tests pour login, logout, token management
- [ ] `src/services/trackService.ts` - Tests pour upload, CRUD operations
- [ ] `src/services/playlistService.ts` - Tests pour CRUD playlists

**Priorité 2 - Hooks personnalisés**
- [ ] `src/hooks/useAuth.ts` - Tests pour état auth, redirections
- [ ] `src/hooks/useTracks.ts` - Tests pour fetching, caching, mutations
- [ ] `src/hooks/usePlaylists.ts` - Tests pour gestion playlists
- [ ] `src/hooks/useUpload.ts` - Tests pour upload par chunks, progress tracking

**Priorité 3 - Composants métier**
- [ ] `src/components/features/auth/LoginForm.tsx` - Tests pour validation, soumission
- [ ] `src/components/features/tracks/TrackUpload.tsx` - Tests pour upload flow
- [ ] `src/components/features/playlists/PlaylistManager.tsx` - Tests pour CRUD

**Fichiers à créer:**
```
apps/web/src/services/__tests__/
├── apiClient.test.ts
├── tokenRefresh.test.ts
├── authService.test.ts
├── trackService.test.ts
└── playlistService.test.ts

apps/web/src/hooks/__tests__/
├── useAuth.test.ts
├── useTracks.test.ts
├── usePlaylists.test.ts
└── useUpload.test.ts

apps/web/src/components/features/__tests__/
├── auth/
│   └── LoginForm.test.tsx
├── tracks/
│   └── TrackUpload.test.tsx
└── playlists/
    └── PlaylistManager.test.tsx
```

#### Tests d'Intégration

**E2E avec Playwright**
- [ ] Parcours complet d'authentification (register → login → logout)
- [ ] Upload de track complet (initiate → chunks → complete)
- [ ] Gestion de playlist (création → ajout tracks → suppression)
- [ ] Navigation et routing
- [ ] Gestion d'erreurs (network errors, validation errors)

**Fichiers à créer/modifier:**
```
apps/web/e2e/
├── auth-flow.spec.ts      # Parcours auth complet
├── track-upload.spec.ts   # Upload par chunks
├── playlist-flow.spec.ts # CRUD playlists
├── navigation.spec.ts      # Routing et navigation
└── error-handling.spec.ts # Gestion d'erreurs
```

#### Tests Backend (Go)

**Tests d'intégration existants à compléter:**
- [ ] `tests/integration/auth_test.go` - Compléter tests refresh token avec cookies
- [ ] `tests/integration/track_test.go` - Tests upload par chunks complets
- [ ] `tests/integration/playlist_test.go` - Tests CRUD playlists

**Commandes pour exécuter les tests:**

```bash
# Tests unitaires frontend
cd apps/web
npm run test:unit

# Tests E2E frontend
npm run test:e2e

# Tests backend unitaires
cd veza-backend-api
go test ./internal/... -v

# Tests backend intégration
go test ./tests/integration/... -tags integration -v
```

### 1.3 Critères de Validation

- ✅ Couverture de code ≥ 80% pour les services critiques
- ✅ Tous les tests unitaires passent
- ✅ Tous les tests E2E passent
- ✅ Tests d'intégration backend passent
- ✅ CI/CD intégré avec exécution automatique des tests

---

## 2. ⚙️ Configuration : Variables d'Environnement

### 2.1 Objectif

Ajouter les variables d'environnement nécessaires pour gérer les cookies sécurisés, notamment `Secure=false` en développement local.

### 2.2 Variables à Ajouter

#### Backend (`veza-backend-api`)

**Fichier:** `veza-backend-api/.env.example` et `veza-backend-api/internal/config/config.go`

```env
# Cookie Security Settings
COOKIE_SECURE=false              # true en production, false en dev local
COOKIE_SAME_SITE=strict          # strict, lax, ou none
COOKIE_DOMAIN=                   # vide pour domaine actuel
COOKIE_HTTP_ONLY=true            # toujours true pour refresh_token
COOKIE_PATH=/                    # chemin du cookie
```

**Modifications dans `internal/config/config.go`:**

```go
type Config struct {
    // ... existing fields ...
    
    // Cookie settings
    CookieSecure   bool   `env:"COOKIE_SECURE" envDefault:"false"`
    CookieSameSite string `env:"COOKIE_SAME_SITE" envDefault:"strict"`
    CookieDomain   string `env:"COOKIE_DOMAIN" envDefault:""`
    CookieHttpOnly bool   `env:"COOKIE_HTTP_ONLY" envDefault:"true"`
    CookiePath     string `env:"COOKIE_PATH" envDefault:"/"`
}

// Helper method to get http.SameSite from string
func (c *Config) GetCookieSameSite() http.SameSite {
    switch c.CookieSameSite {
    case "lax":
        return http.SameSiteLaxMode
    case "none":
        return http.SameSiteNoneMode
    default:
        return http.SameSiteStrictMode
    }
}

// Helper to determine if cookie should be secure based on environment
func (c *Config) ShouldUseSecureCookies() bool {
    if c.CookieSecure {
        return true
    }
    // Auto-detect: secure in production, insecure in development
    return c.Environment == "production"
}
```

**Modifications dans `internal/handlers/auth.go`:**

```go
// Dans Login handler
cookieSecure := cfg.ShouldUseSecureCookies()
c.SetCookie(
    "refresh_token",
    tokens.RefreshToken,
    int(refreshTokenExpires.Seconds()),
    cfg.CookiePath,
    cfg.CookieDomain,
    cookieSecure,
    cfg.CookieHttpOnly,
)
c.SetSameSite(cfg.GetCookieSameSite())
```

#### Frontend (`apps/web`)

**Fichier:** `apps/web/.env.example` et `apps/web/.env.local`

```env
# API Configuration
VITE_API_URL=http://localhost:8080
VITE_API_BASE_PATH=/api/v1

# Environment
VITE_APP_ENV=development

# Cookie Configuration (pour référence, géré par backend)
# Les cookies sont gérés par le backend via Set-Cookie headers
# Le frontend doit simplement activer withCredentials dans les requêtes
```

**Vérification dans `src/services/apiClient.ts`:**

```typescript
// S'assurer que withCredentials est activé
const apiClient = axios.create({
  baseURL: import.meta.env.VITE_API_URL + import.meta.env.VITE_API_BASE_PATH,
  withCredentials: true, // ✅ Nécessaire pour les cookies httpOnly
  headers: {
    'Content-Type': 'application/json',
  },
});
```

#### Docker Compose

**Fichier:** `docker-compose.yml` (dev) et `docker-compose.prod.yml` (production)

```yaml
# docker-compose.yml (development)
services:
  backend-api:
    environment:
      - APP_ENV=development
      - COOKIE_SECURE=false          # ✅ false en dev local
      - COOKIE_SAME_SITE=lax         # lax pour permettre localhost
      - COOKIE_DOMAIN=
      - COOKIE_HTTP_ONLY=true
      - COOKIE_PATH=/

# docker-compose.prod.yml (production)
services:
  backend-api:
    environment:
      - APP_ENV=production
      - COOKIE_SECURE=true           # ✅ true en production
      - COOKIE_SAME_SITE=strict       # strict pour sécurité maximale
      - COOKIE_DOMAIN=.veza.app       # domaine de production
      - COOKIE_HTTP_ONLY=true
      - COOKIE_PATH=/
```

### 2.3 Fichiers à Modifier

- [ ] `veza-backend-api/.env.example` - Ajouter variables cookies
- [ ] `veza-backend-api/internal/config/config.go` - Ajouter struct CookieConfig
- [ ] `veza-backend-api/internal/handlers/auth.go` - Utiliser config cookies
- [ ] `apps/web/.env.example` - Documenter variables frontend
- [ ] `docker-compose.yml` - Ajouter variables dev
- [ ] `docker-compose.prod.yml` - Ajouter variables production
- [ ] `docs/ENV_CONFIG.md` - Mettre à jour documentation

### 2.4 Critères de Validation

- ✅ Variables d'environnement documentées dans `.env.example`
- ✅ Cookies `Secure=false` en développement local
- ✅ Cookies `Secure=true` en production
- ✅ Tests passent avec les nouvelles configurations
- ✅ Documentation mise à jour

---

## 3. 📚 Documentation : Mettre à Jour la Documentation API

### 3.1 État Actuel

- ✅ Swagger/OpenAPI configuré (`/swagger/index.html`)
- ✅ Documentation générée dans `veza-backend-api/docs/`
- ⚠️ Certains handlers manquent d'annotations Swagger
- ⚠️ Documentation des cookies httpOnly à ajouter
- ⚠️ Exemples de requêtes/réponses à compléter

### 3.2 Actions à Réaliser

#### Compléter les Annotations Swagger

**Handlers manquants d'annotations:**

- [ ] `internal/handlers/audit.go` - `SearchLogs`, `GetStats`, `GetSuspiciousActivity`
- [ ] `internal/handlers/webhook_handlers.go` - Tous les handlers webhooks
- [ ] `internal/handlers/comment_handler.go` - Handlers commentaires
- [ ] `internal/handlers/analytics_handler.go` - Handlers analytics

**Exemple d'annotation à ajouter:**

```go
// @Summary      User Login
// @Description  Authenticate user and return access token. Refresh token is set in httpOnly cookie.
// @Tags         Auth
// @Accept       json
// @Produce      json
// @Param        request body dto.LoginRequest true "Login Credentials"
// @Success      200  {object}  dto.LoginResponse "Access token returned in body, refresh token in httpOnly cookie"
// @Failure      400  {object}  handlers.APIResponse "Validation error"
// @Failure      401  {object}  handlers.APIResponse "Invalid credentials"
// @Router       /auth/login [post]
func (h *AuthHandler) Login(c *gin.Context) {
    // ...
}
```

#### Documenter les Cookies httpOnly

**Fichier:** `veza-backend-api/docs/API_DOCUMENTATION.md`

Ajouter section:

```markdown
## Authentication Cookies

### Refresh Token Cookie

After successful login or token refresh, a `refresh_token` cookie is set with the following properties:

- **Name:** `refresh_token`
- **HttpOnly:** `true` (not accessible via JavaScript)
- **Secure:** `true` in production, `false` in development
- **SameSite:** `strict` (prevents CSRF attacks)
- **Path:** `/`
- **Max-Age:** 30 days (or 90 days if "remember me" is selected)

**Important:** The refresh token is NOT returned in the JSON response body for security reasons. It is only available as an httpOnly cookie.

### Using Refresh Token

To refresh your access token, make a POST request to `/auth/refresh`:

```bash
curl -X POST http://localhost:8080/api/v1/auth/refresh \
  -H "Content-Type: application/json" \
  --cookie "refresh_token=<token>" \
  -b cookies.txt -c cookies.txt
```

The new access token will be returned in the response body, and a new refresh token cookie will be set.
```

#### Mettre à Jour les Exemples

- [ ] Ajouter exemples avec cookies dans `docs/API_DOCUMENTATION.md`
- [ ] Mettre à jour Postman collection (`tools/tests/http/postman_collection.json`)
- [ ] Ajouter exemples curl avec `--cookie` flag
- [ ] Documenter les changements de comportement (refresh token dans cookie vs body)

### 3.3 Fichiers à Modifier

- [ ] `veza-backend-api/internal/handlers/audit.go` - Ajouter annotations Swagger
- [ ] `veza-backend-api/internal/handlers/webhook_handlers.go` - Ajouter annotations
- [ ] `veza-backend-api/internal/handlers/comment_handler.go` - Ajouter annotations
- [ ] `veza-backend-api/docs/API_DOCUMENTATION.md` - Documenter cookies
- [ ] `veza-backend-api/docs/docs.go` - Régénérer après ajout annotations
- [ ] `tools/tests/http/postman_collection.json` - Mettre à jour collection

### 3.4 Génération de la Documentation

```bash
# Installer swag si nécessaire
go install github.com/swaggo/swag/cmd/swag@latest

# Générer la documentation Swagger
cd veza-backend-api
swag init -g cmd/api/main.go

# Vérifier la documentation
# Démarrer le serveur et visiter http://localhost:8080/swagger/index.html
```

### 3.5 Critères de Validation

- ✅ Tous les handlers ont des annotations Swagger complètes
- ✅ Documentation des cookies httpOnly ajoutée
- ✅ Exemples de requêtes mis à jour
- ✅ Swagger UI affiche tous les endpoints correctement
- ✅ Postman collection à jour

---

## 4. 🚢 Déploiement : Tester en Staging Avant Production

### 4.1 Environnements

- **Development:** `http://localhost:8080` (local)
- **Staging:** `https://staging-api.veza.app` (à configurer)
- **Production:** `https://api.veza.app` (production)

### 4.2 Checklist de Déploiement Staging

#### Pré-déploiement

- [ ] Tous les tests passent (unitaires + intégration + E2E)
- [ ] Code review effectué
- [ ] Variables d'environnement staging configurées
- [ ] Base de données staging migrée
- [ ] Documentation à jour

#### Configuration Staging

**Fichier:** `docker-compose.staging.yml` (à créer)

```yaml
version: '3.8'

services:
  backend-api:
    build:
      context: ./veza-backend-api
    environment:
      - APP_ENV=staging
      - DATABASE_URL=${STAGING_DATABASE_URL}
      - REDIS_URL=${STAGING_REDIS_URL}
      - JWT_SECRET=${STAGING_JWT_SECRET}
      - COOKIE_SECURE=true
      - COOKIE_SAME_SITE=strict
      - CORS_ALLOWED_ORIGINS=https://staging.veza.app
    ports:
      - "8080:8080"
    depends_on:
      - postgres
      - redis

  frontend:
    build:
      context: ./apps/web
    environment:
      - VITE_API_URL=https://staging-api.veza.app
      - VITE_APP_ENV=staging
    ports:
      - "3000:3000"
```

#### Tests de Validation Staging

**Tests fonctionnels:**
- [ ] Authentification complète (register → login → logout)
- [ ] Refresh token avec cookies httpOnly
- [ ] Upload de track par chunks
- [ ] CRUD playlists
- [ ] Navigation et routing
- [ ] Gestion d'erreurs

**Tests de performance:**
- [ ] Temps de réponse API < 500ms (p95)
- [ ] Upload de fichiers fonctionne correctement
- [ ] WebSocket chat fonctionne
- [ ] Pas de fuites mémoire

**Tests de sécurité:**
- [ ] Cookies httpOnly fonctionnent
- [ ] CORS configuré correctement
- [ ] HTTPS forcé
- [ ] Headers de sécurité présents

#### Script de Déploiement

**Fichier:** `scripts/deploy-staging.sh` (à créer)

```bash
#!/bin/bash
set -e

echo "🚀 Déploiement en staging..."

# Vérifier que les tests passent
echo "📋 Exécution des tests..."
npm run test:unit
npm run test:e2e
cd veza-backend-api && go test ./... && cd ..

# Build des images Docker
echo "🔨 Build des images..."
docker-compose -f docker-compose.staging.yml build

# Déploiement
echo "🚢 Déploiement..."
docker-compose -f docker-compose.staging.yml up -d

# Vérification santé
echo "🏥 Vérification santé..."
sleep 10
curl -f https://staging-api.veza.app/health || exit 1

echo "✅ Déploiement staging réussi!"
```

### 4.3 Rollback Plan

En cas de problème en staging:

```bash
# Rollback vers version précédente
docker-compose -f docker-compose.staging.yml down
git checkout <previous-commit>
docker-compose -f docker-compose.staging.yml up -d
```

### 4.4 Critères de Validation

- ✅ Application déployée en staging sans erreurs
- ✅ Tous les tests fonctionnels passent en staging
- ✅ Performance acceptable
- ✅ Sécurité validée
- ✅ Documentation de déploiement à jour

---

## 5. 📊 Monitoring : Surveiller les Performances Après Déploiement

### 5.1 Métriques à Surveiller

#### Métriques Application

- **Temps de réponse API:** p50, p95, p99
- **Taux d'erreur:** 4xx, 5xx
- **Throughput:** Requêtes/seconde
- **Taux de succès:** % de requêtes réussies

#### Métriques Infrastructure

- **CPU:** Utilisation moyenne et pics
- **Mémoire:** Utilisation et fuites
- **Disque:** Espace utilisé, IOPS
- **Réseau:** Bande passante, latence

#### Métriques Métier

- **Authentification:** Taux de login réussis, échecs
- **Upload:** Taux de succès upload, temps moyen
- **Playlists:** Créations, modifications
- **Utilisateurs actifs:** DAU, MAU

### 5.2 Outils de Monitoring

#### Backend (Go)

**Options:**
- Prometheus + Grafana (recommandé)
- Datadog
- New Relic
- Custom logging + ELK stack

**Implémentation Prometheus:**

```go
// Dans veza-backend-api/internal/middleware/metrics.go
import (
    "github.com/prometheus/client_golang/prometheus"
    "github.com/prometheus/client_golang/prometheus/promauto"
)

var (
    httpRequestsTotal = promauto.NewCounterVec(
        prometheus.CounterOpts{
            Name: "http_requests_total",
            Help: "Total number of HTTP requests",
        },
        []string{"method", "endpoint", "status"},
    )
    
    httpRequestDuration = promauto.NewHistogramVec(
        prometheus.HistogramOpts{
            Name: "http_request_duration_seconds",
            Help: "HTTP request duration in seconds",
        },
        []string{"method", "endpoint"},
    )
)

// Middleware pour collecter les métriques
func MetricsMiddleware() gin.HandlerFunc {
    return func(c *gin.Context) {
        start := time.Now()
        c.Next()
        duration := time.Since(start).Seconds()
        
        httpRequestsTotal.WithLabelValues(
            c.Request.Method,
            c.FullPath(),
            strconv.Itoa(c.Writer.Status()),
        ).Inc()
        
        httpRequestDuration.WithLabelValues(
            c.Request.Method,
            c.FullPath(),
        ).Observe(duration)
    }
}
```

#### Frontend (React)

**Options:**
- Sentry (erreurs)
- Google Analytics / Plausible (analytics)
- Custom metrics avec API

**Implémentation Sentry:**

```typescript
// Dans apps/web/src/lib/sentry.ts
import * as Sentry from "@sentry/react";

Sentry.init({
  dsn: import.meta.env.VITE_SENTRY_DSN,
  environment: import.meta.env.VITE_APP_ENV,
  tracesSampleRate: 1.0,
  beforeSend(event) {
    // Filtrer les erreurs en développement
    if (import.meta.env.DEV) {
      console.error(event);
      return null;
    }
    return event;
  },
});
```

### 5.3 Dashboards à Créer

#### Dashboard Principal (Grafana)

**Métriques à afficher:**
- Graphique: Temps de réponse API (p50, p95, p99)
- Graphique: Taux d'erreur (4xx, 5xx)
- Graphique: Throughput (req/s)
- Graphique: CPU et mémoire
- Tableau: Top endpoints par latence
- Alerte: Taux d'erreur > 5%

#### Dashboard Métier

- Graphique: Utilisateurs actifs (DAU, MAU)
- Graphique: Uploads par jour
- Graphique: Taux de succès authentification
- Graphique: Créations de playlists

### 5.4 Alertes à Configurer

**Alertes critiques:**
- [ ] Taux d'erreur 5xx > 5% pendant 5 minutes
- [ ] Temps de réponse p95 > 1s pendant 10 minutes
- [ ] CPU > 80% pendant 10 minutes
- [ ] Mémoire > 90% pendant 5 minutes
- [ ] Service down (health check échoue)

**Alertes warning:**
- [ ] Taux d'erreur 4xx > 10% pendant 15 minutes
- [ ] Temps de réponse p95 > 500ms pendant 15 minutes
- [ ] Disque > 80% utilisé

### 5.5 Fichiers à Créer/Modifier

- [ ] `veza-backend-api/internal/middleware/metrics.go` - Middleware Prometheus
- [ ] `veza-backend-api/cmd/api/main.go` - Exposer endpoint `/metrics`
- [ ] `docker-compose.prod.yml` - Ajouter Prometheus et Grafana
- [ ] `apps/web/src/lib/sentry.ts` - Configuration Sentry
- [ ] `grafana/dashboards/main.json` - Dashboard principal
- [ ] `grafana/dashboards/business.json` - Dashboard métier
- [ ] `prometheus/alerts.yml` - Règles d'alertes

### 5.6 Critères de Validation

- ✅ Métriques collectées et exposées
- ✅ Dashboards créés et configurés
- ✅ Alertes configurées et testées
- ✅ Monitoring actif en production
- ✅ Documentation du monitoring à jour

---

## 📅 Planning Suggéré

### Semaine 1: Tests et Configuration
- **Jour 1-2:** Tests unitaires services critiques
- **Jour 3:** Configuration variables d'environnement
- **Jour 4-5:** Tests d'intégration et E2E

### Semaine 2: Documentation et Staging
- **Jour 1-2:** Compléter documentation API
- **Jour 3:** Configuration staging
- **Jour 4-5:** Tests et validation staging

### Semaine 3: Monitoring et Production
- **Jour 1-2:** Configuration monitoring
- **Jour 3:** Dashboards et alertes
- **Jour 4-5:** Déploiement production et surveillance

---

## ✅ Checklist Globale

### Tests
- [ ] Tests unitaires services critiques créés
- [ ] Tests d'intégration complets
- [ ] Tests E2E Playwright fonctionnels
- [ ] Couverture ≥ 80%

### Configuration
- [ ] Variables d'environnement documentées
- [ ] Cookies Secure=false en dev, true en prod
- [ ] Configuration staging prête
- [ ] Configuration production prête

### Documentation
- [ ] Annotations Swagger complètes
- [ ] Documentation cookies httpOnly
- [ ] Exemples de requêtes mis à jour
- [ ] Guide de déploiement à jour

### Déploiement
- [ ] Staging déployé et validé
- [ ] Tests fonctionnels staging passent
- [ ] Performance staging acceptable
- [ ] Production prête pour déploiement

### Monitoring
- [ ] Métriques collectées
- [ ] Dashboards configurés
- [ ] Alertes configurées
- [ ] Monitoring actif

---

## 📝 Notes

- Ce document doit être mis à jour au fur et à mesure de l'avancement
- Les priorités peuvent être ajustées selon les besoins
- Chaque section peut être traitée en parallèle par différentes équipes

---

**Dernière mise à jour:** 2025-01-27  
**Prochaine révision:** Après déploiement staging