Aller au contenu principal

Revue Brique Workflows (UX + Moteur + Exploitation)

Dernière mise à jour: 2026-02-09

Objectif​

Rendre la brique workflows:

  • plus simple à configurer (moins d'erreurs de setup),
  • plus fiable en exécution (idempotence, retries, visibilité),
  • plus exploitable en production (debug, incidents, monitoring, audit).

Etat actuel (constat)​

Frontend​

  • Module workflows existant avec édition phases/tâches (WorkflowFormPage, WorkflowVisualEditor).
  • Gestion des triggers disponible (WorkflowTriggersList, WorkflowTriggerForm).
  • UX puissante mais dense (beaucoup d'options sans guidage progressif).

Backend​

  • Architecture découpée (services workflows-*, workflow-triggers, workflow-tasks-*).
  • Scheduler et exécution des workflow tasks en place.
  • Notifications sessions déjà unifiées dans la brique workflows.

Exploitation​

  • Observabilité en place globalement (Prometheus/Grafana), mais pas encore centrée workflow.
  • Peu de visibilité produit sur "pourquoi un trigger n'a pas match" ou "pourquoi une task a échoué".

Problèmes prioritaires​

  1. Complexité de configuration:
  • Trop de liberté sans garde-fous dans l'éditeur.
  • Risque de workflows valides techniquement mais inutiles métier.
  1. Manque de simulation:
  • Pas de "dry-run" lisible avant activation.
  • Difficile de prédire les impacts en production.
  1. Exécution opaque:
  • Peu d'outils UI pour inspecter les runs, retries, erreurs par workflow.
  1. Dette UX:
  • Formulaires longs, navigation et feedback limités.
  • Pas de mode "template rapide" pour les cas standards.

Plan d'implémentation (ordre recommandé)​

Lot 0 - Reset de l'existant (obligatoire, 1 jour)​

Objectif:

  • Supprimer les donnees workflows actuelles et repartir sur une base vide avec le schema Workflow V2.
  • Eviter de maintenir des scripts d'audit/repair transitoires.

0.1 Purge data (clean slate)​

  • Appliquer une migration dediee de purge (0174_workflow_v2_reset_data):
    • nullification des references workflows dans sessions, lead_forms, user_session_types,
    • suppression des donnees workflows/runtime (workflows, workflow_phases, workflow_tasks, workflow_task_actions, workflow_triggers, workflow_trigger_executions, session_workflow_instances, session_workflow_task_runs, session_workflow_action_runs).

0.2 Nettoyage code temporaire​

  • Supprimer les scripts et endpoints admin lies a l'audit/repair/reports.
  • Supprimer le panneau admin et les hooks frontend relies a la lecture de rapports.

0.3 Definition of Done Lot 0​

  • 0 script workflow:audit / workflow:repair dans le backend.
  • 0 endpoint API workflows/reports.
  • 0 carte admin "Workflow reports".
  • Donnees workflows reparties d'un etat vide apres migration de reset.

Sprint 1 - Quick Wins UX (2-3 jours)​

  • Ajouter un mode "Basic" vs "Advanced" dans l'éditeur workflow.
  • Ajouter des validations bloquantes:
    • phase sans tâche,
    • trigger actif sans conditions minimales,
    • action automatique sans paramètres requis.
  • Ajouter une section "Résumé avant sauvegarde":
    • nb phases, nb tâches auto/manuelles, triggers actifs.
  • Ajouter un démarrage guidé avec starters prêts à l'emploi (préremplissage phases+tâches).

Sprint 2 - Simulation & Safety Net (3-4 jours)​

  • Ajouter endpoint de simulation:
    • POST /api/workflows/:workflowId/simulate
    • input: contexte session/contact/devis/facture.
    • output: triggers matchés, tâches qui seraient créées/exécutées.
  • Ajouter bouton frontend "Tester ce workflow".
  • Ajouter warning avant activation si simulation vide ou ambiguë.

Avancement (2026-02-09)​

  • ✅ Endpoint dry-run v1 implémenté (POST /api/workflows/:id/simulate)
    • évaluation des triggers (match event + conditions),
    • preview des tâches qui seraient planifiées selon le statut simulé,
    • warnings sur tâches automatiques incomplètes (templates manquants).
  • ✅ Bouton frontend "Test workflow" sur la page d'édition avec résumé immédiat.
  • ✅ Garde-fou runtime d'activation: impossible d'activer un trigger si le workflow est invalide (workflow phases/tasks/templates).
  • ✅ Endpoint de validation activable par UI: GET /api/workflows/:id/activation-validation.
  • ✅ Safety net post-édition: si un workflow devient invalide après update, les triggers actifs sont auto-désactivés.
  • ✅ UI Trigger panel durcie: sections actifs/inactifs, labels i18n harmonisés, formulaire allégé.
  • ✅ Test workflow guidé: scénarios de simulation prédéfinis + option inclure inactifs.
  • ✅ Démarrage guidé création workflow: starters préconfigurés (session follow-up, relance devis, livraison+avis).
  • ✅ Vue "Flow" en mode avancé: canvas lisible phases→tâches (switch Builder/Flow).
  • ✅ Flow cliquable: clic phase/tâche dans le canvas -> retour Builder + focus visuel sur l'élément.
  • ✅ Quick actions canvas: ouvrir, ajouter tâche, dupliquer phase.
  • ✅ Edition inline canvas: renommer phase + modifier description de tâche sans quitter Flow.
  • ✅ Réordonnancement phases directement en vue Flow (drag & drop horizontal).
  • ✅ Signal qualité dans le Flow: badge statut par phase/tâche (OK/Bloquant) + mini résumé simulation intégré au canvas.
  • ✅ UX Flow améliorée: le mode Flow reste actif avec un panneau de détails latéral (édition de phase/tâches sans retour forcé au Builder).
  • ✅ Refonte visuelle Flow en mode "étapes + liens d'exécution" (pipeline plus lisible, actions compactes, focus UX).

Sprint 3 - Observabilité Workflow-Centric (3-4 jours)​

  • Ajouter mini-dashboard workflow:
    • triggers évalués,
    • matches,
    • tasks créées,
    • tasks failed (24h/7j).
  • Ajouter timeline d'exécution par workflow (derniers runs + erreurs).
  • Standardiser les logs structurés par workflowId, triggerId, taskId, sessionId.

Sprint 4 - Templates & Industrialisation (3-5 jours)​

  • Bibliotheque de templates workflow (mariage, portrait, corporate, etc.).
  • Assistant de création "template -> personnalisation -> activation".
  • Import/export JSON de workflow (versionné).

Sprint 4.1 - Flows par defaut en base​

  • Ajouter des templates par defaut versionnes en base (seed idempotent):
    • lead_followup_basic,
    • quote_followup,
    • invoice_payment_reminder,
    • session_preparation,
    • session_post_feedback,
    • inactive_contact_reactivation.
  • Chaque template doit contenir:
    • trigger,
    • phases ordonnees,
    • taches preconfigurees,
    • metadonnees (slug, category, version, is_default).
  • Strategie de mise a jour:
    • nouvelle version ajoutee sans casser les instances existantes,
    • option UI "mettre a niveau" pour les workflows issus d'un template.

Definition of Done (lot "workflow review")​

  • Lot 0 execute et valide avant extension fonctionnelle.
  • Création/édition guidée avec moins d'erreurs de config.
  • Simulation disponible avant activation.
  • Visibilité production sur exécution/erreurs workflow.
  • Templates prêts pour les cas métier principaux.
  • Documentation opérationnelle mise à jour.

Fichiers cibles (implémentation)​

  • Frontend:
    • frontend/src/pages/workflows/WorkflowsPage/WorkflowFormPage.tsx
    • frontend/src/pages/workflows/WorkflowsPage/components/WorkflowVisualEditor.tsx
    • frontend/src/pages/workflows/WorkflowsPage/components/WorkflowTriggersList.tsx
  • Backend:
    • backend/src/workflows/workflows.controller.ts
    • backend/src/workflows/workflow-triggers.service.ts
    • backend/src/workflow-tasks/workflow-tasks-execution.service.ts
    • backend/src/workflow-tasks/workflow-tasks-query.service.ts

Notes​

  • Prioriser Sprint 1 + Sprint 2 avant toute extension fonctionnelle.
  • Garder la compatibilité avec les workflows existants (pas de breaking change).