ronan.quintin/Keryloo

Fork 0

Workflow #14

New issue

Closed

opened 2025-12-22 21:16:08 +01:00 by ronan.quintin · 0 comments

ronan.quintin commented

2025-12-22 21:16:08 +01:00

Owner

Moteur de Workflow Métier

1. Contexte et objectifs

L’application Keryloo gère des processus métier composés de plusieurs étapes successives, déclenchées par des actions utilisateur ou système (ex. saisie d’un paiement).
Aujourd’hui, ces traitements sont :

fortement couplés au code métier,
exécutés de manière synchrone,
difficiles à faire évoluer ou enrichir.
L’objectif est de mettre en place un moteur de workflow métier transverse, basé sur des événements, permettant :
d’orchestrer des suites d’actions métier,
de gérer des règles conditionnelles,
de découpler la logique métier des actions techniques,
de rendre le système extensible et maintenable.

2. Périmètre fonctionnel

Inclus

Définition d’un moteur de workflow métier
Déclenchement de workflows via des événements métier
Exécution ordonnée d’étapes
Gestion de branchements conditionnels
Traçabilité du déroulement d’un workflow
Premier cas d’usage implémenté :
- Paiement
- Échéance
- Quittance
- Génération PDF
- Stockage en GED
  Exclu (hors périmètre immédiat)
Modélisation technique détaillée
Choix d’implémentation (framework, persistance, etc.)
Interface utilisateur de monitoring avancée
Exécution distribuée ou asynchrone avancée (Kafka, BPMN)

3. Principes fonctionnels

3.1 Séparation des responsabilités

Le moteur de workflow :

ne contient aucune logique métier
orchestre uniquement des étapes métiers atomiques
Les services métier :
exécutent une action précise
sont appelés par le workflow

3.2 Déclenchement par événement

Un workflow est déclenché par la réception d’un événement métier, par exemple :

Paiement enregistré
Quittance créée
Document généré
Un même événement peut :
déclencher un workflow,
ou être émis à l’intérieur d’un workflow pour déclencher un autre processus.

4. Concepts fonctionnels du workflow

4.1 Workflow

Un workflow représente une suite ordonnée d’étapes métiers, avec éventuellement des branchements conditionnels.
Caractéristiques fonctionnelles :

identifié par un nom
déclenché par un événement initial
composé d’étapes ordonnées
chaque étape peut produire un résultat exploitable par la suite

4.2 Étape (Step)

Une étape représente une action métier atomique.
Exemples :

Vérifier si un paiement couvre une échéance
Créer une quittance
Générer un document PDF
Stocker un document en GED
Une étape :
reçoit un contexte
exécute une action
retourne un résultat (succès, échec, données métier)

4.3 Contexte de workflow

Le contexte transporte les informations nécessaires à l’exécution du workflow :

identifiants métier (paiement, échéance, quittance…)
résultats intermédiaires
indicateurs de décision (montant suffisant, statut payé, etc.)
Le contexte est :
enrichi étape après étape
transmis à toutes les étapes du workflow

4.4 Branchement conditionnel

Le workflow peut contenir des points de décision, permettant :

de continuer,
de bifurquer,
ou de s’arrêter.
Exemples de conditions :
paiement ≥ montant attendu ?
échéance associée ?
quittance créée avec succès ?

5. Cas d’usage principal : Paiement → Quittance → GED

5.1 Événement déclencheur

Paiement enregistré
Déclenché lorsque :

un utilisateur saisit un paiement
le paiement est persisté avec succès

5.2 Description fonctionnelle du workflow

Étape 1 – Analyse du paiement
Objectif :

déterminer si le paiement est lié à une échéance
vérifier si le montant reçu est suffisant
Résultats possibles :
paiement non lié à une échéance → fin du workflow
paiement lié mais montant insuffisant → fin du workflow
paiement lié et montant suffisant → étape suivante

Étape 2 – Passage de l’échéance à l’état « payée »
Condition :

