veza/veza-docs/ORIGIN/ORIGIN_ERROR_RESOLUTION_STRATEGY.md

# ORIGIN_ERROR_RESOLUTION_STRATEGY.md

## 📋 RÉSUMÉ EXÉCUTIF

Ce document définit la **stratégie officielle de résolution d'erreurs** pour le projet Veza. Il s'intègre parfaitement à la méthodologie ORIGIN_ existante et doit être appliqué **AVANT** de reprendre l'implémentation des 2100+ tâches restantes. Cette stratégie garantit une base de code stable et fonctionnelle.

## 🎯 OBJECTIFS

### Objectif Principal
Identifier, documenter et corriger **TOUTES** les erreurs existantes dans le codebase actuel avant de poursuivre le développement de nouvelles fonctionnalités.

### Objectifs Secondaires
- Établir un processus répétable de détection et correction d'erreurs
- Maintenir la cohérence avec les standards ORIGIN_
- Documenter chaque correction pour référence future
- Créer une baseline stable pour les tests

## 🔒 RÈGLES IMMUABLES

1. **AUCUNE nouvelle fonctionnalité** avant correction des erreurs existantes
2. **TOUJOURS documenter** chaque erreur identifiée (fichier ORIGIN_ERROR_REGISTRY.md)
3. **TOUJOURS créer une tâche** pour chaque correction (format TERR-XXX)
4. **TOUJOURS tester** après chaque correction
5. **JAMAIS contourner** une erreur sans la corriger définitivement
6. **TOUJOURS respecter** ORIGIN_CODE_STANDARDS.md dans les corrections

## 📖 TABLE DES MATIÈRES

