veza/apps/web/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 :
```typescript
// 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 :
```typescript
// 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 :
```typescript
// 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 :
```typescript
// 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 :
```typescript
// 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 :
```typescript
// 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 :
```typescript
// 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

```bash
# 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`).