senke/veza
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions
veza/apps/web/COMPATIBILITY_CHECK_PROMPT.md

17 KiB
Raw Blame History

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