corentin_wakdo/docs/uml/sequence-passer-commande.md

Diagramme de sequence - Passer une commande (borne client)

Phase UML : P1 - Conception, complement UML (apres MCD) Statut : v0.1 Date : 2026-05-21 Branche : feat/p1-conception Auteur methodologie : BYAN

---

1. Objet du document

Ce document decrit le flux temporel du parcours "passer une commande" cote Client sur la borne kiosk : navigation dans les categories, selection d'un produit ou composition d'un menu, gestion du panier, validation avec saisie du numero de retrait, paiement, puis confirmation.

Le diagramme reste au niveau conceptuel / logique. Il nomme les echanges entre participants sans detailler l'implementation PHP (controllers, models) ni le SQL exact. Il complete le cas d'utilisation "Passer une commande" de docs/uml/use-cases.md et la machine a etats de docs/uml/state-commande.md.

Sources :

• docs/PROJECT_CONTEXT.md section 2 (processus metier), section 7 (endpoints API)
• docs/merise/dictionary.md (commande, ligne_commande, menu, produit)
• docs/uml/state-commande.md (transitions pending_payment -> paid)

---

2. Participants

Participant	Role	Couche
Client	Utilisateur final, compose sa commande au doigt	Acteur
Borne	Interface tactile (front Bloc 1, HTML/CSS/JS vanilla)	Presentation
API	Back-end REST sous /api/* (Bloc 2)	Application
BDD	Base de donnees MariaDB	Persistance

Le panier est gere cote Borne (etat local du front) jusqu'a la validation. Aucune commande n'est creee en base avant la validation finale, pour eviter les commandes fantomes abandonnees.

---

3. Diagramme de sequence

sequenceDiagram
    actor Client
    participant Borne
    participant API
    participant BDD

    Note over Client,BDD: Phase 1 - Navigation du catalogue

    Client->>Borne: ouvrir la borne
    Borne->>API: GET /api/categories
    API->>BDD: lire les categories actives
    BDD-->>API: liste des categories
    API-->>Borne: categories (JSON)
    Borne-->>Client: afficher les categories

    Client->>Borne: choisir une categorie
    Borne->>API: GET /api/products (filtre categorie)
    API->>BDD: lire les produits disponibles
    BDD-->>API: liste des produits
    API-->>Borne: produits (JSON)
    Borne-->>Client: afficher les produits

    Note over Client,BDD: Phase 2 - Selection produit ou composition menu

    alt Produit a la carte
        Client->>Borne: selectionner un produit
        Client->>Borne: regler taille / options
        Borne->>Borne: ajouter la ligne au panier local
    else Composition d'un menu
        Client->>Borne: selectionner un menu
        Borne->>API: GET /api/menus (composition du menu)
        API->>BDD: lire menu et composition
        BDD-->>API: menu + produits par role
        API-->>Borne: composition (JSON)
        Borne-->>Client: afficher les choix par slot (burger, accompagnement, boisson, sauce)
        Client->>Borne: choisir chaque composant + tailles
        Borne->>Borne: ajouter la ligne menu au panier local
    end

    Note over Client,BDD: Phase 3 - Gestion du panier

    Client->>Borne: consulter le panier
    Borne-->>Client: recapitulatif + total provisoire
    opt Modifier le panier
        Client->>Borne: ajuster quantite / supprimer une ligne
        Borne->>Borne: recalculer le total local
        Borne-->>Client: panier mis a jour
    end

    Note over Client,BDD: Phase 4 - Validation du panier et saisie du numero

    Client->>Borne: valider la commande
    Client->>Borne: saisir le numero de retrait
    Borne->>Borne: valider le panier (au moins 1 ligne)
    Borne->>API: POST /api/orders (lignes + mode_consommation + numero)

    API->>API: recalculer les totaux cote serveur
    API->>BDD: creer la commande (statut pending_payment)
    API->>BDD: creer les lignes (snapshot libelle + prix)
    BDD-->>API: commande persistee {id, numero, statut: pending_payment}
    API-->>Borne: 201 Created {id, numero, statut: pending_payment, total}
    Borne-->>Client: afficher le total a regler

    Note over Client,BDD: Phase 5 - Paiement (pending_payment -> paid)

    Client->>Borne: payer la commande
    Borne->>API: POST /api/orders/{id}/pay
    API->>BDD: enregistrer le paiement, passer la commande a paid (paye_a)
    BDD-->>API: commande mise a jour {id, numero, statut: paid}

    Note over Client,BDD: Phase 6 - Confirmation

    API-->>Borne: 200 OK {id, numero, statut: paid}
    Borne-->>Client: ecran de confirmation avec le numero

    Note over Client,BDD: Cas d'erreur

    alt Panier vide ou donnees invalides
        API-->>Borne: 4xx {error: code, message}
        Borne-->>Client: message d'erreur, retour au panier
    end

---

4. Notes de modelisation

4.1 Recalcul des totaux cote serveur

La Borne affiche un total provisoire calcule localement pour l'experience utilisateur. L'API recalcule les totaux a la reception du POST /api/orders a partir des prix en base, puis fige les snapshots (prix_unitaire_ttc_cents_snapshot, libelle_snapshot dans ligne_commande, voir dictionary.md 3.6). Le total affiche par le client n'est pas considere comme la source de verite : ceci limite la falsification du prix cote client.

4.2 Transitions de statut

Le parcours materialise les transitions T1 et T2 de docs/uml/state-commande.md, en deux phases successives conformes a la regle metier :

• POST /api/orders cree la commande composee en pending_payment (T1).
• POST /api/orders/{id}/pay enregistre le paiement et fait passer la commande a paid (T2), avec l'horodatage paye_a.

La separation des deux appels reflete les deux phases du cycle de vie : composer la commande, puis la payer.

4.3 Panier local jusqu'a la validation

Aucun appel ecriture vers la BDD n'a lieu pendant les phases 1 a 3. Le panier vit dans l'etat du front (JavaScript). Ce choix evite de creer en base des commandes abandonnees et reduit le nombre d'ecritures. Inconvenient connu : un rafraichissement de la borne peut vider le panier ; un stockage local cote navigateur peut etre envisage plus tard.

4.4 Fallback JSON (hors flux nominal)

PROJECT_CONTEXT.md section 4 prevoit un mode de repli ou la Borne lit des fichiers JSON statiques si l'API est indisponible. Ce mode concerne uniquement les lectures (phases 1 a 2). La validation (phase 4) et le paiement (phase 5) requierent l'API ; sans elle, la commande n'est ni persistee ni payee. Ce cas degrade n'est pas detaille dans le diagramme nominal ci-dessus.

---

5. Coherence avec les autres livrables

Verification	Resultat
Endpoints utilises existent dans PROJECT_CONTEXT.md section 7	GET /api/categories, GET /api/products, GET /api/menus, POST /api/orders ; POST /api/orders/{id}/pay est a confirmer en section 7 du brief
Entites manipulees presentes au MCD	Oui : categorie, produit, menu, menu_produit, commande, ligne_commande
Statuts utilises coherents avec state-commande.md	Oui : pending_payment puis paid (T1, T2), valeurs ENUM anglaises
Format de reponse JSON	Coherent avec PROJECT_CONTEXT.md section 7 ({data, error}) et la reponse {id, number, status} du POST orders

---

6. Arbitrage tranche

La phase de paiement est integree au flux conformement a la regle metier des deux phases (composer puis payer). La sequence suit la machine canonique de state-commande.md : creation en pending_payment (T1) puis paiement vers paid (T2), avec des valeurs ENUM en anglais. Point a confirmer au MCT : l'endpoint de paiement (POST /api/orders/{id}/pay) doit etre reporte dans la section 7 du brief s'il n'y figure pas encore.