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"
```

---

## 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** : Janvier 2024  
**Version** : 1.0.0  
**Statut** : ✅ Document de référence officiel