senke/veza

senke 99d5f1b61e chore: resolve property mismatches and type conflicts for snake_case alignment

2026-01-07 11:15:48 +01:00

21 KiB

Raw Blame History

🚀 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:

# 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

# 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:

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:

// 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

# 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:

// 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)

# 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
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:

// @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:

## 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)

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)

#!/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:

# 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:

// 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)