Aller au contenu principal

Checklist d’implémentation — refacto structure backend

Objectif : découper le travail en PRs petites, sûres, et testables, en priorité sur la structure NestJS (API vs Worker), la queue, et la prévention des cycles DI.

Référence plan : docs/BACKEND_STRUCTURE_IMPROVEMENT_PLAN.md.

PR 0 — Préparation / garde-fous (smoke tests boot)​

  • But : empêcher toute régression “NestFactory.create() pend”.
  • Changements
    • Ajouter un boot-check exécuté sur code compilé (fiable pour Nest) :
      • API : createApplicationContext(AppModule) puis close()
      • Worker : createApplicationContext(WorkerModule) puis close()
  • Fichiers
    • backend/src/scripts/boot-check.ts
  • Critère d’acceptation
    • CI échoue si cycle DI / provider manquant.

PR 1 — Queue : séparer enqueue vs process (QueueClientModule / QueueWorkerModule)​

  • But : clarifier “API enqueues / Worker processes” au niveau module, pas juste via env vars.
  • Changements
    • Créer QueueCoreModule : BullMQ connection + registerQueue + QueueService (enqueue/status).
    • Créer QueueClientModule (API) : QueueCoreModule + progress via WebSocket.
    • Créer QueueWorkerModule (Worker) : QueueCoreModule + processors base + progress no-op.
    • QueueRuntimeModule choisit quel module importer selon QUEUE_ENABLED et QUEUE_WORKERS_ENABLED.
  • Fichiers (suggestion)
    • backend/src/queue/queue-core.module.ts
    • backend/src/queue/queue-client.module.ts
    • backend/src/queue/queue-worker.module.ts
    • backend/src/queue/queue-runtime.module.ts
  • Critère d’acceptation
    • API démarre avec QUEUE_ENABLED=true et QUEUE_WORKERS_ENABLED=false sans instancier de processors.
    • Worker démarre avec QUEUE_WORKERS_ENABLED=true et exécute les processors.

PR 2 — AppModule “thin” : extraire ApiModule​

  • But : rendre la racine lisible et réduire le risque de régressions lors de refacto.
  • Changements
    • Créer ApiModule (imports + controllers HTTP).
    • AppModule garde uniquement :
      • runtime modules (EventEmitterRuntimeModule, ScheduleRuntimeModule si créé)
      • infra global (ConfigModule, LoggerModule, DbModule, CacheModule, TimeoutModule, etc.)
      • ApiModule
  • Fichiers (suggestion)
    • backend/src/api.module.ts (nouveau)
    • backend/src/app.module.ts (simplifié)
  • Critère d’acceptation
    • app.module.ts ne contient plus de logique de “segmentation debug” type BOOTSTRAP_GROUPS.

PR 3 — WorkerModule : minimiser encore (enlever WebSocket si possible)​

  • But : réduire boot time + mémoire du worker.
  • Changements
    • Vérifier si les processors ont réellement besoin de WebSocketModule.
    • Si besoin “progress events”, passer par un provider dédié plus léger (ex: “QueueProgressEmitter”) ou rendre l’émetteur optionnel.
    • Éviter d’importer des modules “full” quand un “core” suffit.
  • Critère d’acceptation
    • Worker charge un ensemble stable de modules (pas Search/Agent).
    • Les jobs progress continuent de fonctionner (ou sont explicitement documentés si désactivés côté worker).

PR 4 — Runtime modules uniformes (ScheduleRuntimeModule)​

  • But : enlever les if (process.env...) dispersés.
  • Changements
    • Créer ScheduleRuntimeModule.register() qui:
      • si SCHEDULE_ENABLED=false => n’importe rien
      • sinon => ScheduleModule.forRoot() (appel unique)
    • Remplacer la logique dans AppModule.
  • Fichiers
    • backend/src/common/schedule-runtime.module.ts (nouveau)
    • backend/src/app.module.ts (mise à jour)
  • Critère d’acceptation
    • plus aucun ScheduleModule.forRoot() ailleurs.

PR 5 — Convention DI : tokens “leaf/lookup only” + lints/guide​

  • But : prévenir les cycles DI à l’échelle du codebase.
  • Changements
    • Ajouter une section “règle DI tokens” dans docs/BACKEND.md (déjà partiellement fait).
    • (Optionnel) Ajouter un mini “checklist PR” dans docs/ROADMAP.md.
    • Auditer les tokens existants (quick scan) : tout token *_TOKEN doit pointer vers un leaf ou un lookup.
  • Critère d’acceptation
    • Les tokens ne pointent pas vers des orchestrateurs qui ré-injectent le token via leurs dépendances.

PR 6 — Config prod/dev : expliciter le worker partout (env + docs)​

  • But : cohérence dev/prod et onboarding.
  • Changements
    • .env.example : documenter RUN_MODE, QUEUE_*, SCHEDULE_ENABLED, EVENT_EMITTER_ENABLED (placeholders).
    • Vérifier que infra/docker-compose.prod.yml inclut le service worker (fait) et que la doc le mentionne.
  • Critère d’acceptation
    • Déploiement prod : jobs BullMQ sont réellement consommés.

Notes de découpage​

  • Chaque PR doit rester petite (idéalement < 400 lignes net), avec un critère de succès testable.
  • Si une PR touche “wiring” + logique métier, la découper : d’abord wiring, ensuite changements comportementaux.