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
2. Classification des Erreurs
3. Processus de Correction
4. Format de Documentation
5. Checklist de Validation
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 :

# 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

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

## 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 :

# 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 :

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 :

## 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 :

#!/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 :

#!/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

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

# 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