veza/docs/archive/root-md/REPORT_STATUS_2025_12_06.md

🔥 RAPPORT D'ÉTAT PROJET VEZA

Date : 2025-12-06
Auditeur : Antigravity
Version : 1.0

---

SECTION A — Synthèse exécutive

Le projet Veza est dans un état "Production-Ready avec réserves critiques".
Les efforts récents de stabilisation (JSON Hardening, UUID Migration, Transactions P0) ont considérablement assaini la base de code, éliminant les causes les plus fréquentes de crash et de corruption de données.

Cependant, des failles de robustesse subsistent dans les workers asynchrones backend (blocage de thread), la gestion du cycle de vie des tâches Rust (cancellation abrupte), et la supervision des connexions WebSocket (pas de heartbeat applicatif).

📊 État de Santé Global

Service	Stabilité	Code Quality	Migrations	Risque Principal
Backend Go	🟡 Stable mais Fragile	🟢 Bon (Hardened)	🟡 Mixte (Legacy présent)	Workers bloquants (Resource Starvation)
Chat Server	🟢 Robuste	🟢 Excellent (UUID Ok)	🟢 Clean	Connexions Zombies (No Heartbeat)
Stream Server	🟡 Fonctionnel	🟡 Complexe	N/A (No SQL migrations)	Perte de segments sur arrêt brutal

🚨 Points d'Attention Immédiats (P0)

1. Backend Workers : L'implémentation actuelle utilise time.Sleep dans la boucle de traitement, bloquant complètement les workers lors des retries. Risque critique de famine de jobs.
2. Cleanups Legacy : Le dossier migrations_legacy (44 fichiers) cohabite avec la V1, créant une confusion dangereux pour les nouveaux déploiements.
3. Task Abort Safety : Le Stream Server tue les tâches de monitoring violemment (abort()) sans drainer les événements en attente, risquant la perte des derniers segments encodés.

---

SECTION B — Analyse service par service

1. Backend Go (veza-backend-api)

État : Partiellement Stable / Worker System Defective

• API / Handlers : ✅ Excellent. Le BindAndValidateJSON (CommonHandler) est déployé et robuste. Il gère correctement les limites de taille (10MB), les erreurs de syntaxe et le typage. Plus de 500 status codes inattendus sur le parsing JSON.
• Transactions : ✅ Bon. CreateOrder et autres flux critiques utilisent db.Transaction. Le risque d'incohérence financière est maîtrisé.
• Workers : ❌ CRITIQUE.
  • Le mécanisme de retry fait time.Sleep(delay) à l'intérieur du thread worker. Si 2 workers traitent 2 jobs en échec, plus aucun job ne passe pendant 5 minutes.
  • La queue est in-memory (chan Job). Perte de données totale en cas de redémarrage.
• Migrations : ⚠️ Bruitée. Le dossier migrations (Active) est propre, mais migrations_legacy doit être supprimé impérativement pour éviter des accidents de déploiement.

2. Chat Server Rust (veza-chat-server)

État : Robuste / UUID Migré

• Architecture : ✅ Utilise Axum + Tokio. Structure modulaire saine.
• UUID Migration : ✅ CONFIRMÉ. Contrairement à la documentation interne obsolète, le code hub/channels.rs utilise bien Uuid pour Room, RoomMember, etc.
• Sécurité Panic : ✅ Gestion d'erreurs explicite (Result<T, ChatError>) dans la boucle WebSocket. Pas de unwrap() dangereux détecté dans le hot path.
• Fiabilité Connexion : ⚠️ Manquante. Le serveur répond aux Pings (Pong) mais n'a pas de timer pour déconnecter activement un client silencieux (Zombie connection).
• Graceful Shutdown : ❌ Le serveur axum::serve n'a pas de logique d'arrêt gracieux (with_graceful_shutdown). Les connexions seront coupées net au déploiement.

3. Stream Server Rust (veza-stream-server)

État : Fonctionnel à risque modéré

• Pipeline : ✅ Utilise FfmpegCommandBuilder et gère le processus via tokio::process.
• Transactions : ✅ La finalisation (finalize) est atomique. Elle re-persiste tous les segments dans une transaction unique, garantissant la cohérence finale.
• Task Safety : ⚠️ Usage de abort() sur les handles de monitoring (monitor_handle, event_handle) sans attendre la fin ou drainer le channel. Risque de perdre les 1-2 derniers segments si FFmpeg meurt très vite.
• Code Mort : Fichiers comme core/encoder.rs contiennent des TODOs "Implémentation réelle" qui semblent être des vestiges d'une ancienne version, alors que processor.rs fait le vrai travail.

---

SECTION C — Analyse transversale

1. Architecture & Cohérence

• UUID : Cohérence 100% atteinte (Backend, Chat, DB).
• Auth : Backend et Chat partagent la logique JWT, mais la clé secrète dépend de l'env (JWT_SECRET). Risque de configuration si non synchronisé via Ansible/K8s.
• Interopérabilité : Pas de validation que conversation_id existe côté Backend lors de la création côté Chat (sauf si synchro implicite par le client).

2. Tests & Qualité

