Wiki/docs/10-state-diagrams.md

State Diagrams — Cycle de vie des entites

Vue dynamique des entites du domaine. Scope B (CFA + Agence). Methodologie : UML state machine.

1. Pourquoi des state diagrams

Les enums *_statut du MCD ne disent pas quelles transitions sont autorisees. Un cycle de vie explicite :

• Donne une regle de gestion claire (RG-XX par transition)
• Sert de spec UI (boutons disponibles selon l'etat)
• Aide la validation metier
• Sert de checklist pour les tests

Section CFA

2. FORMATION

stateDiagram-v2
    [*] --> draft : Creer formation

    draft --> actif : Activer (au moins 1 bloc + 1 module)
    draft --> archive : Annuler avant lancement

    actif --> termine : Date fin atteinte ET tous modules realises
    actif --> archive : Annulation justifiee

    termine --> archive : Archiver retention reglementaire

    archive --> [*]

• RG-FORMATION-01 : draft → actif autorise uniquement si au moins 1 bloc avec au moins 1 module.
• RG-FORMATION-02 : actif → termine automatique si formation_date_fin <= NOW() ET tous les modules en realise ou annule.

3. MODULE

stateDiagram-v2
    [*] --> a_attribuer : Creer module

    a_attribuer --> attribue : Premiere attribution creee
    a_attribuer --> annule : Module supprime

    attribue --> en_cours : Date debut formation atteinte
    attribue --> a_attribuer : Toutes attributions annulees
    attribue --> annule

    en_cours --> realise : Toutes heures realisees OU date fin
    en_cours --> annule

    realise --> [*]
    annule --> [*]

4. ATTRIBUTION (Module-Personne formateur)

stateDiagram-v2
    [*] --> planifie : Admin attribue module

    planifie --> en_cours : Date debut OU formateur demarre
    planifie --> annule

    en_cours --> realise : Formateur saisit heures et confirme
    en_cours --> annule

    realise --> [*]
    annule --> [*]

Section AGENCE

5. CLIENT

stateDiagram-v2
    [*] --> prospect : Premier contact

    prospect --> actif : Devis signe
    prospect --> archive : Pas de suite

    actif --> inactif : Pas de projet en cours
    inactif --> actif : Reactivation

    actif --> archive : Cessation activite
    inactif --> archive : Idem

    archive --> [*]

• RG-CLIENT-01 : Suppression interdite tant que projet_statut != cloture/abandonne exists.

6. PROJET

stateDiagram-v2
    [*] --> devis : Demande client recue

    devis --> en_cours : Devis signe et facture
    devis --> abandonne : Pas de suite client

    en_cours --> livre : Tous livrables/taches done
    en_cours --> abandonne : Annulation client ou impossibilite

    livre --> cloture : Validation client + facture finale
    livre --> en_cours : Reouverture pour corrections

    cloture --> [*]
    abandonne --> [*]

• RG-PROJET-01 : devis → en_cours necessite signature client (champ projet_date_debut rempli).
• RG-PROJET-02 : en_cours → livre automatique quand toutes les taches sont en done.

7. TACHE

stateDiagram-v2
    [*] --> todo : Creer tache

    todo --> in_progress : Dev demarre
    todo --> abandoned : Tache annulee

    in_progress --> review : Dev marque pret pour review
    in_progress --> abandoned

    review --> done : Admin valide
    review --> in_progress : Demande revisions

    done --> [*]
    abandoned --> [*]

• RG-TACHE-01 : review est optionnel (workflow facultatif). Pour les petites taches, in_progress → done direct possible.

8. INTERVENTION (Tache-Personne developpeur)

stateDiagram-v2
    [*] --> planifie : Intervention prevue (rare)
    [*] --> realise : Saisie a posteriori (cas standard)

    planifie --> realise : Dev confirme execution
    planifie --> annule

    realise --> annule : Annulation justifiee (rare)

    realise --> [*]
    annule --> [*]

Note : la plupart des INTERVENTIONS sont saisies a posteriori (dev fait le travail, puis loggue les heures). Le statut planifie est rare, utilise pour reservations bloquantes.

Section COMMUNS

9. PERSONNE

stateDiagram-v2
    [*] --> actif : Embauche / arrivee

    actif --> inactif : Depart, suspension, vacances longues

    inactif --> actif : Retour

    inactif --> [*] : Suppression\n(interdite si attributions/interventions actives)

• RG-PERSONNE-05 : actif → inactif autorise meme avec attributions/interventions actives, mais bloque les nouvelles assignations.
• RG-PERSONNE-06 : Suppression interdite si personne_id existe dans ATTRIBUTION ou INTERVENTION non-annule (FK ON DELETE RESTRICT).

Synthese

Entite	Etats	Evenements declencheurs
FORMATION	draft, actif, termine, archive	Creation, activation, date fin, archivage
BLOC	(sans cycle propre)	suit la formation
MODULE	a_attribuer, attribue, en_cours, realise, annule	Attribution, demarrage, completion, annulation
ATTRIBUTION	planifie, en_cours, realise, annule	Attribution, demarrage, saisie heures, annulation
CLIENT	prospect, actif, inactif, archive	Devis signe, projets actifs, cessation
PROJET	devis, en_cours, livre, cloture, abandonne	Signature, livraison, validation client, annulation
TACHE	todo, in_progress, review, done, abandoned	Demarrage, soumission review, validation, annulation
INTERVENTION	planifie, realise, annule	Saisie a posteriori (cas standard), annulation rare
PERSONNE	actif, inactif	Embauche, depart, retour

Implementation

Niveau	Implementation
MLD	Champs *_statut typed ENUM avec valeurs limitees
MPD Baserow	Single select avec options exactement = etats
Logique transition	Bridge service : valide les transitions autorisees, refuse les illegales
UI	Boutons d'action conditionnels selon etat courant
Audit	Log par transition (entity_id, from_state, to_state, by_user, at_timestamp, reason)
Auto	Cron horaire pour transitions auto (date fin → termine, etc.)

Questions ouvertes

• Faut-il un audit log explicite des transitions (qui a annule quoi quand) ? Probable oui pour Qualiopi.
• Les automatisations de transition doivent-elles tourner en cron, en webhook Baserow, ou a la lecture (lazy) ?
• Faut-il un etat en_validation entre realise et "facture client" pour PROJET (workflow de validation comptable) ?