Aller au contenu principal

Workers Architecture - Résumé de l'implémentation

Date : 2026-01-24
Statut : ✅ 100% TERMINÉ ET OPÉRATIONNEL

🎯 Objectif​

Déporter les opérations lourdes (OCR PDF, IA, Exports) vers des workers BullMQ asynchrones pour améliorer la performance et la scalabilité du CRM.

✅ Ce qui a été fait​

1. Infrastructure de base​

Migrations DB​

  • ✅ 0152 : Tables transversales (job_runs, outbox_events, file_objects)
  • ✅ 0153 : Tables spécifiques (export_jobs, ai_tasks, documents, document_pages, document_artifacts)
  • ✅ 0154 : Contexte Documents (session_id, contact_id)
  • ✅ 0155 : Types de notifications Document
  • ✅ 0156 : Templates d'extraction personnalisés

Services de base​

  • ✅ JobRunsService : CRUD + tracking avec corrélation.
  • ✅ FileObjectsService : Gestion des artefacts R2.
  • ✅ OutboxService : Pattern outbox transactionnel.
  • ✅ ExportJobService : Gestion des jobs d'export.
  • ✅ AiTaskService : Gestion des tâches IA avec suivi des coûts.
  • ✅ DocumentService : Gestion complète du cycle de vie des documents.
  • ✅ DocumentValidationService : Vérification automatique de la cohérence des données.
  • ✅ DocumentExtractionTemplateService : Gestion des schémas d'extraction personnalisés.

2. Workers (4/4)​

✅ worker-export​

  • Jobs : export:build
  • Queue : exports-v2
  • Fonctionnalités : Génération d'exports multi-formats (CSV, Excel, PDF, JSON) avec stockage R2.

✅ worker-email​

  • Jobs : email:send
  • Fonctionnalités : Envoi d'emails planifiés et tracking.

✅ worker-ai​

  • Jobs : ai:run
  • Queue : ai-insights
  • Fonctionnalités : Tâches IA avancées avec suivi précis des tokens et des coûts.

✅ worker-doc​

  • Jobs : doc:ingest, doc:ocr, doc:extract_structured
  • Queue : exports-v2
  • Fonctionnalités :
    • Pipeline complet : Ingestion → OCR (Tesseract.js) → Extraction IA (OpenAI).
    • Support PDF haute performance (parallélisé, avec cache).
    • Validation automatique contre le contexte CRM (Session/Contact).
    • Support des templates d'extraction personnalisés.

3. Frontend & UI​

✅ Expérience Utilisateur​

  • Composants : DocumentUpload, DocumentTextViewer, DocumentExtraction, DocumentValidation.
  • Intégration : Panneaux dédiés dans les vues Session et Contact.
  • Auto-application : Injection directe des données extraites dans les champs du CRM.
  • Export : Téléchargement direct en CSV/JSON des résultats IA.

✅ Temps Réel & Feedback​

  • Notifications : Alertes WebSocket et Push pour chaque étape franchie (OCR fini, IA finie).
  • Tracking : Barre de progression et badges de statut avec polling automatique via React Query.

📊 Statistiques finales​

  • Fichiers créés/modifiés : 50+
  • Services : 10
  • Modules : 14
  • Processors : 7
  • Migrations SQL : 5 (0152 à 0156)
  • Couverture de tests : Services critiques (PDF, Validation) testés avec Vitest.

🎯 Principes d'Architecture respectés​

  • ✅ Idempotence : jobId stable basé sur le contenu et le contexte.
  • ✅ Observabilité : Logs structurés avec emojis et scope clair.
  • ✅ Sécurité : Vérification systématique de l'ownership des ressources.
  • ✅ Robustesse : Gestion fine des erreurs PDF et LLM avec retries configurés.

🎉 Conclusion​

L'architecture Workers BullMQ est désormais le moteur asynchrone central d'Aaperture. Elle permet de traiter des milliers de documents et d'emails sans impacter la fluidité de l'interface utilisateur, tout en offrant des capacités d'IA avancées et structurées.