Diagramme d'etats-transitions - Commande

Phase UML : P1 - Conception, complement UML (apres MCD) Statut : v0.2 - prod-like, machine a 4 etats Date : 2026-06-11 Branche : feat/p1-conception Auteur methodologie : BYAN

1. Objet du document

Ce document formalise la machine a etats de l'attribut customer_order.status. Il decrit les etats possibles d'une commande, les transitions autorisees entre ces etats, les evenements qui les declenchent et les gardes (conditions) qui les conditionnent.

Il complete le MCD (docs/merise/mcd.md, cycle de vie de la commande), le dictionnaire (docs/merise/dictionary.md 3.10, qui declare l'ENUM status) et le MCT (docs/merise/mct.md section 13, qui resume les transitions par operation).

2. Source de verite et regle metier

Le modele v0.2 (prod-like) reduit la machine a quatre etats. La regle metier distingue la composition payee de la remise : une commande est creee et payee en une operation atomique (la saisie du numero de retrait tient lieu de paiement dans le cadre RNCP), puis elle est remise au client en un geste unique.

Source	Valeurs de statut
`dictionary.md` 3.10 (ENUM SQL)	`pending_payment`, `paid`, `delivered`, `cancelled`
`mct.md` section 13 (transitions)	creer+payer -> remettre, annulation depuis tout etat non terminal

Le dictionnaire (dictionary.md 3.10) et la machine ci-dessous partagent la meme ENUM a 4 valeurs, ce qui maintient la coherence entre le modele de donnees et le modele d'etats (cross-validation, mantra #34).

Etats supprimes par rapport au v0.1 : preparing et ready. En contexte fast-food, l'affichage cuisine (KDS) est un dispositif visuel : l'equipier lit le ticket et agit. Ces deux etats intermediaires ajoutaient des transitions sans valeur metier proportionnelle. La cuisine est en lecture seule ; la remise (DELIVER_ORDER) est le geste unique qui fait avancer le statut. Le KPI est le temps total delivered_at - paid_at (SLA ~10 min) ; la couleur du KDS est calculee a l'affichage depuis now - paid_at, sans etat stocke supplementaire.

3. Etats retenus

Etat	Valeur ENUM	Signification	Acteur qui declenche l'entree
En attente de paiement	`pending_payment`	Etat initial transitoire : commande composee, en attente de paiement. Non observable hors transaction (voir section 7).	Client (kiosk) ou Counter/Drive (back-office)
Payee	`paid`	Paiement effectue ; la commande entre en file de preparation (lecture seule cuisine).	Client (kiosk) ou Counter/Drive
Livree	`delivered`	Remise effectuee au client. Etat final.	Counter ou Drive
Annulee	`cancelled`	Commande abandonnee ou annulee avant remise. Etat final.	Counter, Drive ou Admin

pending_payment est l'etat par defaut a l'INSERT (dictionary.md 3.10), mais la transition vers paid est realisee dans la meme transaction que la creation (operations CREATE_ORDER / CREATE_COUNTER_ORDER du MCT). Il est donc conserve dans l'ENUM pour la lisibilite du cycle et pour laisser la porte ouverte a un paiement reel ulterieur sans migration destructive.

4. Diagramme d'etats-transitions

stateDiagram-v2
    [*] --> pending_payment : creer la commande (kiosk / counter / drive)

    pending_payment --> paid : payer\n[atomique dans CREATE_ORDER / CREATE_COUNTER_ORDER\nsaisie du numero = substitut de paiement]
    pending_payment --> cancelled : annuler\n[avant remise]

    paid --> delivered : remettre au client\n[acteur Counter / Drive, geste unique]
    paid --> cancelled : annuler\n[Counter / Drive / Admin, re-credit du stock]

    delivered --> [*]
    cancelled --> [*]

5. Transitions detaillees

#	De	Vers	Evenement declencheur	Garde (condition)	Acteur
T1	(initial)	`pending_payment`	Creation de la commande composee	Au moins une ligne (`order_item`) ; numero de retrait non vide	Client / Counter / Drive
T2	`pending_payment`	`paid`	Paiement (atomique a la creation)	La commande contient au moins une `order_item` ; decrement du stock et insert dans la meme transaction	Client / Counter / Drive
T3	`pending_payment`	`cancelled`	Abandon avant paiement	Commande pas encore payee	Counter / Drive / Admin
T4	`paid`	`delivered`	Remise physique au client	La commande est `paid` ; l'acteur detient `order.deliver` ; source compatible avec son role (`role_visible_source`)	Counter / Drive
T5	`paid`	`cancelled`	Annulation avant remise	L'acteur detient `order.cancel` ; le stock consomme est re-credite (`stock_movement` type `cancellation`)	Counter / Drive / Admin

Invariants de la machine a etats

delivered et cancelled sont des etats finaux : aucune transition n'en sort.
Aucune transition ne revient en arriere. Une erreur operationnelle se traite par annulation puis nouvelle commande, pour preserver l'integrite de l'historique et des snapshots (label_snapshot, unit_price_cents_snapshot, vat_rate_snapshot sur order_item).
La transition vers cancelled est possible depuis pending_payment et paid, mais pas depuis delivered (une commande remise ne s'annule pas dans ce modele). Coherent avec mct.md 7.1 (CANCEL_ORDER).
paid_at (DATETIME, dictionary.md 3.10) est renseigne a la transition T2. delivered_at est renseigne a T4. cancelled_at est renseigne a T3/T5. Les trois colonnes sont NULL tant que la transition correspondante n'a pas eu lieu.
La cuisine (kitchen) ne declenche aucune transition : son acces a la file des commandes paid est en lecture seule (mct.md 5.1, LIST_ORDERS_DISPLAY).

6. Coherence avec les autres livrables

Verification	Resultat
Tous les etats du diagramme existent dans l'ENUM `dictionary.md` 3.10	Oui (4 valeurs, toutes utilisees)
La regle "annulation possible sauf depuis delivered" de `mct.md` 7.1	Respectee (T3, T5 ; pas de transition depuis `delivered`)
Transition `paid -> delivered` en geste unique de `mct.md` 6.1	Couvert par T4 (`DELIVER_ORDER`)
Atomicite `pending_payment -> paid` de `mct.md` 3.3 / 4.1 / section 13	Couvert par T2 (saisie du numero = substitut de paiement)
Acteurs de `use-cases.md`	Counter/Drive declenchent T4/T5 ; Admin peut annuler (T3/T5) ; Kitchen en lecture seule
Timestamps de phase `paid_at` / `delivered_at` / `cancelled_at`	Renseignes a T2 / T4 / T3-T5

7. Arbitrage tranche

La machine retenue est reduite a quatre etats (Decision 4, docs/notes/revue-alignement-p1.md section 7) :

pending_payment -> paid -> delivered
        |            |
        +------------+--------> cancelled (depuis pending_payment ou paid)

Note sur la transition pending_payment -> paid : dans le cadre RNCP, le paiement est remplace par la saisie du numero de commande (kiosk) ou par la validation de l'equipier (counter/drive). La transition est atomique dans CREATE_ORDER et CREATE_COUNTER_ORDER : le statut pending_payment n'est pas observable en dehors de la transaction de creation. Il reste declare dans l'ENUM pour exprimer le cycle de vie complet et pour autoriser un paiement reel ulterieur (cout d'une valeur d'ENUM).

Les etats preparing et ready du v0.1 sont supprimes : la cuisine est un affichage visuel en lecture seule, et la remise fusionne preparation+remise en un geste unique (DELIVER_ORDER). Effet de bord propage : les operations MARK_IN_PREPARATION et MARK_READY disparaissent du MCT (voir mct.md sections 1 et 13).

7.5 KiB Raw Blame History