le paiement couvre totalement le montant attendu
Action :
mise à jour du statut de l’échéance
Résultat :
échéance marquée comme payée

Étape 3 – Création de la quittance
Condition :

échéance payée avec succès
Action :
création d’une quittance associée à l’échéance
Résultat :
quittance créée

Étape 4 – Génération du document PDF
Condition :

quittance créée
Action :
génération du PDF de quittance
Résultat :
document PDF généré

Étape 5 – Stockage en GED
Condition :

PDF généré
Action :
stockage du document dans la GED
versionnement si nécessaire
Résultat :
document disponible et historisé

6. Gestion de l’ordre du workflow

L’ordre d’exécution est :

déclaratif
défini par la structure du workflow
Les règles d’enchaînement sont :
séquentielles
conditionnelles
explicites
Aucune étape ne décide seule de l’étape suivante :
➡️ le workflow est responsable de l’orchestration

7. Traçabilité et audit

Chaque exécution de workflow doit permettre de retracer :

l’événement déclencheur
les étapes exécutées
les décisions prises
les erreurs éventuelles
Objectifs :
compréhension fonctionnelle
audit
débogage

8. Évolutivité attendue

Le moteur de workflow devra permettre à terme :

ajout de nouveaux workflows sans modifier l’existant
ajout d’étapes dans un workflow existant
nouveaux cas d’usage :
- communication comptable
- génération automatique de documents
- relances de paiement
- archivage légal

9. Contraintes et choix assumés

Workflow orienté métier, pas BPMN
Pas de moteur externe imposé
Pas de dépendance à une technologie distribuée
Simplicité et lisibilité privilégiées

##. 10 Impacts sur les agents Claude

Les agents backend-developer et architect doivent être modifiés pour intégrer les bonnes pratiques sur l’évent bus
Les futurs développements métier doivent s’appuyer sur le moteur d’événements et de workflows
L’agent backend-developer doit considérer l’émission d’événements lors de save/update/delete pour tout service générique

11. Livrable attendu

Implémentation du moteur de workflow
Implémentation du cas d’usage Paiement → Quittance → GED
Documentation du fonctionnement général du moteur
Documentation du premier workflow implémenté
Modification des agents claude

