veza/docs/archive/frontend-sessions-2026/COMPATIBILITY_CHECK_PROMPT.md

PROMPT DE VÉRIFICATION DE COMPATIBILITÉ FRONTEND/BACKEND

Objectif

Vérifier que le frontend React (TypeScript) est complètement et entièrement compatible avec le backend Go (API REST).

---

1. VÉRIFICATION DES ENDPOINTS API

Tâche

Comparer chaque endpoint utilisé dans le frontend avec les routes enregistrées dans le backend.

Points à vérifier :

• Correspondance des chemins : Les endpoints frontend correspondent exactement aux routes backend (y compris préfixe /api/v1)
• Méthodes HTTP : GET, POST, PUT, DELETE, PATCH correspondent
• Paramètres de route : Les :id, :username, etc. sont correctement formatés
• Query parameters : ?page=1&limit=20 correspondent aux attentes backend
• Endpoints manquants : Tous les endpoints backend sont accessibles depuis le frontend
• Endpoints obsolètes : Aucun endpoint frontend n'appelle des routes backend supprimées

Fichiers à examiner :

• Frontend : src/config/constants.ts (API_ENDPOINTS), src/services/api/*.ts, src/features/*/api/*.ts
• Backend : Routes enregistrées dans les logs de démarrage (voir sortie make run)

Exemple de vérification :

// Frontend
POST /api/v1/auth/login

// Backend (vérifier dans les logs)
[GIN-debug] POST   /api/v1/auth/login --> handler

---

2. VÉRIFICATION DES TYPES DE DONNÉES

Tâche

Vérifier que les interfaces TypeScript correspondent aux structures de données retournées par le backend.

Points à vérifier :

• User : id (string/UUID), username, email, role, created_at, etc.
• Track : id, title, artist_id, duration, file_path, etc.
• Conversation : id, name, type, participants, last_message, etc.
• Message : id, content, sender_id, message_type, created_at, etc.
• Session : id, user_id, token, expires_at, ip_address, etc.
• Types de champs : string vs number, Date vs string (ISO), boolean vs number
• Champs optionnels : Les ? dans TypeScript correspondent aux NULL/omitempty du backend
• Champs manquants : Tous les champs backend sont présents dans les types frontend
• Champs supplémentaires : Pas de champs frontend qui n'existent pas côté backend

Fichiers à examiner :

• Frontend : src/types/api.ts, src/types/index.ts, src/features/*/types/*.ts
• Backend : Modèles Go dans internal/models/*.go ou internal/core/*/models.go

Exemple de vérification :

// Frontend
interface User {
  id: string;
  username: string;
  email: string;
  role: 'user' | 'admin';
  created_at: string; // ISO date string
}

// Backend (vérifier)
type User struct {
  ID        uuid.UUID `json:"id"`
  Username  string    `json:"username"`
  Email     string    `json:"email"`
  Role      string    `json:"role"`
  CreatedAt time.Time `json:"created_at"`
}

---

3. VÉRIFICATION DES FORMATS DE REQUÊTES

Tâche

Vérifier que les payloads envoyés par le frontend correspondent aux structures attendues par le backend.

Points à vérifier :

• Login : { email, password, remember_me? } correspond au handler backend
• Register : { email, password, username } + validation frontend = validation backend
• Update Profile : Champs optionnels correctement gérés
• Upload Track : Format FormData ou multipart/form-data correct
• Pagination : { page, limit } ou { cursor } selon backend
• Filtres/Recherche : Query params formatés correctement
• Noms de champs : snake_case vs camelCase (backend Go utilise souvent snake_case)

Fichiers à examiner :