• Tests Unitaires : Beaucoup de tests "SKIP" ou "TODO".
  • internal/handlers/room_handler_test.go désactivé (P0 compilation fix).
  • Go : Tests d'intégration difficiles sans DB dockerisée.
  • Rust : Tests ignorés (#[ignore]) nécessitant un environnement réel.
• Tests de Charge : Inexistants. Le comportement des RwLock du Chat Server sous 10k users est inconnu.

---

SECTION D — Liste exhaustive des TODOs détectés (Échantillon Critique)

Fichier	Ligne	Catégorie	Description
veza-backend-api/internal/workers/job_worker.go	332	P1	TODO: Enregistrer dans la table job_failures (Actuellement log only)
veza-chat-server/src/security/mod.rs	N/A	P0	TODO: Implémenter la validation réelle (Sécurité Auth?)
veza-chat-server/src/monitoring.rs	N/A	P2	TODO: implémenter lecture mémoire réelle (Métriques fausses)
veza-stream-server/src/core/sync.rs	N/A	P1	TODO: Implémenter l'envoi réel via la connexion WebSocket
veza-backend-api/internal/handlers/room_handler_test.go	N/A	P1	TODO(P2): Refactor ... Currently disabled (Tests unitaires manquants)
veza-backend-api/AUDIT_BACKEND_GO.md	Doc	Info	Mentionne "139 TODOs/FIXMEs/HACKs" globaux

---

SECTION E — Matrice de Priorisation du code

Priorité	Service	Composant	Problème / Action Requise	Risque si ignoré	Est. Temps
🔴 P0	Backend	JobWorker	Remplacer time.Sleep bloquant par un système de re-queue différé (AfterFunc ou DeliveryAt).	Arrêt total des jobs si erreurs en série.	2h
🔴 P0	Backend	Cleanup	Supprimer migrations_legacy/ et les scripts obsolètes.	Confusion DB, risque de run des vieux scripts.	30m
🔴 P0	Backend	Room Tests	Réparer room_handler_test.go.	Régression silencieuse sur feature core.	2h
🟠 P1	Chat	Heartbeat	Implémenter un disconnect timeout (ex: 60s sans pong).	Fuite de connexions, mémoire saturée.	3h
🟠 P1	Chat	Shutdown	Ajouter with_graceful_shutdown à Axum.	Perte de messages en vol au déploiement.	1h
🟠 P1	Stream	Processor	Drainer le channel d'événements avant abort().	Perte sporadique de segments hls.	2h
🟡 P2	Backend	Persistence	Migrer la queue Worker vers Redis ou DB (Job Table).	Perte de jobs au redémarrage.	1j
🟡 P2	Chat	Monitoring	Implémenter les vraies métriques CPU/RAM.	Aveugle sur la conso ressources.	4h

---

SECTION F — Roadmap de développement immédiate (Semaines 1-4)

Semaine 1 : Stabilisation Critique (The "Stop the Bleeding" Phase)

• Jour 1 : Fix du JobWorker (Backend) pour supprimer le time.Sleep bloquant.
• Jour 2 : Suppression définitive de migrations_legacy et validation d'un terraform/docker clean.
• Jour 3 : Implémentation du Graceful Shutdown (Chat & Backend).
• Jour 4 : Fix des tests unitaires room_handler et CI simple (GitHub Actions).
• Jour 5 : Audit manuel de sécurité sur security/mod.rs (Chat) pour traiter le TODO de validation.

Semaine 2 : Robustesse & Fiabilité

• Stream Server : Sécurisation de l'arrêt des tâches (Use CancellationToken instead of abort).
• Chat Server : Implémentation du Heartbeat application-layer.
• Backend : Migration de la queue de jobs vers une table PostgreSQL (jobs table with status, run_at).

Semaine 3 : Performance & Monitoring

• Implémentation des vraies métriques Rust (Chat/Stream).
• Setup d'un Dashboard Grafana minimal (Jobs lag, WS connections, Stream status).
• Tests de charge (k6) sur le WebSocket Chat.

Semaine 4 : Cleanup & QA

• Revue de tous les TODOs restants.
• Écriture de tests d'intégration E2E (Backend -> Chat -> Stream).

---

SECTION G — Validation finale (Critères DONE)

Pour considérer le projet stable techniquement, nous devons valider :

• 0 Sleep bloquant dans les workers Go.
• 0 Panic possible sur les entrées utilisateur WebSocket (Vérifié par fuzzing ou review).
• Clean Shutdown : Les services s'arrêtent en finissant les requêtes en cours (< 30s).
• Zéro Legacy : Le dossier migrations_legacy est supprimé du repo.
• State Consistency : Un job stream interrompu nettoie sa DB ou reprend (non supporté actuellement, mais au moins ne corrompt pas).

---

💡 L'avis du Staff Engineer

"Le code est de bonne qualité structurelle (Hexagonal/Clean Arch en Go, Modular en Rust). Les bases sont solides (UUID, Transactions). Le danger immédiat n'est pas dans l'architecture, mais dans les détails d'implémentation asynchrone (le sleep bloquant, le abort brutal). Corrigez ces 3-4 points de threading/concurrence, et vous aurez une plateforme très stable."