# Moteur de Workflow Métier ## 1. Contexte et objectifs L’application Keryloo gère des processus métier composés de plusieurs étapes successives, déclenchées par des actions utilisateur ou système (ex. saisie d’un paiement). Aujourd’hui, ces traitements sont : - fortement couplés au code métier, - exécutés de manière synchrone, - difficiles à faire évoluer ou enrichir. L’objectif est de mettre en place un moteur de workflow métier transverse, basé sur des événements, permettant : - d’orchestrer des suites d’actions métier, - de gérer des règles conditionnelles, - de découpler la logique métier des actions techniques, - de rendre le système extensible et maintenable. ## 2. Périmètre fonctionnel Inclus - Définition d’un moteur de workflow métier - Déclenchement de workflows via des événements métier - Exécution ordonnée d’étapes - Gestion de branchements conditionnels - Traçabilité du déroulement d’un workflow - Premier cas d’usage implémenté : - Paiement - Échéance - Quittance - Génération PDF - Stockage en GED Exclu (hors périmètre immédiat) - Modélisation technique détaillée - Choix d’implémentation (framework, persistance, etc.) - Interface utilisateur de monitoring avancée - Exécution distribuée ou asynchrone avancée (Kafka, BPMN) ## 3. Principes fonctionnels ### 3.1 Séparation des responsabilités Le moteur de workflow : - ne contient aucune logique métier - orchestre uniquement des étapes métiers atomiques Les services métier : - exécutent une action précise - sont appelés par le workflow ### 3.2 Déclenchement par événement Un workflow est déclenché par la réception d’un événement métier, par exemple : - Paiement enregistré - Quittance créée - Document généré Un même événement peut : - déclencher un workflow, - ou être émis à l’intérieur d’un workflow pour déclencher un autre processus. ## 4. Concepts fonctionnels du workflow ### 4.1 Workflow Un workflow représente une suite ordonnée d’étapes métiers, avec éventuellement des branchements conditionnels. Caractéristiques fonctionnelles : - identifié par un nom - déclenché par un événement initial - composé d’étapes ordonnées - chaque étape peut produire un résultat exploitable par la suite ### 4.2 Étape (Step) Une étape représente une action métier atomique. Exemples : - Vérifier si un paiement couvre une échéance - Créer une quittance - Générer un document PDF - Stocker un document en GED Une étape : - reçoit un contexte - exécute une action - retourne un résultat (succès, échec, données métier) ### 4.3 Contexte de workflow Le contexte transporte les informations nécessaires à l’exécution du workflow : - identifiants métier (paiement, échéance, quittance…) - résultats intermédiaires - indicateurs de décision (montant suffisant, statut payé, etc.) Le contexte est : - enrichi étape après étape - transmis à toutes les étapes du workflow ### 4.4 Branchement conditionnel Le workflow peut contenir des points de décision, permettant : - de continuer, - de bifurquer, - ou de s’arrêter. Exemples de conditions : - paiement ≥ montant attendu ? - échéance associée ? - quittance créée avec succès ? ## 5. Cas d’usage principal : Paiement → Quittance → GED ### 5.1 Événement déclencheur Paiement enregistré Déclenché lorsque : - un utilisateur saisit un paiement - le paiement est persisté avec succès ### 5.2 Description fonctionnelle du workflow **Étape 1** – Analyse du paiement Objectif : - déterminer si le paiement est lié à une échéance - vérifier si le montant reçu est suffisant Résultats possibles : - paiement non lié à une échéance → fin du workflow - paiement lié mais montant insuffisant → fin du workflow - paiement lié et montant suffisant → étape suivante **Étape 2** – Passage de l’échéance à l’état « payée » Condition : - le paiement couvre totalement le montant attendu Action : - mise à jour du statut de l’échéance Résultat : - échéance marquée comme payée **Étape 3** – Création de la quittance Condition : - échéance payée avec succès Action : - création d’une quittance associée à l’échéance Résultat : - quittance créée **Étape 4** – Génération du document PDF Condition : - quittance créée Action : - génération du PDF de quittance Résultat : - document PDF généré **Étape 5** – Stockage en GED Condition : - PDF généré Action : - stockage du document dans la GED - versionnement si nécessaire Résultat : - document disponible et historisé ## 6. Gestion de l’ordre du workflow L’ordre d’exécution est : - déclaratif - défini par la structure du workflow Les règles d’enchaînement sont : - séquentielles - conditionnelles - explicites Aucune étape ne décide seule de l’étape suivante : ➡️ le workflow est responsable de l’orchestration ## 7. Traçabilité et audit Chaque exécution de workflow doit permettre de retracer : - l’événement déclencheur - les étapes exécutées - les décisions prises - les erreurs éventuelles Objectifs : - compréhension fonctionnelle - audit - débogage ## 8. Évolutivité attendue Le moteur de workflow devra permettre à terme : - ajout de nouveaux workflows sans modifier l’existant - ajout d’étapes dans un workflow existant - nouveaux cas d’usage : - communication comptable - génération automatique de documents - relances de paiement - archivage légal ## 9. Contraintes et choix assumés - Workflow orienté métier, pas BPMN - Pas de moteur externe imposé - Pas de dépendance à une technologie distribuée - Simplicité et lisibilité privilégiées ##. 10 Impacts sur les agents Claude - Les agents `backend-developer` et `architect` doivent être **modifiés pour intégrer les bonnes pratiques sur l’évent bus** - Les futurs développements métier doivent **s’appuyer sur le moteur d’événements et de workflows** - L’agent `backend-developer` doit considérer l’**émission d’événements lors de save/update/delete** pour tout service générique ## 11. Livrable attendu - Implémentation du moteur de workflow - Implémentation du cas d’usage Paiement → Quittance → GED - Documentation du fonctionnement général du moteur - Documentation du premier workflow implémenté - Modification des agents claude