1. [Méthodologie de Résolution](#1-méthodologie-de-résolution)
2. [Classification des Erreurs](#2-classification-des-erreurs)
3. [Processus de Correction](#3-processus-de-correction)
4. [Format de Documentation](#4-format-de-documentation)
5. [Checklist de Validation](#5-checklist-de-validation)
6. [Intégration avec ORIGIN_IMPLEMENTATION_TASKS](#6-intégration-avec-origin_implementation_tasks)

---

## 1. Méthodologie de Résolution

### 1.1 Phase de Découverte (PHASE 0)

**Durée estimée** : 2-4 heures

**Objectif** : Identifier toutes les erreurs existantes

**Actions** :
1. Lancer tous les services (backend, frontend, chat, stream)
2. Collecter tous les logs d'erreur
3. Exécuter tous les tests existants
4. Lancer les linters et analyseurs statiques
5. Vérifier les builds de production
6. Tester les endpoints critiques

**Commandes de découverte** :
```bash
# Backend Go
cd veza-backend-api
go build ./...
go test ./... -v
go vet ./...
golangci-lint run

# Frontend React
cd apps/web
npm run build
npm run lint
npm test

# Chat Server Rust
cd veza-chat-server
cargo build --release
cargo test
cargo clippy

# Stream Server Rust
cd veza-stream-server
cargo build --release
cargo test
cargo clippy

# Docker
docker-compose config
```

**Livrables** :
- Liste complète des erreurs (ORIGIN_ERROR_REGISTRY.md)
- Logs d'erreur sauvegardés
- Rapport de découverte

### 1.2 Phase de Classification (PHASE 0.5)

**Durée estimée** : 1-2 heures

**Objectif** : Classer et prioriser les erreurs

**Actions** :
1. Catégoriser chaque erreur (voir section 2)
2. Assigner une priorité (P0, P1, P2, P3)
3. Estimer la complexité de correction
4. Identifier les dépendances entre erreurs

**Critères de priorité** :
- **P0 (CRITIQUE)** : Bloque le démarrage de l'application
- **P1 (HAUTE)** : Empêche des fonctionnalités majeures
- **P2 (MOYENNE)** : Affecte des fonctionnalités mineures
- **P3 (BASSE)** : Avertissements, code smell, optimisations

### 1.3 Phase de Correction (PHASE 0.75)

**Durée estimée** : Variable selon les erreurs

**Objectif** : Corriger toutes les erreurs P0 et P1, puis P2

**Ordre de correction** :
1. Erreurs P0 (ordre de dépendance)
2. Erreurs P1 (ordre de dépendance)
3. Erreurs P2 (ordre de dépendance)
4. Erreurs P3 (si temps disponible)

**Pour chaque erreur** :
1. Créer une tâche TERR-XXX
2. Corriger selon ORIGIN_CODE_STANDARDS.md
3. Tester la correction
4. Documenter la solution
5. Committer avec format : "TERR-XXX: [Description]"
6. Marquer comme résolue dans ORIGIN_ERROR_REGISTRY.md

### 1.4 Phase de Validation (PHASE 0.9)

**Durée estimée** : 2-3 heures

**Objectif** : Valider que toutes les corrections fonctionnent ensemble

**Actions** :
1. Relancer tous les tests
2. Démarrer tous les services
3. Tester les scénarios critiques
4. Vérifier les métriques de qualité
5. Créer un rapport de validation

**Critères de succès** :
- ✅ Tous les services démarrent sans erreur
- ✅ Tests backend ≥ 80% coverage, 100% pass
- ✅ Tests frontend ≥ 80% coverage, 100% pass
- ✅ Builds de production réussis
- ✅ Aucune erreur critique dans les logs

---

## 2. Classification des Erreurs

### 2.1 Catégories d'Erreurs

#### CAT-01: Erreurs de Compilation
- Packages manquants
- Imports cycliques
- Erreurs de syntaxe
- Conflits de types

**Exemple** :
```
package veza-backend-api/internal/api/search is not in std
```

#### CAT-02: Erreurs de Configuration
- Variables d'environnement manquantes
- Fichiers de config invalides
- Ports déjà utilisés
- Chemins incorrects

**Exemple** :
```
DATABASE_URL not set
```

#### CAT-03: Erreurs de Dépendances
- Packages NPM manquants
- Versions incompatibles
- Dépendances circulaires

**Exemple** :
```
Cannot find package 'rollup-plugin-visualizer'
```

#### CAT-04: Erreurs Runtime
- Null pointer exceptions
- Database connection failures
- Timeout errors
- Resource not found

#### CAT-05: Erreurs de Tests
- Tests qui échouent
- Mocks incorrects
- Assertions invalides

#### CAT-06: Erreurs Docker
- Images manquantes
- docker-compose.yml invalide
- Network issues
- Volume permissions

#### CAT-07: Erreurs de Lint/Format
- Code style violations
- Unused imports
- Dead code
- Type errors (TypeScript)

### 2.2 Niveaux de Priorité

| Priorité | Définition | Impact | Délai de correction |
|----------|------------|--------|---------------------|
| **P0** | Bloque l'application | Application inutilisable | Immédiat |
| **P1** | Bloque une feature majeure | Fonctionnalité critique KO | 1-2 jours |
| **P2** | Affecte une feature mineure | Fonctionnalité secondaire KO | 3-5 jours |
| **P3** | Warning/optimisation | Qualité du code | Backlog |

### 2.3 Niveaux de Complexité

| Complexité | Temps estimé | Description |
|------------|--------------|-------------|
| **TRIVIAL** | 5-15 min | Import manquant, typo |
| **SIMPLE** | 15-60 min | Config, dépendance |
| **MOYEN** | 1-4 heures | Refactoring léger |
| **COMPLEXE** | 4-8 heures | Architecture, dépendances multiples |
| **CRITIQUE** | 1-3 jours | Refonte majeure |

---

## 3. Processus de Correction

### 3.1 Workflow Standard

```mermaid
graph TD
    A[Erreur Identifiée] --> B[Créer TERR-XXX]
    B --> C[Classer CAT-XX + Priorité]
    C --> D[Analyser la cause]
    D --> E[Proposer solution]
    E --> F[Implémenter selon ORIGIN_CODE_STANDARDS]
    F --> G[Tester la correction]
    G --> H{Tests OK?}
    H -->|Non| D
    H -->|Oui| I[Documenter]
    I --> J[Commit]
    J --> K[Marquer résolu]
```

### 3.2 Template de Tâche TERR-XXX

```markdown
## TERR-XXX: [Titre descriptif]

**Catégorie**: CAT-XX  
**Priorité**: PX  
**Complexité**: [TRIVIAL|SIMPLE|MOYEN|COMPLEXE|CRITIQUE]  
**Temps Estimé**: Xh  
**Statut**: ⏳ **EN ATTENTE** | 🔄 **EN COURS** | ✅ **RÉSOLU**

### Description de l'Erreur
[Description détaillée de l'erreur]

### Message d'Erreur
```
[Copier le message d'erreur complet]
```

### Cause Identifiée
[Explication de la cause racine]

### Solution Proposée
[Description de la solution]

### Fichiers Affectés
- `chemin/vers/fichier1.ext`
- `chemin/vers/fichier2.ext`

### Implémentation

**Étape 1**: [Description]  
**Étape 2**: [Description]  
**Étape 3**: [Description]

### Tests de Validation
- [ ] Build réussi
- [ ] Tests unitaires passent
- [ ] Tests d'intégration passent
- [ ] Service démarre correctement
- [ ] Fonctionnalité testée manuellement

### Definition of Done
- [ ] Erreur corrigée
- [ ] Tests ajoutés/mis à jour
- [ ] Documentation mise à jour
- [ ] Code review (si applicable)
- [ ] Commit effectué
```

### 3.3 Format de Commit

```
TERR-XXX: [Type] [Description courte]

[Description détaillée de la correction]

Fixes: TERR-XXX
Category: CAT-XX
Priority: PX
Files: file1.go, file2.tsx
Tests: Added/Updated/None
```

**Types** :
- `fix` : Correction d'erreur
- `deps` : Mise à jour de dépendances
- `config` : Modification de configuration
- `refactor` : Refactoring pour corriger
- `test` : Correction de tests

**Exemple** :
```
TERR-001: fix: Add missing rollup-plugin-visualizer dependency

Fixed frontend build error by adding missing dev dependency
rollup-plugin-visualizer required by vite.config.ts

Fixes: TERR-001
Category: CAT-03
Priority: P0
Files: apps/web/package.json
Tests: None
```

---

## 4. Format de Documentation

### 4.1 ORIGIN_ERROR_REGISTRY.md

Fichier central listant toutes les erreurs identifiées et leur statut.

**Structure** :
```markdown
# ORIGIN_ERROR_REGISTRY.md

## Statistiques

- **Total erreurs** : XX
- **P0 résolues** : X/X
- **P1 résolues** : X/X
- **P2 résolues** : X/X
- **P3 résolues** : X/X

## Erreurs Actives

### P0 - Critiques

#### TERR-001: [Titre]
- **Catégorie** : CAT-XX
- **Composant** : Backend/Frontend/Chat/Stream
- **Statut** : ⏳ EN ATTENTE
- **Assigné** : [Nom ou vide]
- **Découvert** : 2024-01-XX
- **Résolu** : -

#### TERR-002: [Titre]
...

### P1 - Hautes

...

## Erreurs Résolues

### TERR-XXX: [Titre] ✅
- **Catégorie** : CAT-XX
- **Résolu le** : 2024-01-XX
- **Solution** : [Brève description]
- **Commit** : abc123def
```

### 4.2 Logs de Correction

Sauvegarder les logs de découverte :

```bash
mkdir -p docs/ORIGIN/error-logs
date=$(date +%Y%m%d-%H%M%S)

# Sauvegarder les logs d'erreur
cp logs/backend.log docs/ORIGIN/error-logs/backend-${date}.log
cp logs/frontend.log docs/ORIGIN/error-logs/frontend-${date}.log

# Sauvegarder les résultats de tests
go test ./... -v > docs/ORIGIN/error-logs/backend-tests-${date}.log 2>&1
npm test > docs/ORIGIN/error-logs/frontend-tests-${date}.log 2>&1
```

---

## 5. Checklist de Validation

### 5.1 Avant de démarrer les corrections

- [ ] Tous les logs d'erreur sont sauvegardés
- [ ] ORIGIN_ERROR_REGISTRY.md est créé et complet
- [ ] Toutes les erreurs sont classées (CAT + Priorité)
- [ ] Les dépendances entre erreurs sont identifiées
- [ ] Un plan de correction est établi

### 5.2 Pour chaque correction

- [ ] Tâche TERR-XXX créée dans ORIGIN_IMPLEMENTATION_TASKS.md
- [ ] Cause racine identifiée
- [ ] Solution conforme à ORIGIN_CODE_STANDARDS.md
- [ ] Tests ajoutés/mis à jour
- [ ] Build réussi
- [ ] Tests unitaires passent
- [ ] Service démarre correctement
- [ ] Commit avec format standard
- [ ] ORIGIN_ERROR_REGISTRY.md mis à jour

### 5.3 Avant de reprendre les tâches normales

- [ ] Toutes les erreurs P0 sont résolues
- [ ] Toutes les erreurs P1 sont résolues
- [ ] Au moins 80% des erreurs P2 sont résolues
- [ ] Tous les services démarrent sans erreur
- [ ] Tests backend ≥ 80% coverage
- [ ] Tests frontend ≥ 80% coverage
- [ ] Builds de production réussis
- [ ] Documentation à jour
- [ ] Rapport de validation créé
- [ ] Commit "PHASE 0: Error Resolution Complete"

---

## 6. Intégration avec ORIGIN_IMPLEMENTATION_TASKS

### 6.1 Nouvelle Section dans ORIGIN_IMPLEMENTATION_TASKS.md

Ajouter en début de fichier :

```markdown
## PHASE 0: ERROR RESOLUTION (TERR-001 à TERR-XXX)

**Statut Global** : 🔄 **EN COURS** | ✅ **TERMINÉ**  
**Priorité** : CRITIQUE  
**Durée Estimée** : 1-2 semaines  
**Prérequis** : Aucun  
**Bloque** : Toutes les autres phases

### Description
Phase de stabilisation pour corriger toutes les erreurs existantes
avant de reprendre le développement des 2100+ tâches.

### Objectifs
- Corriger 100% des erreurs P0
- Corriger 100% des erreurs P1
- Corriger ≥ 80% des erreurs P2
- Documenter toutes les corrections
- Établir une baseline stable

### Tâches (voir ORIGIN_ERROR_REGISTRY.md)
- TERR-001 à TERR-XXX selon découverte

### Definition of Done
- [ ] Tous les services démarrent
- [ ] Tests ≥ 80% coverage
- [ ] Builds production OK
- [ ] Documentation à jour
- [ ] Rapport de validation créé
```

### 6.2 Numérotation des Tâches

Les tâches de correction d'erreurs utilisent le préfixe **TERR** (Task Error Resolution) :

- **TERR-001** à **TERR-999** : Réservé aux corrections d'erreurs
- **T0001** à **T2100+** : Tâches de développement normales

### 6.3 Reprise après Phase 0

Une fois la Phase 0 terminée, reprendre à partir de **T0511** (tâche suivant T0510).

---

## 7. Outils et Scripts

### 7.1 Script de Découverte Automatique

Créer `scripts/discover-errors.sh` :

```bash
#!/bin/bash
# ORIGIN Error Discovery Script

echo "🔍 Découverte des erreurs existantes..."
mkdir -p docs/ORIGIN/error-logs
DATE=$(date +%Y%m%d-%H%M%S)

# Backend
echo "📡 Analyse du backend..."
cd veza-backend-api
go build ./... > ../docs/ORIGIN/error-logs/backend-build-${DATE}.log 2>&1
go test ./... -v > ../docs/ORIGIN/error-logs/backend-tests-${DATE}.log 2>&1
go vet ./... > ../docs/ORIGIN/error-logs/backend-vet-${DATE}.log 2>&1
cd ..

# Frontend
echo "🌐 Analyse du frontend..."
cd apps/web
npm run build > ../../docs/ORIGIN/error-logs/frontend-build-${DATE}.log 2>&1
npm test > ../../docs/ORIGIN/error-logs/frontend-tests-${DATE}.log 2>&1
npm run lint > ../../docs/ORIGIN/error-logs/frontend-lint-${DATE}.log 2>&1
cd ../..

# Générer résumé
echo "📊 Génération du résumé..."
./scripts/generate-error-summary.sh

echo "✅ Découverte terminée. Voir docs/ORIGIN/error-logs/"
```

### 7.2 Script de Génération de Rapport

Créer `scripts/generate-error-summary.sh` :

```bash
#!/bin/bash
# Generate error summary

DATE=$(date +%Y%m%d-%H%M%S)
OUTPUT="docs/ORIGIN/error-logs/summary-${DATE}.md"

echo "# Rapport de Découverte d'Erreurs" > $OUTPUT
echo "" >> $OUTPUT
echo "**Date** : $(date)" >> $OUTPUT
echo "" >> $OUTPUT

# Compter les erreurs
BACKEND_ERRORS=$(grep -c "error\|Error\|ERROR" docs/ORIGIN/error-logs/backend-* 2>/dev/null || echo "0")
FRONTEND_ERRORS=$(grep -c "error\|Error\|ERROR" docs/ORIGIN/error-logs/frontend-* 2>/dev/null || echo "0")

echo "## Statistiques" >> $OUTPUT
echo "" >> $OUTPUT
echo "- **Backend** : ${BACKEND_ERRORS} erreurs" >> $OUTPUT
echo "- **Frontend** : ${FRONTEND_ERRORS} erreurs" >> $OUTPUT
echo "- **Total** : $((BACKEND_ERRORS + FRONTEND_ERRORS)) erreurs" >> $OUTPUT

echo "✅ Rapport généré : $OUTPUT"
```

---

## 8. Exemples de Corrections

### 8.1 Exemple : Package Manquant (CAT-03, P0)

**TERR-001: Add missing rollup-plugin-visualizer**

```bash
cd apps/web
npm install -D rollup-plugin-visualizer
npm run build # Vérifier que ça marche
git add package.json package-lock.json
git commit -m "TERR-001: deps: Add missing rollup-plugin-visualizer

Fixed frontend build error by adding missing dev dependency.

Fixes: TERR-001
Category: CAT-03
Priority: P0
Files: apps/web/package.json
Tests: None"
```

### 8.2 Exemple : Import Cyclique (CAT-01, P0)

**TERR-002: Fix circular dependency in internal/config**

```bash
# Analyser la dépendance
go list -f '{{.ImportPath}} {{.Imports}}' ./internal/config

# Refactorer pour casser le cycle (exemple simplifié)
# Déplacer les types communs dans un package séparé

git add internal/config internal/types
git commit -m "TERR-002: refactor: Break circular dependency in config

Moved shared types to internal/types to break import cycle
between config and handlers packages.

Fixes: TERR-002
Category: CAT-01
Priority: P0
Files: internal/config/config.go, internal/types/types.go
Tests: Updated"
```

### 8.3 Exemple : Discovery Algorithm Bias Detected (CAT-04, P1)

**TERR-030: Fix abnormal distribution in discovery algorithm**

Un biais dans l'algorithme de découverte favorise disproportionnellement certains artistes ou genres. Détecté par une analyse statistique de la distribution des tracks recommandées.

**Diagnostic** :
```bash
# Analyser la distribution des tracks dans les résultats de découverte
psql $DATABASE_URL -c "
  SELECT genre, COUNT(*) as count,
         ROUND(COUNT(*) * 100.0 / SUM(COUNT(*)) OVER(), 2) as pct
  FROM discovery_results
  JOIN tracks ON tracks.id = discovery_results.track_id
  GROUP BY genre
  ORDER BY count DESC;
"
# Si un genre dépasse 40% → biais confirmé
```

**Résolution** :
```go
// Vérifier les pondérations de l'algorithme de découverte
// internal/services/discovery_service.go

func (s *DiscoveryService) GetRecommendations(ctx context.Context, params DiscoveryParams) ([]Track, error) {
    tracks, err := s.repo.GetDiscoverableTracks(ctx, params)
    if err != nil {
        return nil, fmt.Errorf("discovery query failed: %w", err)
    }

    if err := s.validateDistribution(tracks); err != nil {
        s.logger.Warn("discovery distribution anomaly detected", "error", err)
        s.metrics.IncrCounter("discovery.distribution_anomaly", 1)
    }

    return tracks, nil
}

func (s *DiscoveryService) validateDistribution(tracks []Track) error {
    genreCounts := make(map[string]int)
    for _, t := range tracks {
        genreCounts[t.Genre]++
    }
    threshold := float64(len(tracks)) * 0.4
    for genre, count := range genreCounts {
        if float64(count) > threshold {
            return fmt.Errorf("genre %q represents %.1f%% of results (max 40%%)",
                genre, float64(count)/float64(len(tracks))*100)
        }
    }
    return nil
}
```

```bash
git add internal/services/discovery_service.go
git commit -m "$(cat <<'EOF'
TERR-030: fix: Add distribution validation to discovery algorithm

Added genre distribution check to detect and log abnormal bias
in discovery results. Threshold set at 40% per genre.

Fixes: TERR-030
Category: CAT-04
Priority: P1
Files: internal/services/discovery_service.go
Tests: Added
EOF
)"
```

### 8.4 Exemple : JWT Mismatch Errors (CAT-02, P0)

**TERR-031: Fix JWT issuer/audience validation**

Erreurs 401 intermittentes causées par un mismatch entre l'issuer configuré dans le service d'émission et celui attendu par le service de validation.

**Diagnostic** :
```bash
# Identifier les tokens rejetés
grep "token validation failed" /var/log/veza-api/*.log | tail -20

# Vérifier la configuration
echo "Émission: JWT_ISSUER=$JWT_ISSUER"
echo "Validation: JWT_EXPECTED_ISSUER=$JWT_EXPECTED_ISSUER"
# Si différents → mismatch confirmé
```

**Résolution** :

```go
// Étape 1 : Centraliser la configuration JWT
// internal/auth/jwt_config.go
type JWTConfig struct {
    Secret   string
    Issuer   string
    Audience string
    Expiry   time.Duration
}

func LoadJWTConfig() (*JWTConfig, error) {
    cfg := &JWTConfig{
        Secret:   os.Getenv("JWT_SECRET"),
        Issuer:   os.Getenv("JWT_ISSUER"),
        Audience: os.Getenv("JWT_AUDIENCE"),
        Expiry:   parseDuration(os.Getenv("JWT_EXPIRATION"), 24*time.Hour),
    }
    if cfg.Secret == "" {
        return nil, fmt.Errorf("JWT_SECRET is required")
    }
    if cfg.Issuer == "" {
        return nil, fmt.Errorf("JWT_ISSUER is required")
    }
    if cfg.Audience == "" {
        return nil, fmt.Errorf("JWT_AUDIENCE is required")
    }
    return cfg, nil
}

// Étape 2 : Utiliser la même config pour émission ET validation
// internal/auth/jwt.go
func (a *Auth) GenerateToken(userID string) (string, error) {
    claims := jwt.RegisteredClaims{
        Issuer:    a.config.Issuer,
        Audience:  jwt.ClaimStrings{a.config.Audience},
        Subject:   userID,
        ExpiresAt: jwt.NewNumericDate(time.Now().Add(a.config.Expiry)),
        IssuedAt:  jwt.NewNumericDate(time.Now()),
    }
    return jwt.NewWithClaims(jwt.SigningMethodHS256, claims).SignedString([]byte(a.config.Secret))
}

func (a *Auth) ValidateToken(tokenStr string) (*jwt.RegisteredClaims, error) {
    token, err := jwt.ParseWithClaims(tokenStr, &jwt.RegisteredClaims{},
        func(token *jwt.Token) (interface{}, error) {
            return []byte(a.config.Secret), nil
        },
        jwt.WithIssuer(a.config.Issuer),
        jwt.WithAudience(a.config.Audience),
    )
    if err != nil {
        return nil, fmt.Errorf("token validation failed: %w", err)
    }
    return token.Claims.(*jwt.RegisteredClaims), nil
}
```

```bash
git add internal/auth/
git commit -m "$(cat <<'EOF'
TERR-031: fix: Centralize JWT config and enforce issuer/audience validation

- Created JWTConfig with fail-fast validation at startup
- Unified issuer/audience between token generation and validation
- Added jwt.WithIssuer/WithAudience to ParseWithClaims

Fixes: TERR-031
Category: CAT-02
Priority: P0
Files: internal/auth/jwt_config.go, internal/auth/jwt.go
Tests: Added
EOF
)"
```

### 8.5 Exemple : Error Handling Migration gin.H → RespondWithAppError (CAT-04, P1)

**TERR-032: Migrate error responses from gin.H to RespondWithAppError**

Migration systématique de toutes les réponses d'erreur ad hoc (`gin.H{"error": ...}`) vers le format standardisé (`RespondWithAppError`).

**Diagnostic** :
```bash
# Identifier tous les usages de gin.H pour les erreurs
grep -rn 'gin.H{.*"error"' internal/handlers/
# Compter les occurrences
grep -rn 'gin.H{.*"error"' internal/handlers/ | wc -l
```

**Résolution** :

```go
// Étape 1 : S'assurer que apperrors couvre tous les cas
// internal/apperrors/errors.go
func NewValidationError(message string, cause error) *AppError {
    return &AppError{Code: "VALIDATION_ERROR", Message: message, Status: 400, Cause: cause}
}

func NewNotFoundError(resource string) *AppError {
    return &AppError{Code: "NOT_FOUND", Message: fmt.Sprintf("%s not found", resource), Status: 404}
}

func NewUnauthorizedError(message string) *AppError {
    return &AppError{Code: "UNAUTHORIZED", Message: message, Status: 401}
}

func NewForbiddenError(message string) *AppError {
    return &AppError{Code: "FORBIDDEN", Message: message, Status: 403}
}
```

```go
// Étape 2 : Remplacer chaque occurrence dans les handlers
// AVANT :
c.JSON(http.StatusBadRequest, gin.H{"error": "invalid request"})

// APRÈS :
RespondWithAppError(c, apperrors.NewValidationError("invalid request", err))

// AVANT :
c.JSON(http.StatusNotFound, gin.H{"error": "track not found"})

// APRÈS :
RespondWithAppError(c, apperrors.NewNotFoundError("track"))

// AVANT :
c.JSON(http.StatusUnauthorized, gin.H{"error": "unauthorized"})

// APRÈS :
RespondWithAppError(c, apperrors.NewUnauthorizedError("authentication required"))
```

**Validation post-migration** :
```bash
# Vérifier qu'aucun gin.H{"error" ne subsiste
grep -rn 'gin.H{.*"error"' internal/handlers/
# Résultat attendu : 0 ligne

# Vérifier que les tests passent toujours
go test ./internal/handlers/... -v
```

```bash
git add internal/handlers/ internal/apperrors/
git commit -m "$(cat <<'EOF'
TERR-032: refactor: Migrate all error responses to RespondWithAppError

Replaced all gin.H{"error": ...} with RespondWithAppError() across
all handlers for consistent error response format.

Fixes: TERR-032
Category: CAT-04
Priority: P1
Files: internal/handlers/*.go, internal/apperrors/errors.go
Tests: Updated
EOF
)"
```

---

## 9. Métriques de Succès

### 9.1 Objectifs Quantitatifs

- **Taux de résolution P0** : 100%
- **Taux de résolution P1** : 100%
- **Taux de résolution P2** : ≥ 80%
- **Coverage tests backend** : ≥ 80%
- **Coverage tests frontend** : ≥ 80%
- **Temps de build** : < 5 min
- **Temps de démarrage** : < 30 sec

### 9.2 Critères Qualitatifs

- ✅ Code conforme à ORIGIN_CODE_STANDARDS.md
- ✅ Documentation à jour
- ✅ Tous les services démarrent
- ✅ Aucune régression introduite
- ✅ Architecture préservée

---

## 10. Maintenance Continue

### 10.1 Après la Phase 0

Une fois toutes les erreurs corrigées :

1. **Ne plus accumuler de dette technique**
2. **Corriger immédiatement** toute nouvelle erreur
3. **Maintenir** les tests et la qualité
4. **Réviser** périodiquement ORIGIN_ERROR_REGISTRY.md

### 10.2 Processus Continu

- **Daily** : Vérifier les logs, aucune nouvelle erreur
- **Weekly** : Lancer les tests complets
- **Monthly** : Audit de qualité du code

---

## ✅ CHECKLIST DE VALIDATION FINALE

Avant de marquer la Phase 0 comme terminée :

- [ ] ORIGIN_ERROR_REGISTRY.md créé et complet
- [ ] Toutes les erreurs P0 résolues (100%)
- [ ] Toutes les erreurs P1 résolues (100%)
- [ ] Au moins 80% des erreurs P2 résolues
- [ ] Tous les logs d'erreur sauvegardés
- [ ] Script discover-errors.sh créé
- [ ] Script generate-error-summary.sh créé
- [ ] Tests backend ≥ 80% coverage
- [ ] Tests frontend ≥ 80% coverage
- [ ] Backend démarre sans erreur
- [ ] Frontend démarre sans erreur
- [ ] Chat server compile (si applicable)
- [ ] Stream server compile (si applicable)
- [ ] Builds de production réussis
- [ ] Documentation mise à jour
- [ ] Rapport de validation créé
- [ ] Commit "PHASE 0: Error Resolution Complete"
- [ ] Ready to resume T0511+

---

**Dernière mise à jour** : 2026-03-04  
**Version** : 2.0.0  
**Statut** : ✅ Document de référence officiel