Aller au contenu principal

Plan d'Implémentation - Architecture Workers BullMQ

Date : 2026-01-24
Statut : 🚀 Prêt pour finalisation et déploiement

📊 État Actuel​

✅ Ce qui est déjà implémenté​

Infrastructure​

  • ✅ 4 Workers : worker-export, worker-email, worker-ai, worker-doc
  • ✅ Migrations DB : 0152 (infrastructure) et 0153 (tables spécifiques)
  • ✅ Services : JobRunsService, FileObjectsService, OutboxService
  • ✅ WorkersQueueService : Service centralisé pour enqueueer les jobs
  • ✅ Validation Zod : Tous les payloads validés
  • ✅ Idempotence : JobId stable pour tous les jobs
  • ✅ Modules intégrés : Tous les modules sont intégrés dans ApiOpsModule et WorkerModule

Processors​

  • ✅ ExportBuildProcessor : Traite les exports asynchrones
  • ✅ EmailSendProcessor : Envoi d'emails individuels
  • ✅ EmailSeqRunDueProcessor : Exécution des séquences d'emails
  • ✅ AiRunProcessor : Exécution de tâches IA
  • ✅ DocIngestProcessor : Ingestion de documents
  • ✅ DocOcrProcessor : OCR de documents (placeholder)
  • ✅ DocExtractStructuredProcessor : Extraction structurée

API​

  • ✅ JobRunsController : Endpoints pour polling status
  • ✅ ExportController.exportAsync() : Endpoint async pour exports
  • ✅ Intégration dans les services existants

Frontend​

  • ✅ Hooks React Query : useJobRuns, useJobRun
  • ✅ Composants : JobRunStatusBadge, JobRunProgress

⚠️ Actions requises immédiatement​

  1. Exécuter les migrations DB

    npm run migrate
    • Vérifier que les tables job_runs, outbox_events, file_objects sont créées
    • Vérifier que les tables export_jobs, ai_tasks, documents sont créées

  2. Générer les types TypeScript

    npm run generate:types
    • Vérifier que les types sont dans database.types.ts
    • Supprimer les casts as any temporaires

  3. Configuration environnement

    • Vérifier QUEUE_WORKERS_ENABLED=true
    • Vérifier les variables Redis et R2

  4. Test de démarrage

    • Démarrer le backend en mode worker
    • Vérifier que les workers démarrent sans erreur

🎯 Plan d'Action​

Phase 1 : Finalisation (Aujourd'hui)​

1.1 Vérifier l'état des migrations​

# Vérifier si les migrations ont été exécutées
psql -d your_database -c "\dt job_runs export_jobs ai_tasks documents"

Actions :

  • Si les tables n'existent pas → Exécuter npm run migrate
  • Vérifier les indexes sont créés
  • Vérifier les contraintes sont en place

1.2 Générer les types DB​

# Générer les types depuis la DB
npm run generate:types

Actions :

  • Vérifier que job_runs, export_jobs, ai_tasks, documents sont dans database.types.ts
  • Supprimer les casts as any dans les services
  • Vérifier la compilation TypeScript

1.3 Configuration​

# Vérifier les variables d'environnement
cat .env | grep -E "QUEUE_WORKERS_ENABLED|REDIS|R2"

Actions :

  • Vérifier QUEUE_WORKERS_ENABLED=true
  • Vérifier les variables Redis (HOST, PORT, PASSWORD)
  • Vérifier les variables R2 (BUCKET_NAME, ACCOUNT_ID, ACCESS_KEY_ID, SECRET_ACCESS_KEY)

1.4 Test de démarrage​

# Démarrer le backend en mode worker
RUN_MODE=worker npm run dev

Actions :

  • Vérifier les logs : "WorkerExportModule initialized"
  • Vérifier les logs : "WorkerEmailModule initialized"
  • Vérifier les logs : "WorkerAiModule initialized"
  • Vérifier les logs : "WorkerDocModule initialized"
  • Vérifier qu'il n'y a pas d'erreurs de dépendances circulaires

Phase 2 : Tests (Aujourd'hui)​

2.1 Test export async​

# Tester un export async
curl -X GET "http://localhost:3000/api/export/async?entity=sessions&format=csv" \
  -H "Authorization: Bearer YOUR_TOKEN"

Vérifications :

  • La réponse contient jobRunId et exportJobId
  • Le job apparaît dans job_runs avec status QUEUED
  • Le worker traite le job et le complète
  • Le status passe à COMPLETED dans job_runs
  • Un file_object est créé dans R2

2.2 Test polling frontend​

  • Créer un export depuis l'UI
  • Vérifier que le polling démarre automatiquement
  • Vérifier que le statut est mis à jour en temps réel
  • Vérifier que le téléchargement fonctionne une fois terminé

Phase 3 : Améliorations (Semaine prochaine)​

3.1 OCR réel​

  • Implémenter OCR avec Tesseract.js dans DocOcrProcessor
  • Tester sur images PNG/JPG
  • Tester sur pages PDF

3.2 Dashboard de monitoring​

  • Créer une page admin pour surveiller les workers
  • Afficher les métriques (queue depth, success rate, etc.)
  • Afficher les jobs en DLQ

3.3 Tests unitaires​

  • Tests pour ExportBuildProcessor
  • Tests pour EmailSendProcessor
  • Tests pour AiRunProcessor

📋 Checklist Complète​

🔴 Urgent (Avant production)​

  • Migrations exécutées
  • Types DB générés
  • Configuration environnement vérifiée
  • Test export async end-to-end
  • Vérification que les workers démarrent

🟡 Important (Court terme)​

  • Implémenter OCR réel
  • Dashboard de monitoring basique
  • Tests unitaires pour processors critiques
  • Documentation API

🟢 Souhaitable (Long terme)​

  • Tests d'intégration complets
  • Migration progressive des endpoints existants
  • Optimisations de performance
  • Runbook opérationnel complet

🔍 Points d'Attention​

Dépendances circulaires​

  • ✅ Résolues avec forwardRef() dans WorkerExportModule
  • ⚠️ Surveiller lors de l'ajout de nouveaux workers

Types DB​

  • ⚠️ Vérifier que les types sont générés après les migrations
  • ⚠️ Supprimer les casts as any temporaires

Configuration​

  • ⚠️ QUEUE_WORKERS_ENABLED doit être true pour les workers
  • ⚠️ QUEUE_WORKERS_ENABLED peut être false pour l'API (recommandé)

Performance​

  • ⚠️ Surveiller la profondeur des queues
  • ⚠️ Configurer les retries et backoff selon les besoins
  • ⚠️ Nettoyer les jobs complétés régulièrement

📚 Documentation​

🎯 Objectif​

Objectif immédiat : Workers opérationnels en production

Actions prioritaires :

  1. Exécuter migrations
  2. Générer types
  3. Tester export async
  4. Vérifier démarrage workers

Une fois ces étapes complétées, l'architecture sera 100% opérationnelle et prête pour la production.