420 lines
No EOL
11 KiB
Markdown
420 lines
No EOL
11 KiB
Markdown
# Chat Conversation
|
||
|
||
Note: _This is purely the output of the chat conversation and does not contain any raw data, codebase snippets, etc. used to generate the output._
|
||
|
||
### User Input
|
||
|
||
# 🚀 **PHASE 5 — API CONTRACT FINALIZATION & FRONTEND-INTEGRATION HARDENING**
|
||
|
||
Tu démarres immédiatement à partir de l’état final du **API Stabilization Report** :
|
||
|
||
|
||
**Résumé de ce que Phase 4 a accompli :**
|
||
|
||
* Tous les handlers critiques stabilisés
|
||
* Stratégie *full sentinel errors* en place
|
||
* Erreurs cohérentes (400/401/403/404) et testées
|
||
* API Flow test E2E (`TestAPIFlow_UserJourney`) validé
|
||
* Plus aucun “Blind 404” ou “500 silencieux”
|
||
* Plus aucun string literal fragile dans les handlers
|
||
* Services alignés sur une table d’erreurs unifiée
|
||
|
||
L’API est **stable**, **prédictible**, **documentable**, et **consommable** par le futur frontend.
|
||
|
||
---
|
||
|
||
# 🎯 OBJECTIF GLOBAL PHASE 5
|
||
|
||
Préparer **l’intégration frontend** et verrouiller **le contrat API final**, en garantissant :
|
||
|
||
1. **Un schéma API explicite et documenté**
|
||
2. **Des structures de réponse JSON uniformes**
|
||
3. **Des erreurs typées & documentées**
|
||
4. **Un comportement stable et entièrement prévisible par le frontend**
|
||
5. **Une suite de tests E2E complète couvrant tous les flux utilisateurs**
|
||
6. **Un fichier OpenAPI (Swagger) 100% conforme avec le backend réel**
|
||
7. **Un rapport final API-Ready à destination du futur frontend React/Vite**
|
||
|
||
Phase 5, c’est **le gel du contrat API**.
|
||
|
||
---
|
||
|
||
# ✔️ **1. MISSION**
|
||
|
||
Tu dois exécuter un audit complet orienté “Client / Frontend”, et produire :
|
||
|
||
## A. Analyse et normalisation des réponses JSON
|
||
|
||
Pour chaque handler :
|
||
|
||
* Format uniforme des réponses success
|
||
* Format uniforme des erreurs
|
||
* Structure commune :
|
||
|
||
```json
|
||
{
|
||
"success": true/false,
|
||
"data": {...},
|
||
"error": { "code": "ErrXxx", "message": "..." }
|
||
}
|
||
```
|
||
|
||
* Vérifier :
|
||
|
||
* champs sérialisés cohérents (`track_id` vs `trackId`)
|
||
* absence de champs non utilisés
|
||
* présence systématique de `json` tags
|
||
* logique `omitempty` là où nécessaire
|
||
|
||
## B. Documentation contractuelle
|
||
|
||
1. Générer ou mettre à jour une **spec OpenAPI 3.1** couvrant :
|
||
|
||
* Playlist CRUD
|
||
* Playlist tracks
|
||
* Bitrate adaptation
|
||
* Chat token
|
||
* Comments & replies
|
||
* Rooms
|
||
* User auth (register/login/refresh)
|
||
* Password reset
|
||
|
||
2. Ajouter des exemples de réponses JSON :
|
||
|
||
* Success
|
||
* Validation error
|
||
* Unauthorized
|
||
* Forbidden
|
||
* NotFound
|
||
|
||
3. Ajouter la section **Error Codes Reference**, basée sur `internal/services/errors.go`.
|
||
|
||
---
|
||
|
||
## C. Stabilisation des handlers et services pour compatibilité Frontend
|
||
|
||
Tu dois vérifier, corriger ou améliorer :
|
||
|
||
* cohérence des noms de champs JSON
|
||
* cohérence des structures de request bodies
|
||
* cohérence des réponses dans tout le backend
|
||
* présence de validations manquantes (ex: valeurs négatives, mauvaise forme UUID)
|
||
* comportement post-refactor encore ambigu
|
||
|
||
Objectif final : **Zéro surprise côté frontend.**
|
||
|
||
---
|
||
|
||
## D. Finalisation des micro-E2E tests (API acceptance tests)
|
||
|
||
Créer un petit répertoire :
|
||
|
||
```
|
||
tests/api_acceptance/
|
||
```
|
||
|
||
Et ajouter les tests suivants :
|
||
|
||
1. **User Journey Full Flow**
|
||
2. **Playlist Full Flow**
|
||
3. **Track Upload → Adapt Bitrate → Comment → Reply → Unauthorized Delete**
|
||
4. **Chat Token Flow**
|
||
5. **Password Reset Full Flow**
|
||
6. **Room Creation → Join → Fail Join Without Token**
|
||
|
||
Règles :
|
||
|
||
* Pas de DB externe — utiliser SQLite in-memory ou mocks
|
||
* Tests rapides (<150ms)
|
||
* Tests stables et déterministes
|
||
* Les tests doivent utiliser **strict JSON schema validation**
|
||
|
||
---
|
||
|
||
## E. Mise à jour du reporting
|
||
|
||
Mettre à jour :
|
||
|
||
1. `API_STABILITY_REPORT.md`
|
||
2. `POST_REMEDIATION_REPORT.md` (section Phase 5 finale)
|
||
3. `CHANGELOG.md`
|
||
4. Créer :
|
||
|
||
```
|
||
API_CONTRACT_FINAL.md
|
||
API_OPENAPI_SPEC.yaml
|
||
API_FRONTEND_GUIDE.md
|
||
```
|
||
|
||
---
|
||
|
||
# ✔️ **2. MÉTHODOLOGIE**
|
||
|
||
### Étape 1 — Scan du code actuel
|
||
|
||
Scanner :
|
||
|
||
```
|
||
internal/handlers/
|
||
internal/services/
|
||
internal/models/
|
||
internal/errors/
|
||
```
|
||
|
||
Identifier les incohérences encore possibles, ex :
|
||
|
||
* `trackId` vs `track_id`
|
||
* `userId` vs `user_id`
|
||
* `err := fmt.Errorf(...)` non remplacé par un sentinel
|
||
* validations absentes dans certains requests
|
||
* erreurs non mappées (`ErrForbidden` → 500)
|
||
* handlers retournant des `[]map[string]any` au lieu de structs
|
||
|
||
Produire une liste d’actions P1/P2.
|
||
|
||
---
|
||
|
||
### Étape 2 — Correction ciblée
|
||
|
||
Un commit = un problème.
|
||
|
||
Exemples de commits attendus :
|
||
|
||
```
|
||
fix(api-json): normalize field names across playlist & track responses
|
||
fix(api-errors): use unified error envelope for all handlers
|
||
feat(api-docs): add OpenAPI 3.1 full specification
|
||
test(api-e2e): add Playlist Full Flow acceptance test
|
||
fix(api-validation): enforce UUID format for ChatTokenRequest
|
||
```
|
||
|
||
---
|
||
|
||
### Étape 3 — Génération du schéma OpenAPI
|
||
|
||
Tu dois auto-générer le fichier **OpenAPI** depuis :
|
||
|
||
* les structs Go
|
||
* les handlers
|
||
* les exemples
|
||
* les erreurs
|
||
|
||
Puis le corriger manuellement pour exactitude totale.
|
||
|
||
---
|
||
|
||
### Étape 4 — Tests E2E
|
||
|
||
Créer des tests courts et fiables :
|
||
|
||
```
|
||
go test ./tests/api_acceptance -run TestPlaylistFlow
|
||
```
|
||
|
||
---
|
||
|
||
### Étape 5 — Rapport final
|
||
|
||
Écrire :
|
||
|
||
* **API_CONTRACT_FINAL.md** : état final du contrat API
|
||
* **API_FRONTEND_GUIDE.md** : comment consommer correctement chaque endpoint
|
||
* Mise à jour du **API_STABILITY_REPORT.md**
|
||
|
||
---
|
||
|
||
# ✔️ **3. LIVRABLES ATTENDUS**
|
||
|
||
À la fin de la PHASE 5, tu dois avoir :
|
||
|
||
### 📌 1. Backend API complètement normalisé
|
||
|
||
### 📌 2. OpenAPI 3.1 complet
|
||
|
||
### 📌 3. Tests E2E API stables au-dessus de SQLite
|
||
|
||
### 📌 4. Documentation API prête pour le frontend
|
||
|
||
### 📌 5. API contract congelé avant intégration React/Vite
|
||
|
||
---
|
||
|
||
# ✔️ **4. DÉMARRAGE**
|
||
|
||
Commence maintenant par :
|
||
|
||
1. Analyser tous les handlers pour extraire :
|
||
|
||
* JSON inconsistencies
|
||
* error mapping gaps
|
||
* validation missing
|
||
* wrong HTTP codes
|
||
2. Proposer une liste P1 / P2 de corrections
|
||
3. Implémenter la première avec un commit propre
|
||
|
||
---
|
||
|
||
# 🚀 **PHASE 5 STARTS NOW**
|
||
|
||
Continue.
|
||
|
||
|
||
*Edited relevant file*
|
||
|
||
*Edited relevant file*
|
||
|
||
*Listed directory [handlers](file:///home/senke/Documents/veza/veza-backend-api/internal/handlers) *
|
||
|
||
*Listed directory [models](file:///home/senke/Documents/veza/veza-backend-api/internal/models) *
|
||
|
||
*Viewed [playlist_handler.go](file:///home/senke/Documents/veza/veza-backend-api/internal/handlers/playlist_handler.go) *
|
||
|
||
*Viewed [auth.go](file:///home/senke/Documents/veza/veza-backend-api/internal/handlers/auth.go) *
|
||
|
||
*Viewed [room_handler.go](file:///home/senke/Documents/veza/veza-backend-api/internal/handlers/room_handler.go) *
|
||
|
||
*Viewed [error_response.go](file:///home/senke/Documents/veza/veza-backend-api/internal/handlers/error_response.go) *
|
||
|
||
*Viewed [responses.go](file:///home/senke/Documents/veza/veza-backend-api/internal/models/responses.go) *
|
||
|
||
*Listed directory [dto](file:///home/senke/Documents/veza/veza-backend-api/internal/dto) *
|
||
|
||
*Viewed [login_request.go](file:///home/senke/Documents/veza/veza-backend-api/internal/dto/login_request.go) *
|
||
|
||
*Viewed [register_request.go](file:///home/senke/Documents/veza/veza-backend-api/internal/dto/register_request.go) *
|
||
|
||
*Edited relevant file*
|
||
|
||
### User Input
|
||
|
||
This is a system-generated message that is sent due to the user's review policy. Proceed with the decision that you think is the most optimal here.
|
||
|
||
*Edited relevant file*
|
||
|
||
*Edited relevant file*
|
||
|
||
*Edited relevant file*
|
||
|
||
*User accepted the command `go build ./internal/handlers/...`*
|
||
|
||
*Edited relevant file*
|
||
|
||
*Viewed [playlist_handler.go](file:///home/senke/Documents/veza/veza-backend-api/internal/handlers/playlist_handler.go) *
|
||
|
||
*Viewed [auth.go](file:///home/senke/Documents/veza/veza-backend-api/internal/handlers/auth.go) *
|
||
|
||
*Viewed [room_handler.go](file:///home/senke/Documents/veza/veza-backend-api/internal/handlers/room_handler.go) *
|
||
|
||
*Edited relevant file*
|
||
|
||
*Edited relevant file*
|
||
|
||
*Edited relevant file*
|
||
|
||
*Grep searched codebase*
|
||
|
||
*Read resource from file:///home/senke/Documents/veza/veza-backend-api/internal/handlers/common.go *
|
||
|
||
*Viewed [common.go](file:///home/senke/Documents/veza/veza-backend-api/internal/handlers/common.go) *
|
||
|
||
*Viewed [marketplace.go](file:///home/senke/Documents/veza/veza-backend-api/internal/handlers/marketplace.go) *
|
||
|
||
*Viewed [settings_handler.go](file:///home/senke/Documents/veza/veza-backend-api/internal/handlers/settings_handler.go) *
|
||
|
||
*Viewed [config_reload.go](file:///home/senke/Documents/veza/veza-backend-api/internal/handlers/config_reload.go) *
|
||
|
||
*Viewed [health.go](file:///home/senke/Documents/veza/veza-backend-api/internal/handlers/health.go) *
|
||
|
||
*Edited relevant file*
|
||
|
||
*Edited relevant file*
|
||
|
||
*Edited relevant file*
|
||
|
||
*Edited relevant file*
|
||
|
||
*Viewed [notification_handlers.go](file:///home/senke/Documents/veza/veza-backend-api/internal/handlers/notification_handlers.go) *
|
||
|
||
*Viewed [oauth_handlers.go](file:///home/senke/Documents/veza/veza-backend-api/internal/handlers/oauth_handlers.go) *
|
||
|
||
*Viewed [search_handlers.go](file:///home/senke/Documents/veza/veza-backend-api/internal/handlers/search_handlers.go) *
|
||
|
||
*Viewed [password_reset_handler.go](file:///home/senke/Documents/veza/veza-backend-api/internal/handlers/password_reset_handler.go) *
|
||
|
||
*Edited relevant file*
|
||
|
||
*Edited relevant file*
|
||
|
||
*Edited relevant file*
|
||
|
||
*Edited relevant file*
|
||
|
||
*Viewed [social.go](file:///home/senke/Documents/veza/veza-backend-api/internal/handlers/social.go) *
|
||
|
||
*Viewed [upload.go](file:///home/senke/Documents/veza/veza-backend-api/internal/handlers/upload.go) *
|
||
|
||
*Viewed [analytics_handler.go](file:///home/senke/Documents/veza/veza-backend-api/internal/handlers/analytics_handler.go) *
|
||
|
||
*Viewed [session.go](file:///home/senke/Documents/veza/veza-backend-api/internal/handlers/session.go) *
|
||
|
||
*Viewed [chat_handler.go](file:///home/senke/Documents/veza/veza-backend-api/internal/handlers/chat_handler.go) *
|
||
|
||
*Viewed [status_handler.go](file:///home/senke/Documents/veza/veza-backend-api/internal/handlers/status_handler.go) *
|
||
|
||
*Edited relevant file*
|
||
|
||
*Edited relevant file*
|
||
|
||
*Edited relevant file*
|
||
|
||
*Edited relevant file*
|
||
|
||
*Edited relevant file*
|
||
|
||
*Edited relevant file*
|
||
|
||
*Viewed [webhook_handlers.go](file:///home/senke/Documents/veza/veza-backend-api/internal/handlers/webhook_handlers.go) *
|
||
|
||
*Viewed [avatar_handler.go](file:///home/senke/Documents/veza/veza-backend-api/internal/handlers/avatar_handler.go) *
|
||
|
||
*Viewed [playback_analytics_handler.go](file:///home/senke/Documents/veza/veza-backend-api/internal/handlers/playback_analytics_handler.go) *
|
||
|
||
*User accepted the command `grep -r "RespondWithSuccess" /home/senke/Documents/veza/veza-backend-api/internal/handlers`*
|
||
|
||
*User accepted the command `go build ./internal/handlers/...`*
|
||
|
||
*User accepted the command `grep -r "RespondWith" /home/senke/Documents/veza/veza-backend-api/internal/handlers`*
|
||
|
||
*Edited relevant file*
|
||
|
||
*Edited relevant file*
|
||
|
||
*Edited relevant file*
|
||
|
||
*Edited relevant file*
|
||
|
||
*User accepted the command `go build ./internal/handlers/...`*
|
||
|
||
*Grep searched codebase*
|
||
|
||
*Edited relevant file*
|
||
|
||
*Listed directory [veza-backend-api](file:///home/senke/Documents/veza/veza-backend-api) *
|
||
|
||
*Viewed [Makefile](file:///home/senke/Documents/veza/veza-backend-api/Makefile) *
|
||
|
||
*Viewed [main.go](file:///home/senke/Documents/veza/veza-backend-api/cmd/api/main.go) *
|
||
|
||
*User accepted the command `swag init -g cmd/api/main.go`*
|
||
|
||
*User accepted the command `go install github.com/swaggo/swag/cmd/swag@latest`*
|
||
|
||
*User accepted the command `~/go/bin/swag init -g cmd/api/main.go`*
|
||
|
||
*Edited relevant file*
|
||
|
||
*Edited relevant file*
|
||
|
||
*Edited relevant file*
|
||
|
||
*Edited relevant file* |