• Frontend : src/features/*/api/*.ts, src/services/api.ts
• Backend : Handlers dans internal/handlers/*.go, internal/api/*.go

Exemple de vérification :

// Frontend
POST /api/v1/auth/login
Body: { email: "user@example.com", password: "pass123" }

// Backend (vérifier)
type LoginRequest struct {
  Email    string `json:"email" binding:"required,email"`
  Password string `json:"password" binding:"required"`
}

---

4. VÉRIFICATION DES FORMATS DE RÉPONSES

Tâche

Vérifier que le frontend gère correctement le format de réponse standardisé du backend.

Points à vérifier :

• Format wrapper : { success: boolean, data: T, error?: ApiError }
• Unwrapping : Le client API (apiClient) unwrap correctement response.data.data
• Réponses directes : Certains endpoints retournent directement data sans wrapper
• Codes HTTP : 200/201 pour succès, 400/401/403/404/409/422/429/500 pour erreurs
• Pagination : Format { items: T[], pagination: {...} } ou { data: T[], meta: {...} }
• Listes vides : [] vs null vs absence de champ

Fichiers à examiner :

• Frontend : src/services/api/client.ts (interceptors), src/utils/apiErrorHandler.ts
• Backend : Format de réponse dans internal/api/response.go ou middleware

Exemple de vérification :

// Frontend attend
{
  success: true,
  data: { id: "123", username: "user" },
  error: null
}

// Backend retourne (vérifier)
Response{Success: true, Data: user, Error: nil}

---

5. VÉRIFICATION DE LA GESTION DES ERREURS

Tâche

Vérifier que le frontend gère tous les codes d'erreur et formats d'erreur du backend.

Points à vérifier :

• Format ApiError : { code: number, message: string, details?: [...], request_id?: string, timestamp: string }
• Codes d'erreur : 1000-1999 (auth), 2000-2999 (validation), 3000-3999 (business), etc.
• Parsing d'erreurs : parseApiError() gère tous les cas (AxiosError, ApiError, Error)
• Erreurs de validation : error.details[] avec { field, message } affichés correctement
• Erreurs réseau : Timeout, connexion refusée, CORS
• Erreurs 401 : Refresh automatique du token, redirection si échec
• Erreurs 403 : Affichage message "Accès interdit"
• Erreurs 409 : Gestion conflits (username/email déjà utilisé)
• Erreurs 429 : Rate limiting avec retry après délai
• Erreurs 500 : Logger request_id pour support

Fichiers à examiner :

• Frontend : src/utils/apiErrorHandler.ts, src/services/api/client.ts (interceptors)
• Backend : Codes d'erreur dans internal/errors/*.go ou constants

Exemple de vérification :

// Frontend gère
{
  code: 1000,
  message: "Invalid credentials",
  request_id: "req-123",
  timestamp: "2025-01-27T10:00:00Z"
}

// Backend retourne (vérifier)
ErrorCode: 1000, Message: "Invalid credentials", RequestID: "req-123"

---

6. VÉRIFICATION DE L'AUTHENTIFICATION

Tâche

Vérifier que le flux d'authentification frontend correspond au backend.

Points à vérifier :

• Header Authorization : Format Bearer <token> correct
• Token storage : localStorage vs sessionStorage vs cookies (selon backend)
• Refresh token : Endpoint /api/v1/auth/refresh avec { refresh_token: string }
• Token expiration : Gestion automatique du refresh avant expiration
• Logout : Appel /api/v1/auth/logout avec refresh_token, nettoyage local
• GetMe : Endpoint /api/v1/auth/me retourne le user actuel
• Interceptors : Ajout automatique du token sur toutes les requêtes authentifiées
• 401 handling : Refresh automatique + retry, redirection si refresh échoue
• JWT claims : Le frontend peut décoder/utiliser les claims si nécessaire

Fichiers à examiner :

• Frontend : src/services/api/client.ts, src/services/tokenRefresh.ts, src/services/tokenStorage.ts
• Backend : Handlers auth dans internal/api/auth.go ou internal/handlers/auth*.go

Exemple de vérification :

// Frontend
headers: { Authorization: `Bearer ${token}` }

// Backend (vérifier)
c.GetHeader("Authorization") // "Bearer <token>"

---

7. VÉRIFICATION DES SCHÉMAS DE VALIDATION

Tâche

Vérifier que les validations frontend (Zod) correspondent aux validations backend.

Points à vérifier :

• Email : Format regex identique, validation côté client = validation backend
• Password : Longueur min/max, complexité (majuscule, chiffre, caractère spécial)
• Username : Longueur min/max, caractères autorisés (alphanumérique, underscore, tiret)
• File uploads : Taille max, types MIME autorisés
• Messages : Longueur max du contenu
• Dates : Format ISO 8601 (YYYY-MM-DD ou YYYY-MM-DDTHH:mm:ssZ)
• UUIDs : Format validation si utilisé
• Nombres : Min/max, entiers vs décimaux

Fichiers à examiner :

• Frontend : src/schemas/validation.ts, src/features/*/schemas/*.ts
• Backend : Validations dans les handlers Go (tags binding, validate)

Exemple de vérification :

// Frontend (Zod)
z.string().email().min(3).max(100)

// Backend (vérifier)
Email string `json:"email" binding:"required,email" validate:"min=3,max=100"`

---

8. VÉRIFICATION DES CODES HTTP

Tâche

Vérifier que le frontend gère correctement tous les codes HTTP retournés par le backend.

Points à vérifier :

• 200 OK : Succès, traiter data
• 201 Created : Ressource créée, traiter data (peut contenir Location header)
• 204 No Content : Succès sans body (DELETE, UPDATE parfois)
• 400 Bad Request : Erreur de validation, afficher error.details
• 401 Unauthorized : Token manquant/invalide, refresh ou rediriger login
• 403 Forbidden : Permissions insuffisantes, afficher message
• 404 Not Found : Ressource introuvable, afficher message générique
• 409 Conflict : Conflit (username/email existant), afficher error.message
• 422 Unprocessable Entity : Validation échouée, afficher error.details
• 429 Too Many Requests : Rate limit, afficher message + retry après
• 500 Internal Server Error : Erreur serveur, logger request_id, message générique
• 502/503 : Service indisponible, message + retry

Fichiers à examiner :

• Frontend : src/services/api/client.ts, src/utils/apiErrorHandler.ts
• Backend : Codes HTTP dans les handlers (Gin c.JSON(status, ...))

---

9. VÉRIFICATION DES HEADERS

Tâche

Vérifier que les headers requis sont correctement envoyés et gérés.

Points à vérifier :

• Content-Type : application/json pour les requêtes JSON
• Authorization : Bearer <token> pour les routes protégées
• Accept : application/json si backend le requiert
• X-Requested-With : Si backend vérifie CSRF
• Custom headers : Headers spécifiques (API version, client ID, etc.)
• CORS : Headers CORS gérés correctement (backend autorise les origines frontend)

Fichiers à examiner :

• Frontend : src/services/api/client.ts (headers par défaut)
• Backend : Middleware CORS dans internal/api/*.go ou internal/middleware/*.go

---

10. VÉRIFICATION DE LA PAGINATION

Tâche

Vérifier que le format de pagination frontend correspond au backend.

Points à vérifier :

• Format pagination : { page, limit, total, total_pages, has_next, has_prev } ou cursor-based
• Paramètres query : ?page=1&limit=20 vs ?cursor=abc&limit=20
• Valeurs par défaut : page=1, limit=20 (ou valeurs backend)
• Limites max : Frontend respecte limit <= 100 (ou limite backend)
• Navigation : Boutons précédent/suivant utilisent correctement has_prev/has_next
• Liste vide : items: [] ou data: [] selon format backend

Fichiers à examiner :

• Frontend : src/types/api.ts (PaginationData), composants de liste
• Backend : Format pagination dans les handlers de liste

---

11. VÉRIFICATION DES UPLOADS

Tâche

Vérifier que les uploads de fichiers sont compatibles avec le backend.

Points à vérifier :

• Format : multipart/form-data ou FormData selon backend
• Champs : Noms de champs (file, cover_art, title, etc.) correspondent
• Taille max : Frontend valide avant upload (10MB image, 100MB audio, etc.)
• Types MIME : Validation frontend = validation backend
• Progress : Endpoint /api/v1/uploads/:id/progress si disponible
• Chunked upload : Si backend supporte, frontend utilise /api/v1/tracks/chunk
• Response : Format de réponse après upload (file_id, file_url, etc.)

Fichiers à examiner :

• Frontend : src/services/api.ts (upload methods), src/features/tracks/services/*.ts
• Backend : Handlers upload dans internal/api/upload.go ou internal/core/track/*.go

---

12. VÉRIFICATION DES WEBSOCKETS

Tâche

Vérifier que la connexion WebSocket et les messages sont compatibles.

Points à vérifier :

• URL : ws://localhost:8081/ws ou wss:// en production
• Authentification : Token JWT dans query param ?token=... ou header
• Format messages : { type: string, data: any, timestamp: string }
• Types de messages : message, typing, read_receipt, user_joined, etc.
• Reconnection : Logique de reconnexion automatique
• Heartbeat : Ping/pong si backend le requiert
• Error handling : Gestion des erreurs WebSocket

Fichiers à examiner :

• Frontend : src/services/websocket.ts, src/features/chat/hooks/useChat.ts
• Backend : WebSocket handler dans chat server Rust (hors scope backend Go)

---

13. VÉRIFICATION DES VARIABLES D'ENVIRONNEMENT

Tâche

Vérifier que les URLs et configurations correspondent.

Points à vérifier :

• API URL : VITE_API_URL=http://localhost:8080/api/v1 (avec /api/v1)
• WS URL : VITE_WS_URL=ws://localhost:8081/ws
• Stream URL : VITE_STREAM_URL=ws://localhost:8082/stream
• Timeout : Timeout frontend (10s) compatible avec timeout backend
• CORS origins : Backend autorise les origines frontend (localhost:5173, localhost:3000)

Fichiers à examiner :

• Frontend : src/config/env.ts, .env.local
• Backend : Configuration CORS dans internal/config/*.go

---

14. VÉRIFICATION DES TESTS E2E

Tâche

Vérifier que les tests E2E couvrent tous les endpoints critiques.

Points à vérifier :

• Auth flow : Login, register, logout, refresh
• CRUD operations : Create, Read, Update, Delete pour chaque ressource
• Error cases : 400, 401, 403, 404, 409, 422, 429, 500
• Edge cases : Pagination limites, listes vides, champs optionnels

Fichiers à examiner :

• Frontend : e2e/*.spec.ts

---

15. CHECKLIST FINALE

Avant de considérer la compatibilité complète :

• Tous les endpoints backend sont testés depuis le frontend
• Tous les types TypeScript correspondent aux modèles backend
• Toutes les erreurs backend sont gérées et affichées correctement
• L'authentification fonctionne (login, refresh, logout)
• Les uploads fonctionnent (fichiers, images, audio)
• La pagination fonctionne sur toutes les listes
• Les WebSockets se connectent et échangent des messages
• Les validations frontend = validations backend
• Les codes HTTP sont tous gérés
• Les tests E2E passent

---

MÉTHODOLOGIE DE VÉRIFICATION

Étape 1 : Audit statique

1. Lire tous les fichiers API frontend (src/services/api/*.ts, src/features/*/api/*.ts)
2. Extraire tous les endpoints, types, formats de requêtes/réponses
3. Comparer avec la documentation backend ou les routes enregistrées

Étape 2 : Audit dynamique

1. Démarrer le backend (make run dans veza-backend-api)
2. Tester chaque endpoint avec curl ou Postman
3. Comparer les réponses réelles avec ce que le frontend attend

Étape 3 : Tests d'intégration

1. Démarrer frontend + backend
2. Exécuter les tests E2E (npm run test:e2e)
3. Tester manuellement les flows critiques (auth, upload, chat)

Étape 4 : Vérification des logs

1. Examiner les logs backend pour les erreurs 400/401/500
2. Examiner les logs frontend (console) pour les erreurs de parsing
3. Identifier les incompatibilités

---

OUTILS RECOMMANDÉS

• Postman/Insomnia : Tester les endpoints backend directement
• Browser DevTools : Network tab pour voir les requêtes/réponses réelles
• TypeScript compiler : Vérifier les types (npm run typecheck)
• Playwright : Tests E2E automatisés
• Diff tools : Comparer types frontend vs modèles backend

---

RAPPORT DE COMPATIBILITÉ

Après vérification, créer un rapport avec :

1. Endpoints vérifiés : Liste de tous les endpoints testés
2. Incompatibilités trouvées : Détails de chaque problème
3. Recommandations : Actions à prendre pour corriger
4. Couverture : % d'endpoints/testés, % de types alignés

---

EXEMPLE D'UTILISATION

# 1. Démarrer le backend
cd veza-backend-api && make run

# 2. Dans un autre terminal, vérifier les routes
curl http://localhost:8080/api/v1/health

# 3. Tester un endpoint avec auth
curl -X POST http://localhost:8080/api/v1/auth/login \
  -H "Content-Type: application/json" \
  -d '{"email":"test@example.com","password":"test123"}'

# 4. Comparer la réponse avec ce que le frontend attend
# (voir src/features/auth/api/authApi.ts)

---

Note : Ce prompt doit être utilisé avec le backend en cours d'exécution pour une vérification complète. Les routes backend sont visibles dans les logs de démarrage (make run).