# 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

```mermaid
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

```mermaid
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)

```mermaid
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

```mermaid
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

```mermaid
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

```mermaid
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)

```mermaid
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

```mermaid
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) ?