corentin_wakdo/docs/merise/dictionary.md

Dictionnaire de Donnees — Wakdo

Phase Merise : P1 - Conception, etape 1 (dictionnaire de donnees d'abord, mantra #33) Version : v0.3 — prod-like, 22 entites (19 prod-like + couche security-by-design, incl. les entites login_throttle et pin_throttle) Date : 2026-06-04 (ajouts security-by-design 2026-06-11) Branche : feat/p1-conception Statut : prod-like — toutes les decisions D1-D8 + stock appliquees (voir docs/notes/revue-alignement-p1.md §7) ; couche security-by-design en cours (voir note 13) Auteur : BYAN (couche methodologie)

---

1. Objectif

Ce dictionnaire liste toutes les entites de donnees identifiees pour Wakdo, avec leurs attributs, types, contraintes et sources. Il sert de base au MCD (entites + relations), puis au MLD (mapping relationnel), puis au DDL (SQL CREATE TABLE).

Methodologie : derivation bottom-up depuis les sources disponibles :

• Source ecole : docs/merise/_sources/categories.json + produits.json (66 produits, 9 categories)
• Brief metier : docs/PROJECT_CONTEXT.md (composition du menu, flux de commande, RBAC, modes de service)
• Maquette : docs/design/maquette-borne.pdf (UX borne, ecrans visibles)

Tous les ecarts entre la source ecole et le modele final sont documentes dans la section "Notes de modelisation" en bas de ce document.

Pour le diagramme entite-relation et les justifications de cardinalite, voir mcd.md. Ce dictionnaire ne duplique pas cette vue afin d'eviter des sources de verite divergentes.

---

2. Conventions generales

Nommage

• Tables : snake_case, singulier (ex. category, product, customer_order). Le singulier reflete la perspective "1 ligne = 1 instance de l'entite" (convention relationnelle standard). Le code applicatif (PHP, JS) utilise ces noms tels quels via le mapping ORM.
• Colonnes : snake_case. Suffixes typiques : _id (FK), _at (timestamp), _cents (montant monetaire en centimes entiers), _path (chemin de fichier), _rate (taux ou fraction stocke en entier pour-mille).
• Cles primaires : colonne id (INT UNSIGNED AUTO_INCREMENT). Pas de PK composite sauf sur les tables de jointure pures.
• Cles etrangeres : <referenced_table>_id (ex. category_id dans product).
• Valeurs ENUM : anglais, snake_case (ex. pending_payment, dine_in, kiosk).
• Chaines cote code (ENUM, codes de permission, codes de role) : anglais uniquement, coherentes entre la BDD, PHP et l'API JSON.

Types par defaut

Categorie	Type MariaDB	Justification
Identifiants	INT UNSIGNED AUTO_INCREMENT	4 milliards d'ids — suffisant pour ce projet
Libelles courts	VARCHAR(120)	Couvre la plupart des noms de produits (max observe : 41 caracteres dans la source ecole)
Descriptions	TEXT	Longueur variable, sans limite stricte
Montants monetaires	INT UNSIGNED (cents)	Evite les bugs d'arrondi FLOAT (voir note 1)
Booleens	TINYINT(1)	Convention MariaDB pour BOOLEAN (alias)
Horodatages	DATETIME	Lisible par l'humain, fuseau horaire gere au niveau applicatif
Enumerations	ENUM('a','b','c')	Contrainte au niveau SGBD, lisible (voir note 2)
Chemins de fichiers	VARCHAR(255)	Limite standard de longueur de chemin POSIX

Charset et collation

• Charset : utf8mb4 (RFC 3629 — vrai UTF-8 sur 4 octets, supporte emoji et caracteres asiatiques). MariaDB gere utf8mb4 nativement.
• Collation : utf8mb4_unicode_ci (insensible a la casse, comparaison conforme Unicode).

Champs d'audit (presents sur toutes les tables metier sauf les tables de jointure pures)

Colonne	Type	Default	Role
created_at	DATETIME	CURRENT_TIMESTAMP	Timestamp de creation, ecrit une fois a l'insertion
updated_at	DATETIME	CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP	Timestamp de derniere modification, mis a jour automatiquement

Soft delete

Pas de soft delete generalise. Les entites qui peuvent etre temporairement desactivees portent une colonne booleenne is_active ou is_available. Le DELETE dur reste possible mais est reserve aux operations admin avec sauvegarde prealable.

---

3. Entites

3.1 category

Regroupement metier de produits et de menus pour l'affichage sur la borne.

Attribut	Type	NULL	Default	Contrainte	Source ecole	Notes
id	INT UNSIGNED	NO	AUTO_INCREMENT	PK	id (1-9)	identique a la source
name	VARCHAR(60)	NO	—	UNIQUE	title	renomme depuis title
slug	VARCHAR(60)	NO	—	UNIQUE	derive de title (kebab-case minuscule)	utilise pour l'URL /api/categories/burgers
image_path	VARCHAR(255)	YES	NULL	—	image	chemin relatif, voir note 8
display_order	SMALLINT UNSIGNED	NO	0	—	(ajoute)	ordre d'affichage sur la borne, ajustable depuis l'admin
is_active	TINYINT(1)	NO	1	—	(ajoute)	desactiver sans supprimer
created_at	DATETIME	NO	CURRENT_TIMESTAMP	—	—	audit
updated_at	DATETIME	NO	CURRENT_TIMESTAMP ON UPDATE	—	—	audit

Exemples : menus, drinks, burgers, fries, snacks, wraps, salads, desserts, sauces. Volume : 9 lignes a l'init (seed depuis categories.json).

---

3.2 product

Un article vendable unique, disponible a la carte ou comme composant dans un slot de menu.

Attribut	Type	NULL	Default	Contrainte	Source ecole	Notes
id	INT UNSIGNED	NO	AUTO_INCREMENT	PK	id	identique a la source
category_id	INT UNSIGNED	NO	—	FK -> category(id), ON DELETE RESTRICT	(derive de la cle d'objet JSON)
name	VARCHAR(120)	NO	—	INDEX	nom	renomme depuis nom
description	TEXT	YES	NULL	—	(ajoute)	renseigne plus tard via l'admin
price_cents	INT UNSIGNED	NO	—	CHECK > 0	prix (FLOAT)	conversion FLOAT -> INT centimes au seed (voir note 1)
vat_rate	SMALLINT UNSIGNED	NO	100	CHECK IN (55, 100)	(ajoute)	taux de TVA en pour-mille : 100 = 10%, 55 = 5,5%. Defaut 10%. Voir note 9
image_path	VARCHAR(255)	YES	NULL	—	image	chemin relatif, voir note 8
is_available	TINYINT(1)	NO	1	—	(ajoute)	bascule de disponibilite manuelle depuis l'admin
display_order	SMALLINT UNSIGNED	NO	0	—	(ajoute)	ordre d'affichage au sein de la categorie
created_at	DATETIME	NO	CURRENT_TIMESTAMP	—	—	audit
updated_at	DATETIME	NO	CURRENT_TIMESTAMP ON UPDATE	—	—	audit

Volume : ~53 lignes a l'init (66 lignes dans produits.json moins 13 menus deplaces vers menu).

---

3.3 menu

Combo a prix fixe construit autour d'un burger specifique, avec des slots selectionnables par le client (boisson, accompagnement, sauce). Deux paliers de prix : Normal et Maxi.

Attribut	Type	NULL	Default	Contrainte	Source ecole	Notes
id	INT UNSIGNED	NO	AUTO_INCREMENT	PK	id (1-13 dans la categorie menus)
category_id	INT UNSIGNED	NO	—	FK -> category(id), ON DELETE RESTRICT	implicite (categorie menus)
burger_product_id	INT UNSIGNED	NO	—	FK -> product(id), ON DELETE RESTRICT	(ajoute)	le burger fixe qui ancre ce menu ; pilote la personnalisation des ingredients
name	VARCHAR(120)	NO	—	INDEX	nom	ex. "Menu Le 280"
description	TEXT	YES	NULL	—	(ajoute)
price_normal_cents	INT UNSIGNED	NO	—	CHECK > 0	prix	prix format Normal. Remplace le prix_ttc_cents unique.
price_maxi_cents	INT UNSIGNED	NO	—	CHECK > 0	(ajoute)	prix format Maxi (~+150 centimes vs normal ; voir note 7)
image_path	VARCHAR(255)	YES	NULL	—	image	reutilise generalement l'image du burger
is_available	TINYINT(1)	NO	1	—	(ajoute)
display_order	SMALLINT UNSIGNED	NO	0	—	(ajoute)
created_at	DATETIME	NO	CURRENT_TIMESTAMP	—	—	audit
updated_at	DATETIME	NO	CURRENT_TIMESTAMP ON UPDATE	—	—	audit

Volume : 13 lignes a l'init. Remplace l'ancien modele menu_produit a composition fixe.

---

3.4 menu_slot

Un slot selectionnable au sein d'un menu (ex. "slot boisson", "slot accompagnement", "slot sauce"). Chaque slot contraint les produits parmi lesquels le client peut choisir, exprimes via la table de jointure menu_slot_option.

Attribut	Type	NULL	Default	Contrainte	Notes
id	INT UNSIGNED	NO	AUTO_INCREMENT	PK
menu_id	INT UNSIGNED	NO	—	FK -> menu(id), ON DELETE CASCADE	un slot appartient a exactement un menu
name	VARCHAR(80)	NO	—	—	ex. "Drink", "Side", "Sauce"
slot_type	ENUM('drink','side','sauce','dessert','extra')	NO	—	—	role semantique de ce slot
is_required	TINYINT(1)	NO	1	—	indique si le client doit remplir ce slot
display_order	SMALLINT UNSIGNED	NO	0	—	ordre d'affichage dans le constructeur de menu

Pas de champs d'audit : un slot fait partie de la definition du menu ; cree et mis a jour avec le menu. Index composite : (menu_id, display_order).

---

3.5 menu_slot_option

Produits eligibles pour un slot de menu donne. Table de jointure pure.

Attribut	Type	NULL	Default	Contrainte	Notes
menu_slot_id	INT UNSIGNED	NO	—	FK -> menu_slot(id), ON DELETE CASCADE
product_id	INT UNSIGNED	NO	—	FK -> product(id), ON DELETE RESTRICT	RESTRICT : retirer un produit ne doit pas casser silencieusement les menus

Cle primaire : composite (menu_slot_id, product_id).

Volume : ~3-5 options par slot, ~3 slots par menu, 13 menus = ~120-200 lignes a l'init.

---

3.6 ingredient

Ingredient elementaire utilise dans la composition des produits. Porte les donnees de stock.

Attribut	Type	NULL	Default	Contrainte	Notes
id	INT UNSIGNED	NO	AUTO_INCREMENT	PK
name	VARCHAR(120)	NO	—	UNIQUE	ex. "Sesame Bun", "Cheddar Slice", "Ketchup Portion"
unit	VARCHAR(40)	NO	—	—	libelle de l'unite de conditionnement : piece / portion / sachet 1kg / pot / bouteille (libelle libre, pas un ENUM — les unites varient par ingredient)
stock_quantity	INT (signed)	NO	0	—	stock courant en unites. INT signe sans CHECK >= 0 : il PEUT devenir negatif quand les ventes depassent le stock compte (ampleur de la survente, remontee aux managers). Le systeme ne bloque pas une commande sur le stock.
stock_capacity	INT	NO	—	CHECK > 0	niveau "plein" de reference en unites = les 100% servant a calculer le pourcentage de stock. Le CHECK > 0 protege aussi la division du pourcentage contre la division par zero
pack_size	SMALLINT UNSIGNED	NO	1	CHECK > 0	unites par pack de reapprovisionnement (ex. 100 pour un sac de 100 portions)
pack_label	VARCHAR(80)	YES	NULL	—	libelle humain du pack (ex. "Sac 100 portions")
low_stock_pct	SMALLINT UNSIGNED	NO	10	CHECK BETWEEN 0 AND 100	bande d’alerte, pourcentage de capacite : stock_quantity <= stock_capacity * low_stock_pct/100 declenche l'indicateur de stock bas
critical_stock_pct	SMALLINT UNSIGNED	NO	5	CHECK BETWEEN 0 AND 100	seuil de rupture automatique, pourcentage de capacite : stock_quantity <= stock_capacity * critical_stock_pct/100 rend le produit calcule en rupture
is_active	TINYINT(1)	NO	1	—	desactiver les ingredients obsoletes sans supprimer
created_at	DATETIME	NO	CURRENT_TIMESTAMP	—	audit
updated_at	DATETIME	NO	CURRENT_TIMESTAMP ON UPDATE	—	audit

CHECK au niveau table : critical_stock_pct < low_stock_pct (le seuil critique se situe sous la bande d’alerte).

Regle de decrement de stock : a la transition paid, chaque ingredient est decremente de product_ingredient.quantity_normal ou quantity_maxi (selectionne par order_item.format) multiplie par order_item.quantity, puis ajuste par les lignes order_item_modifier. Voir note 7. Regle de reapprovisionnement : stock_quantity += N * pack_size (reapprovisionne en packs complets). Regle d'annulation : le stock est recredite quand une commande paid est annulee. Modele de stock (base sur le pourcentage, trois bandes) : le seuil d'alerte absolu est remplace par un modele en pourcentage ancre sur stock_capacity (la reference 100%). Le pourcentage de stock est calcule, non stocke : stock_pct = ROUND(stock_quantity / stock_capacity * 100). Le CHECK > 0 sur stock_capacity protege cette division contre la division par zero. Trois bandes :

• Normal — au-dessus de la bande d’alerte : rien n'est signale.
• Low — stock_quantity <= stock_capacity * low_stock_pct/100 : commandable + alerte manager. Le manager retire le produit via product.is_available=0, ou reapprovisionne pour lever l'alerte.
• Critical — stock_quantity <= stock_capacity * critical_stock_pct/100 : le produit passe automatiquement en rupture (disponibilite calculee, voir regle RG-T21 dans mlt.md) ; aucune colonne stockee supplementaire.

---

3.7 product_ingredient

Composition par defaut d'un produit (burger, wrap, etc.) en termes d'ingredients. Porte les metadonnees de personnalisation pour le configurateur d'ingredients.

Attribut	Type	NULL	Default	Contrainte	Notes
product_id	INT UNSIGNED	NO	—	FK -> product(id), ON DELETE CASCADE
ingredient_id	INT UNSIGNED	NO	—	FK -> ingredient(id), ON DELETE RESTRICT	RESTRICT : impossible de retirer un ingredient encore reference dans une recette de produit
quantity_normal	SMALLINT UNSIGNED	NO	1	CHECK > 0	unites consommees en format Normal (ex. 2 pour double cheese)
quantity_maxi	SMALLINT UNSIGNED	NO	1	CHECK > 0	unites consommees en format Maxi. Egale quantity_normal pour les ingredients invariants au format (burger, sauce) ; superieure pour les ingredients d'accompagnement et de boisson (le Maxi agrandit uniquement l'accompagnement + la boisson). Voir note 7.
is_removable	TINYINT(1)	NO	1	—	le client peut retirer cet ingredient sans frais
is_addable	TINYINT(1)	NO	0	—	le client peut ajouter une unite supplementaire de cet ingredient
extra_price_cents	INT UNSIGNED	NO	0	CHECK >= 0	supplement en centimes quand is_addable=1 et que le client l'ajoute (0 = extra gratuit)

Cle primaire : composite (product_id, ingredient_id).

Volume : ~5-10 ingredients par produit, ~53 produits = ~300-500 lignes au seed.

---

3.8 allergen

Catalogue des 14 allergenes reglementes (Reglement INCO (UE) 1169/2011).

Attribut	Type	NULL	Default	Contrainte	Notes
id	INT UNSIGNED	NO	AUTO_INCREMENT	PK
code	VARCHAR(30)	NO	—	UNIQUE	code lisible par machine, ex. gluten, milk, nuts
name	VARCHAR(80)	NO	—	—	nom d'affichage, ex. "Gluten", "Lait", "Fruits a coque"
description	TEXT	YES	NULL	—	guidance optionnelle pour le personnel

Volume : 14 lignes au seed (fixe par le reglement UE 1169/2011, liste confirmee au moment du seed). Les allergenes d'un produit sont calcules en joignant product_ingredient -> ingredient_allergen -> allergen ; pas de ressaisie manuelle par produit.

---

3.9 ingredient_allergen

Indique quels allergenes contient chaque ingredient. Table de jointure pure.

Attribut	Type	NULL	Default	Contrainte	Notes
ingredient_id	INT UNSIGNED	NO	—	FK -> ingredient(id), ON DELETE CASCADE
allergen_id	INT UNSIGNED	NO	—	FK -> allergen(id), ON DELETE RESTRICT

Cle primaire : composite (ingredient_id, allergen_id).

---

3.10 customer_order

Transaction client : 1 commande = 1 panier valide a un instant donne. (Rationale du nom de table : voir note de modelisation 3.)

Attribut	Type	NULL	Default	Contrainte	Notes
id	INT UNSIGNED	NO	AUTO_INCREMENT	PK
order_number	VARCHAR(20)	NO	—	UNIQUE	format lisible par l'humain : K/C/D-YYYY-MM-DD-NNN. Prefixe par canal : K=kiosk, C=counter, D=drive. Voir note 4.
idempotency_key	VARCHAR(36)	YES	NULL	UNIQUE	UUID genere par le client pour dedupliquer un POST /api/orders reessaye (anti-double-charge). UNIQUE rejette les doublons ; plusieurs NULL autorises. Security-by-design, voir note 13
source	ENUM('kiosk','counter','drive')	NO	—	INDEX	canal de saisie (qui a saisi la commande). Valeurs en anglais, voir note 5.
acting_user_id	INT UNSIGNED	YES	NULL	FK -> user(id), ON DELETE SET NULL	personnel back-office (counter/drive) ayant cree la commande, capture sous PIN. NULL pour kiosk (anonyme). Imputabilite ciblee sans imposer un login par personne sur la borne. Voir note 13
service_mode	ENUM('dine_in','takeaway','drive')	NO	—	—	mode de consommation, conserve pour les stats/KPI uniquement. Aucun role fiscal (voir note 9). La source drive implique le service_mode drive (contrainte croisee appliquee au niveau applicatif).
status	ENUM('pending_payment','paid','delivered','cancelled')	NO	'pending_payment'	INDEX	machine a 4 etats : pending_payment -> paid -> delivered (+ cancelled). Voir note 6.
total_ht_cents	INT UNSIGNED	NO	—	CHECK >= 0	total hors TVA, snapshot a la validation de la commande
total_vat_cents	INT UNSIGNED	NO	—	CHECK >= 0	montant de TVA, snapshot
total_ttc_cents	INT UNSIGNED	NO	—	CHECK > 0	total TTC ; doit egaler total_ht_cents + total_vat_cents (verifie a la couche MLT)
paid_at	DATETIME	YES	NULL	—	timestamp de la transition vers paid (NULL avant paiement)
delivered_at	DATETIME	YES	NULL	—	timestamp de la transition vers delivered (NULL avant la remise)
cancelled_at	DATETIME	YES	NULL	—	timestamp d'annulation (NULL si non annulee)
created_at	DATETIME	NO	CURRENT_TIMESTAMP	INDEX	utilise pour les agregations de stats en direct ; sert aussi de base a service_day
updated_at	DATETIME	NO	CURRENT_TIMESTAMP ON UPDATE	—	audit

Retire de v0.1 : tva_taux_pourmille (deplace au niveau ligne — order_item.vat_rate_snapshot), paye_a (renomme paid_at). Etats machine preparing et ready retires (voir note 6).

Calcul de service_day (regroupement KPI) :

CASE WHEN HOUR(created_at) < 10 THEN DATE(created_at) - INTERVAL 1 DAY ELSE DATE(created_at) END

Calcule au moment de la requete, non stocke comme colonne (la formule de colonne generee avec INTERVAL 4 HOUR 30 MINUTE dans le MLD v0.1 etait incorrecte et est retiree). Coupure : 10:00.

Volume : ~100-300 commandes/jour au pic, ~10k lignes sur une demo de 6 mois.

---

3.11 order_item

Ligne d'une commande : un seul produit ou un menu, avec prix, libelle et taux de TVA snapshotes au moment de la transaction.

Attribut	Type	NULL	Default	Contrainte	Notes
id	INT UNSIGNED	NO	AUTO_INCREMENT	PK
order_id	INT UNSIGNED	NO	—	FK -> customer_order(id), ON DELETE CASCADE
item_type	ENUM('product','menu')	NO	—	—	discriminateur
product_id	INT UNSIGNED	YES	NULL	FK -> product(id), ON DELETE RESTRICT	non nul si item_type = 'product'
menu_id	INT UNSIGNED	YES	NULL	FK -> menu(id), ON DELETE RESTRICT	non nul si item_type = 'menu'
format	ENUM('normal','maxi')	NO	'normal'	—	s'applique aux items menu (Normal / Maxi). Pour les produits autonomes, la valeur est normal (pas d'agrandissement individuel dans ce modele). Voir note 7.
label_snapshot	VARCHAR(120)	NO	—	—	libelle au moment de la commande (preserve si le produit est renomme)
unit_price_cents_snapshot	INT UNSIGNED	NO	—	CHECK > 0	prix unitaire TTC au moment de la commande
vat_rate_snapshot	SMALLINT UNSIGNED	NO	—	CHECK IN (55, 100)	taux de TVA en pour-mille au moment de la commande (snapshote depuis product.vat_rate)
quantity	SMALLINT UNSIGNED	NO	1	CHECK > 0	quantite commandee (ex. 3 Cocas = 1 ligne avec quantity=3)
created_at	DATETIME	NO	CURRENT_TIMESTAMP	—	audit

Contrainte CHECK (applicative ou MariaDB CHECK >= 10.2) : (item_type='product' AND product_id IS NOT NULL AND menu_id IS NULL) OR (item_type='menu' AND menu_id IS NOT NULL AND product_id IS NULL)

Volume : ~3-5 lignes par commande -> 30k-50k lignes sur 6 mois.

---

3.12 order_item_selection

Les choix reels effectues par le client pour chaque slot d'une ligne de menu. 1 ligne = 1 slot rempli pour 1 order_item de type menu.

Attribut	Type	NULL	Default	Contrainte	Notes
id	INT UNSIGNED	NO	AUTO_INCREMENT	PK
order_item_id	INT UNSIGNED	NO	—	FK -> order_item(id), ON DELETE CASCADE	doit referencer un order_item avec item_type='menu'
menu_slot_id	INT UNSIGNED	NO	—	FK -> menu_slot(id), ON DELETE RESTRICT	quel slot a ete rempli
product_id	INT UNSIGNED	NO	—	FK -> product(id), ON DELETE RESTRICT	produit choisi par le client pour ce slot
label_snapshot	VARCHAR(120)	NO	—	—	libelle du produit au moment de la commande

Volume : ~2-3 selections par ligne de menu. Usage KPI : permet d'analyser quelles combinaisons boisson/accompagnement sont les plus choisies.

---

3.13 order_item_modifier

Modifications au niveau ingredient appliquees par le client a un produit ou au burger fixe d'un menu : retrait (gratuit) ou ajout (avec supplement optionnel).

Attribut	Type	NULL	Default	Contrainte	Notes
id	INT UNSIGNED	NO	AUTO_INCREMENT	PK
order_item_id	INT UNSIGNED	NO	—	FK -> order_item(id), ON DELETE CASCADE	la ligne de commande modifiee (produit ou menu)
ingredient_id	INT UNSIGNED	NO	—	FK -> ingredient(id), ON DELETE RESTRICT	l'ingredient modifie
action	ENUM('remove','add')	NO	—	—	remove = retrait gratuit ; add = unite supplementaire (peut avoir un supplement)
extra_price_cents	INT UNSIGNED	NO	0	CHECK >= 0	snapshot de product_ingredient.extra_price_cents au moment de la commande (0 pour les retraits)

Regle de rattachement du modificateur (voir note de modelisation 10) :

• Pour un produit autonome (item_type='product') : le modificateur cible le produit directement via order_item_id.
• Pour un menu (item_type='menu') : le modificateur cible le burger fixe de la ligne de menu via le meme order_item_id. Le burger est identifie par menu.burger_product_id, permettant a l'affichage cuisine de resoudre sans ambiguite quels ingredients sont modifies. Aucune FK supplementaire n'est necessaire : etant donne order_item_id, le burger est order_item.menu_id -> menu.burger_product_id.

Impact stock : chaque modificateur affecte le stock d'ingredient a la transition paid (remove -> pas de decrement pour cet ingredient ; add -> decrement supplementaire).

---

3.14 user

Utilisateur back-office (admin, manager, personnel cuisine, counter, drive). Les clients de la borne ne sont pas authentifies et n'ont pas de ligne ici.

Attribut	Type	NULL	Default	Contrainte	Notes
id	INT UNSIGNED	NO	AUTO_INCREMENT	PK
email	VARCHAR(254)	NO	—	UNIQUE	longueur max selon RFC 5321
password_hash	VARCHAR(255)	NO	—	—	hash argon2id (voir PASSWORD_ALGO dans .env) ; longueur typique 96 caracteres, marge jusqu'a 255
first_name	VARCHAR(60)	NO	—	—
last_name	VARCHAR(60)	NO	—	—
role_id	INT UNSIGNED	NO	—	FK -> role(id), ON DELETE RESTRICT	un utilisateur ne peut exister sans role
is_active	TINYINT(1)	NO	1	—	desactivation sans suppression
last_login_at	DATETIME	YES	NULL	—	utile pour l'audit et la detection de comptes dormants
pin_hash	VARCHAR(255)	YES	NULL	—	hash argon2id du PIN par membre du personnel qui autorise les actions sensibles (prix/RBAC/utilisateur/annulation/inventaire). NULL = aucun PIN defini. Security-by-design, voir note 13
failed_login_attempts	SMALLINT UNSIGNED	NO	0	—	logins echoues consecutifs ; pilote le throttling degressif (note 13)
last_failed_login_at	DATETIME	YES	NULL	—	timestamp du dernier login echoue
lockout_until	DATETIME	YES	NULL	—	fin de la fenetre de throttling courante (backoff degressif, pas un verrouillage dur indefini)
password_reset_token_hash	VARCHAR(255)	YES	NULL	—	hash du token de reset (pas le token brut) ; NULL quand aucun reset en attente
password_reset_expires_at	DATETIME	YES	NULL	—	expiration du token de reset
anonymized_at	DATETIME	YES	NULL	—	marqueur tombstone RGPD : quand renseigne, les colonnes PII sont mises a NULL/remplacees (note 13). La ligne est conservee pour l'integrite referentielle
created_at	DATETIME	NO	CURRENT_TIMESTAMP	—	audit
updated_at	DATETIME	NO	CURRENT_TIMESTAMP ON UPDATE	—	audit

Volume : 5-20 lignes (equipe du restaurant + 1-2 admins).

Longueur d'email RFC 5321 : local-part <= 64, domaine <= 255, total <= 254 (incluant @). VARCHAR(254) est la valeur conforme a la spec.

Colonnes PII : email, first_name, last_name. Soumises a l'anonymisation RGPD (voir note 13). password_hash et pin_hash sont des credentials, tenus hors des logs et des reponses d'API.

---

3.15 role

Roles back-office (RBAC). Creables / modifiables / desactivables depuis l'UI admin. Le seed fournit 5 roles ; des roles personnalises (ex. "chef-patissier") peuvent etre ajoutes sans deploiement.

Attribut	Type	NULL	Default	Contrainte	Notes
id	INT UNSIGNED	NO	AUTO_INCREMENT	PK
code	VARCHAR(40)	NO	—	UNIQUE	code machine, ex. admin, manager, kitchen, counter, drive
label	VARCHAR(80)	NO	—	—	nom d'affichage, ex. Administrator, Kitchen Staff
description	TEXT	YES	NULL	—
default_route	VARCHAR(120)	YES	NULL	—	ecran d'atterrissage pour ce role (ex. /admin/orders, /kitchen/display). Rend le routage dynamique — pas de noms de role en dur dans le routage front-end.
order_source	ENUM('kiosk','counter','drive')	YES	NULL	—	source auto-taggee quand ce role cree une commande (NULL pour admin/manager qui peuvent creer au nom de n'importe quel canal)
is_active	TINYINT(1)	NO	1	—	la desactivation preserve l'historique des utilisateurs ayant detenu ce role
created_at	DATETIME	NO	CURRENT_TIMESTAMP	—	audit
updated_at	DATETIME	NO	CURRENT_TIMESTAMP ON UPDATE	—	audit

Roles du seed :

Code	default_route	order_source
admin	/admin/dashboard	NULL
manager	/admin/stats	NULL
kitchen	/kitchen/display	NULL
counter	/counter/orders	counter
drive	/drive/orders	drive

Regle d'architecture RBAC (P2) : le code applicatif teste les permissions, pas les noms de role. Ajouter un nouveau role avec les bonnes permissions ne requiert aucun changement de code (pilote par permission, non par nom de role — selon le modele RBAC Sandhu/NIST).

---

3.16 role_visible_source

Definit quelles sources de commande sont visibles sur le tableau de bord de preparation pour un role donne. Table de jointure pure.

Attribut	Type	NULL	Default	Contrainte	Notes
role_id	INT UNSIGNED	NO	—	FK -> role(id), ON DELETE CASCADE
source	ENUM('kiosk','counter','drive')	NO	—	—	source visible pour ce role sur l'affichage kitchen/counter/drive

Cle primaire : composite (role_id, source).

Donnees du seed :

Role	Sources visibles
kitchen	kiosk, counter, drive (toutes)
counter	kiosk, counter
drive	drive

---

3.17 permission

Permissions granulaires assignables aux roles. Le catalogue est fixe au seed (pas de creation via UI).

Attribut	Type	NULL	Default	Contrainte	Notes
id	INT UNSIGNED	NO	AUTO_INCREMENT	PK
code	VARCHAR(60)	NO	—	UNIQUE	format <resource>.<action>
label	VARCHAR(120)	NO	—	—	nom d'affichage
description	TEXT	YES	NULL	—
created_at	DATETIME	NO	CURRENT_TIMESTAMP	—	audit

Catalogue de permissions fixe (23 codes — gele avant le DDL) :

Code	Accorde a (defaut seed)
product.create	admin, manager
product.read	admin, manager, kitchen, counter, drive
product.update	admin, manager
product.delete	admin
menu.create	admin, manager
menu.read	admin, manager, kitchen, counter, drive
menu.update	admin, manager
menu.delete	admin
category.manage	admin, manager
ingredient.manage	admin, manager
stock.read	admin, manager, kitchen, counter, drive
stock.count	admin, manager, kitchen, counter, drive
stock.manage	admin, manager
order.read	admin, manager, kitchen, counter, drive
order.create	admin, counter, drive
order.deliver	admin, counter, drive
order.cancel	admin, counter, drive
user.create	admin
user.read	admin, manager
user.update	admin
user.deactivate	admin
role.manage	admin
stats.read	admin, manager

Volume : 23 lignes au seed.

---

3.18 role_permission

Mapping N-N entre roles et permissions. Table de jointure pure.

Attribut	Type	NULL	Default	Contrainte	Notes
role_id	INT UNSIGNED	NO	—	FK -> role(id), ON DELETE CASCADE
permission_id	INT UNSIGNED	NO	—	FK -> permission(id), ON DELETE CASCADE

Cle primaire : composite (role_id, permission_id).

Volume : ~50-100 lignes au seed (admin couvre tout ; les autres couvrent un sous-ensemble).

---

3.19 stock_movement

Journal d'audit append-only de tous les changements de stock par ingredient. 1 ligne par mouvement (vente, annulation, reapprovisionnement, correction d'inventaire).

Attribut	Type	NULL	Default	Contrainte	Notes
id	INT UNSIGNED	NO	AUTO_INCREMENT	PK
ingredient_id	INT UNSIGNED	NO	—	FK -> ingredient(id), ON DELETE RESTRICT	ingredient affecte
movement_type	ENUM('sale','cancellation','restock','inventory_correction')	NO	—	INDEX	nature du mouvement
delta	INT	NO	—	—	changement signe : negatif pour la consommation (vente), positif pour reapprovisionnement/annulation/correction
order_id	INT UNSIGNED	YES	NULL	FK -> customer_order(id), ON DELETE SET NULL	commande liee pour les mouvements sale et cancellation ; NULL pour restock/correction
user_id	INT UNSIGNED	YES	NULL	FK -> user(id), ON DELETE SET NULL	utilisateur ayant declenche le mouvement (NULL pour les decrements de vente automatises)
note	VARCHAR(255)	YES	NULL	—	note humaine optionnelle (ex. raison de la correction, reference de pack)
created_at	DATETIME	NO	CURRENT_TIMESTAMP	INDEX	timestamp immuable

Immuabilite : aucun UPDATE ni DELETE sur cette table. Les corrections sont de nouvelles lignes avec movement_type='inventory_correction' et un delta signe.

Mouvements automatiques (declenches aux transitions de statut) :

• transition paid : 1 ligne sale par unite d'ingredient consommee (en tenant compte des modificateurs).
• cancelled (depuis paid) : 1 ligne cancellation par unite d'ingredient recreditee.

Mouvements manuels :

• restock : le manager ou l'admin enregistre une livraison (+= N * pack_size).
• inventory_correction : comptage physique matin/soir ; le systeme enregistre l'ecart (delta = reel - theorique).

Volume : ~5-15 mouvements par commande sur tous les ingredients ; un index sur (ingredient_id, created_at) est recommande pour les requetes d'historique par ingredient.

---

3.20 audit_log

Journal append-only des actions back-office sensibles, pour l'imputabilite la ou elle importe (menace interne, manipulation d'argent, changements RBAC). Complete stock_movement (specifique au stock) ; couvre les evenements catalogue/prix, utilisateur, role/permission et annulation de commande. Ajout security-by-design (voir note 13).

Attribut	Type	NULL	Default	Contrainte	Notes
id	INT UNSIGNED	NO	AUTO_INCREMENT	PK
actor_user_id	INT UNSIGNED	YES	NULL	FK -> user(id), ON DELETE SET NULL	personnel ayant effectue l'action, capture via PIN pour les operations sensibles. NULL si non attribuable a un individu
actor_role_id	INT UNSIGNED	YES	NULL	FK -> role(id), ON DELETE SET NULL	contexte de role au moment de l'action (denormalise pour que la trace survive a l'anonymisation de l'utilisateur)
action_code	VARCHAR(60)	NO	—	INDEX	code d'operation MCT / de permission, ex. product.update, order.cancel, role.manage, user.deactivate
entity_type	VARCHAR(40)	YES	NULL	—	nom de la table affectee, ex. product, customer_order, role, user
entity_id	INT UNSIGNED	YES	NULL	—	PK de la ligne affectee
summary	VARCHAR(255)	YES	NULL	—	courte description non personnelle, ex. "price_cents 880 -> 920", "added permission stock.manage"
details	JSON	YES	NULL	—	diff before/after optionnel. Pour les actions ciblant un utilisateur, stocke les noms de champs modifies, pas les valeurs PII
created_at	DATETIME	NO	CURRENT_TIMESTAMP	INDEX	timestamp immuable

Immuabilite : aucun UPDATE ni DELETE au niveau applicatif (meme discipline que stock_movement). Index : (actor_user_id, created_at), (entity_type, entity_id), (action_code, created_at). Retention : fenetre propre (~12 mois, interet legitime / tracabilite fiscale), decouplee du cycle de vie des PII utilisateur (note 13). Une purge planifiee (cron) retire les lignes au-dela de la fenetre.

Operations journalisees (ensemble sensible) : UPDATE_PRODUCT (8.2, incl. prix), DELETE_PRODUCT (8.3), DELETE_MENU (8.6), CANCEL_ORDER (7.1), RESTOCK (9.1), INVENTORY_COUNT (9.2), CREATE_USER / UPDATE_USER / DEACTIVATE_USER (10.1-10.3), MANAGE_RBAC (10.4).

Volume : faible (~10-50 actions sensibles/jour) — des ordres de grandeur sous stock_movement.

---

3.21 login_throttle

Throttle anti-brute-force par IP source. Complete le compteur par compte deja present sur user (failed_login_attempts / lockout_until), une ligne par IP source. Ajout security-by-design (voir note 13).

Attribut	Type	NULL	Default	Contrainte	Notes
id	INT UNSIGNED	NO	AUTO_INCREMENT	PK
ip_address	VARCHAR(45)	NO	—	UNIQUE	IP source, une ligne par IP, upsertee ; 45 caracteres contiennent un litteral IPv6 complet
failed_attempts	SMALLINT UNSIGNED	NO	0	—	logins echoues consecutifs depuis cette IP dans la fenetre courante
window_started_at	DATETIME	NO	CURRENT_TIMESTAMP	—	debut de la fenetre de comptage courante
lockout_until	DATETIME	YES	NULL	—	fin de la fenetre de backoff degressif ; NULL = non throttle
last_attempt_at	DATETIME	NO	CURRENT_TIMESTAMP	—	timestamp de la derniere tentative echouee

Pas de FK : une IP n'est pas une entite modelisee. Les lignes sont appended/upsertees par IP ; la fenetre se reinitialise a son expiration. Un cron quotidien purge les lignes sans lockout actif dont le last_attempt_at est plus ancien que 24h.

---

3.22 pin_throttle

Throttle du PIN d'action sensible (RG-T22), complement de RG-T13. Une ligne par utilisateur AGISSANT (l'identite de session qui soumet email+PIN), STRICTEMENT SEPAREE des compteurs de connexion (user.failed_login_attempts / login_throttle) : un echec de PIN n'incremente aucun compteur de login. Ajout security-by-design (voir note 13).

Attribut	Type	NULL	Default	Contrainte	Notes
id	INT UNSIGNED	NO	AUTO_INCREMENT	PK
actor_user_id	INT UNSIGNED	NO	—	UNIQUE, FK -> user(id) ON DELETE CASCADE	l'utilisateur agissant (session), une ligne par acteur, upsertee
failed_attempts	SMALLINT UNSIGNED	NO	0	—	echecs de PIN consecutifs de cet acteur dans la fenetre courante
window_started_at	DATETIME	NO	CURRENT_TIMESTAMP	—	debut de la fenetre de comptage courante
lockout_until	DATETIME	YES	NULL	—	fin de la fenetre de backoff degressif ; NULL = non throttle
last_attempt_at	DATETIME	NO	CURRENT_TIMESTAMP	—	timestamp de la derniere tentative echouee

FK ON DELETE CASCADE (contrairement a login_throttle) : la cle est un utilisateur back-office authentifie, donc supprimer/anonymiser le compte purge proprement sa ligne de throttle. Memes bornes de backoff que RG-8 mais PROPRES au PIN (PIN_THROTTLE_*, plus permissives). Meme purge cron quotidienne que login_throttle (lignes sans lockout actif > 24h).

---

4. Notes de modelisation

Note 1 — Pourquoi INT UNSIGNED en centimes pour les prix

Stocker un prix en FLOAT ou DECIMAL(10,2) est techniquement valide mais introduit deux risques :

1. Arrondi FLOAT : 0.1 + 0.2 = 0.30000000000000004 en virgule flottante IEEE 754. Sommer 100 lignes de commande peut produire des ecarts au niveau du centime vs la realite metier.
2. Conversion FLOAT-vers-chaine : differentes versions de driver PHP/MariaDB peuvent serialiser les floats avec une precision variable.

Stocker en INT UNSIGNED (centimes : 880 pour 8,80 EUR) elimine ces risques. La conversion en EUR pour l'affichage se fait en PHP a la sortie : number_format($cents / 100, 2).

Reference : David Goldberg, What Every Computer Scientist Should Know About Floating-Point Arithmetic, ACM Computing Surveys, 1991.

Note 2 — Pourquoi ENUM plutot qu'une table de reference

Les ENUMs (service_mode, status, item_type, action, slot_type) auraient pu etre des tables de reference. Choix retenu : ENUM.

Avantages dans ce contexte :

• Les valeurs sont stables et limitees (3-7 valeurs max), peu susceptibles d'evoluer frequemment.
• Contrainte au niveau SGBD au lieu d'une FK a l'execution ; requetes plus simples.
• Directement lisible en SQL : WHERE status = 'paid'.

Cout d'un changement futur : ALTER TABLE ... MODIFY COLUMN ... ENUM(...) pour ajouter une valeur. Acceptable etant donne que les changements sont attendus comme rares.

Si ces ENUMs requierent plus tard des libelles ou descriptions multilingues, ils seront migres vers des tables de reference. Hors perimetre pour cette iteration.

Note 3 — Pourquoi customer_order et non order

ORDER est un mot reserve SQL (utilise dans ORDER BY). Trois approches existent :

• Quoter le nom partout : `order` — requiert un quoting dans chaque instruction SQL, source d'erreurs et non portable entre dialectes SGBD.
• Utiliser un alias au niveau ORM : possible mais ajoute une couche de mapping.
• Renommer : customer_order (choisi) — sans ambiguite, auto-documente, sans quoting requis.

Alternative consideree et rejetee : purchase (moins specifique au domaine), transaction (egalement reserve ou ambigu). customer_order correspond au langage du domaine et evite tous les conflits.

order_item est conserve comme nom de table de ligne : item n'est pas reserve, et le prefixe order_ rend claire la relation parent.

Note 4 — Prefixe de numero de commande par canal

Format : K/C/D-YYYY-MM-DD-NNN (kiosk / counter / drive).

Rationale : le prefixe encode le canal, ce qui est utile pour une identification visuelle rapide par le personnel cuisine et comptoir sans interroger la colonne source. Le compteur sequentiel NNN repart chaque jour par canal. Sans collision sur une journee, vu le volume attendu.

Alternative rejetee : prefixe neutre W- pour tous les canaux (plus simple, mais perd la lisibilite du canal pour le personnel).

Note 5 — source vs service_mode (canal vs mode de consommation)

Deux dimensions distinctes, gardees separees :

	source	service_mode
Nature	canal de saisie (qui a saisi la commande)	mode de consommation (ou le client mange)
Valeurs	kiosk, counter, drive	dine_in, takeaway, drive
Sert a	authentification, analytics, filtrage de permission	KPI, capacite (aucun role fiscal)

Les deux dimensions sont independantes pour kiosk et counter (un client borne peut choisir dine_in ou takeaway). drive est le seul cas ou les deux dimensions s'alignent : source=drive implique service_mode=drive. Cette contrainte croisee est verifiee au niveau applicatif.

Note 6 — Machine a 4 etats reduite

v0.1 avait 6 etats (pending_payment, paid, preparing, ready, delivered, cancelled). v0.2 reduit a 4 etats : pending_payment -> paid -> delivered (+ cancelled).

Rationale (Decision 4 de revue-alignement-p1.md §7) : dans un contexte fast-food, l'affichage cuisine (KDS) est un systeme visuel — le personnel voit le ticket et agit. preparing et ready etaient des etats intermediaires qui ajoutaient de la complexite sans valeur metier proportionnelle. L'unique action cuisine est deliver (le personnel counter/drive remet la commande), fusionnant preparing + ready + delivered en un seul geste. Le KPI est le temps total : delivered_at - paid_at (SLA ~10 min). Le codage couleur du KDS est calcule depuis now - paid_at, sans etat stocke supplementaire.

Etats et timestamps retires : preparing_at, ready_at ne sont pas stockes.

Note 7 — Cascade de format Normal / Maxi

Le format Maxi agrandit uniquement l'accompagnement et la boisson. Le burger est inchange et la portion de sauce est inchangee (un pot de sauce est identique dans les deux formats). Ce perimetre est explicite afin que le modele de stock reste fidele.

Cote prix — non modelise au niveau du prix de composant individuel :

• menu porte deux prix : price_normal_cents et price_maxi_cents.
• order_item.format enregistre le format choisi par le client (normal ou maxi).
• order_item.unit_price_cents_snapshot capture le prix reellement paye (Normal ou Maxi).
• Aucun prix individuel par composant de slot n'est stocke ; le differentiel de prix est un attribut au niveau menu, coherent avec la maniere dont les menus fast-food tendent a etre tarifes en pratique.

Cote stock — modelise via un multiplicateur de format sur la recette :

• product_ingredient porte quantity_normal et quantity_maxi.
• A la transition paid, le decrement utilise quantity_maxi quand order_item.format='maxi', sinon quantity_normal.
• Pour les ingredients burger et sauce, quantity_maxi = quantity_normal (invariants au format).
• Pour les ingredients accompagnement et boisson, quantity_maxi > quantity_normal (le Maxi consomme plus).
• Le format se propage de la ligne de menu (order_item.format) a ses selections de slot ; une ligne de produit autonome est par defaut a normal.
• Un seul produit par choix (ex. un produit Fries), pas de produits medium/large separes.

Calibration : le supplement Maxi est dans la fourchette ~1,50 EUR pour ce modele (derive de donnees internes ; recoupe avec l'ordre de grandeur du marche pour plausibilite. Wakdo est un pastiche fictif, donc les prix exacts ne sont pas copies d'une chaine reelle).

Calibration : le supplement Maxi est dans la fourchette ~1,50 EUR pour ce modele (derive de donnees internes ; recoupe avec l'ordre de grandeur du marche pour plausibilite. Wakdo est un pastiche fictif, donc les prix exacts ne sont pas copies d'une chaine reelle).

Note 8 — Stockage des images : chemin en VARCHAR vs BLOB en BDD

Les colonnes image_path (category, product, menu) stockent un chemin relatif depuis la racine publique (ex. /uploads/products/classic-burger.jpg), pas un chemin serveur absolu. PHP resout via un prefixe depuis .env (UPLOAD_DIR=public/uploads).

Le stockage BLOB a ete considere et rejete :

Critere	image_path VARCHAR (choisi)	BLOB en BDD
Performance borne	Apache sert les fichiers en ms (cache OS)	PHP lit la BDD + streame, latence multipliee
Cache HTTP	ETag, Last-Modified, cache navigateur, CDN natifs	doit etre reimplemente en PHP
Taille de backup BDD	Megaoctets (chemins seulement)	Gigaoctets (66 produits x ~200 Ko + variantes responsive)
Pipeline d'images	convert, webp, optimisation = outils standard du systeme de fichiers	doit etre reinvente en PHP

Sources : OWASP File Upload Cheat Sheet ; MariaDB Knowledge Base — LONGBLOB performance ; documentation Apache HTTP Server — serving static content.

Note 9 — Regle de TVA dans le fast-food francais (fact-checked)

FACT-CHECK
Claim audited : "TVA 10% sur place / 5,5% a emporter" (dictionary v0.1 note 9)
Domain         : compliance (fiscal)
Verdict        : CLAIM INEXACT — superseded
Source         : BOFiP BOI-ANNX-000495 + BOI-TVA-LIQ-30-10-10 (official doctrine impots.gouv.fr)
Actual rule    : 10% for immediate consumption (dine-in OR hot takeaway);
                 5.5% for products in resealable containers (bottle, can) / deferred consumption
Confidence     : 95% (L1, official text)

Consequence sur le modele : le taux de TVA est un attribut du product (vat_rate en pour-mille : 100 = 10%, 55 = 5,5%), pas de la commande ni du mode de service. Defaut : 100 (10%). Le taux de 5,5% s'applique aux produits en contenants refermables (eau en bouteille, bouteilles de jus). La TVA est calculee ligne par ligne ; le taux est snapshote sur order_item.vat_rate_snapshot au moment de la transaction pour preserver l'integrite historique si la legislation change.

service_mode est conserve sur customer_order pour les stats et le KPI uniquement (planification de capacite, repartition du chiffre d'affaires par mode). Il n'a aucun role de calcul fiscal.

Note 10 — Configurateur d'ingredients et rattachement du modificateur

order_item_modifier se rattache a une ligne order_item via order_item_id, que la ligne soit un produit autonome ou un menu.

Pour un produit autonome (item_type='product') : order_item_id identifie directement le produit modifie.

Pour un menu (item_type='menu') : le produit modifiable est le burger fixe, identifie via order_item.menu_id -> menu.burger_product_id. L'affichage cuisine resout : modifier.order_item_id -> order_item -> menu -> menu.burger_product_id -> product.name. Aucune colonne FK supplementaire n'est necessaire sur order_item_modifier. Cela garde la table modificateur simple et evite une colonne nullable target_product_id qui ne serait peuplee que pour les lignes de menu.

Contrainte appliquee au niveau applicatif : les lignes order_item_modifier pour une ligne de menu referencent uniquement des ingredients appartenant a menu.burger_product_id via product_ingredient.

Note 11 — Eligibilite menu_slot : filtre par categorie vs liste de produits explicite

Deux options ont ete considerees :

• Filtre par categorie : menu_slot.category_id pointe vers une categorie ; tous les produits de cette categorie sont eligibles. Simple, mais une categorie peut contenir des produits non proposes dans ce slot (ex. une boisson premium ajoutee a la categorie "drinks" ne devrait pas apparaitre automatiquement dans tous les slots de menu).
• Liste de produits explicite menu_slot_option(menu_slot_id, product_id) (choisie) : chaque produit eligible est liste explicitement par slot. Plus verbeux au moment du seed mais precis — pas d'eligibilite accidentelle quand le catalogue grandit. Permet des overrides de tarification par slot a l'avenir sans changement structurel.

La liste explicite ajoute une entite (menu_slot_option, entite 3.5) mais elimine une classe de bugs de justesse. Coherent avec l'ambition prod-like de ce modele.

Note 12 — commande_event retire

v0.1 portait une table d'audit append-only commande_event (pattern event sourcing). Retiree en v0.2 (Decision 1, revue-alignement-p1.md §7).

Rationale : dans un contexte restaurant, le compte back-office est partage par poste de travail, non individuel. L'attribution par personne d'une transition d'etat n'a aucune valeur metier. Le besoin reel (durees de phase, stats par heure de la journee) est couvert par les timestamps de phase sur customer_order (paid_at, delivered_at, cancelled_at) sans la complexite d'un event store.

La machine a 4 etats combinee a 3 timestamps de phase fournit toutes les donnees KPI necessaires :

• Temps de remise : delivered_at - paid_at
• Taux et timing d'annulation : cancelled_at - created_at
• Volume par heure : calcul HOUR(created_at) / service_day

Pour l'audit de stock, stock_movement (entite 3.19) fournit la trace d'audit append-only la ou elle est genuinement necessaire (reconciliation d'inventaire).

Note 13 — Ajouts de donnees security-by-design (2026-06-11)

Ces ajouts etendent le modele prod-like avec une couche security-by-design. Ils ne remplacent aucune decision v0.2 ; ils ajoutent imputabilite, cycle de vie d'auth et resistance a l'abus.

Imputabilite — compte partage hybride + PIN. Les sessions back-office restent partagees par poste de travail pour le flux de routine (un terminal fast-food est partage, les equipiers tournent). Un PIN par membre du personnel (user.pin_hash, argon2id) autorise un ensemble defini d'actions sensibles (editions prix/menu 8.2/8.3/8.6, annulation de commande 7.1, correction d'inventaire 9.2, gestion des utilisateurs 10.1-10.3, RBAC 10.4). Ces actions ecrivent le user_id agissant dans audit_log (3.20). Cela resout la justification circulaire qui avait retire commande_event en v0.1 (les events etaient juges inutiles parce que les comptes etaient partages) : l'imputabilite est enregistree la ou elle importe, a friction quasi nulle pour les 95% de routine. customer_order.acting_user_id capture le personnel pour les commandes counter/drive prises sous PIN ; les commandes borne restent anonymes.

Cycle de vie d'auth. password_reset_token_hash + password_reset_expires_at permettent un parcours de reset (le token est stocke hashe, le token brut est envoye par e-mail une seule fois). La resistance au brute-force utilise un throttling degressif plutot qu'un verrouillage dur indefini : failed_login_attempts + lockout_until implementent un backoff degressif par (compte + IP source), de sorte qu'une serie de fautes de frappe ne verrouille pas toute une cuisine en plein service (15 h continues). Les logins echoues sont ecrits dans audit_log.

Anonymisation RGPD vs retention d'audit. Les PII de user (email, first_name, last_name) sont soumises au droit a l'effacement (Cr 3.d). L'effacement anonymise plutot qu'il ne supprime durement : la ligne est conservee, email devient un placeholder unique non identifiant (anon-<id>@wakdo.invalid, domaine reserve RFC 2606), les noms sont effaces, password_hash/pin_hash sont invalides, et anonymized_at est renseigne. audit_log conserve sa propre fenetre de retention (~12 mois, interet legitime / tracabilite fiscale) et continue de pointer vers le principal anonymise, de sorte que effacement et imputabilite coexistent sans casser l'integrite referentielle.

Resistance a l'abus sur la borne anonyme. customer_order.idempotency_key (UUID client, UNIQUE) deduplique un POST /api/orders reessaye de sorte qu'un retry reseau ne cree pas de commande payee dupliquee. Le stock est decremente avec une seule instruction atomique (UPDATE ingredient SET stock_quantity = stock_quantity - :units WHERE id = :id) : aucune operation ne depend d'une lecture de stock, donc la ligne s'auto-verrouille pour la duree de l'ecriture — pas de lost update et pas de souci d'ordre des deadlocks. Cela remplace l'approche pessimiste anterieure SELECT ... FOR UPDATE (regle de la couche traitement, voir mlt.md) ; elle n'ajoute aucune colonne ici.

Modele de stock en pourcentage + disponibilite calculee. ingredient porte stock_capacity (la reference 100%), low_stock_pct (bande d’alerte) et critical_stock_pct (seuil de rupture automatique) — voir 3.6. stock_quantity est signe et peut devenir negatif (ampleur de survente remontee aux managers) ; le systeme ne bloque pas une commande sur le stock. La commandabilite effective du produit est calculee (regle RG-T21 dans mlt.md) : product.is_available = 1 ET chaque ingredient non retirable (is_removable=0) de son product_ingredient a stock_quantity > stock_capacity * critical_stock_pct/100. A la bande critique, un produit passe automatiquement en rupture sans ecriture ni cascade ; un retrait manuel (product.is_available=0) est une surcharge forte ; un reapprovisionnement au-dessus de la bande critique rend le produit a nouveau commandable de lui-meme.

Throttle anti-brute-force par IP. login_throttle (3.21) suit failed_attempts et lockout_until par IP source (une ligne upsertee par IP), completant le compteur par compte sur user. Cela ajoute une seconde dimension de throttling, de sorte qu'une seule IP martelant de nombreux comptes soit ralentie independamment du compteur de n'importe quel compte. Un cron quotidien purge les lignes inactives et non verrouillees.

Throttle du PIN d'action sensible (par acteur). pin_throttle (3.22) suit failed_attempts et lockout_until par utilisateur AGISSANT (l'identite de session qui valide une action sensible), dans une table separee des compteurs de connexion. La dimension est l'acteur (et non l'email cible, contournable par rotation, ni l'IP, qui penaliserait tous les equipiers d'un poste partage) ; le verrou est un backoff degressif aux bornes propres (PIN_THROTTLE_*). Meme purge cron que login_throttle. RG-T22.

References : docs/notes/revue-alignement-p1.md §7 (decisions D), carte d'impact security-by-design (2026-06-11). Modele de menace et matrice de classification des donnees : PROJECT_CONTEXT.md §19 (a venir).

---

5. Synthese du decompte des entites

#	Entite	Type	Remplace / nouveau
1	category	business	v0.1 categorie (renommee + traduite)
2	product	business	v0.1 produit (+ vat_rate)
3	menu	business	v0.1 menu (+ FK burger, 2 prix)
4	menu_slot	business	nouveau — remplace la composition fixe menu_produit
5	menu_slot_option	join	nouveau — liste d'eligibilite par slot
6	ingredient	business	nouveau — configurateur d'ingredients + stock
7	product_ingredient	join	nouveau — recette + metadonnees de personnalisation
8	allergen	reference	nouveau — INCO 1169/2011
9	ingredient_allergen	join	nouveau — mappe les allergenes aux ingredients
10	customer_order	business	v0.1 commande (renommee, machine a 4 etats, timestamps de phase)
11	order_item	business	v0.1 ligne_commande (+ format, vat_rate_snapshot)
12	order_item_selection	business	nouveau — choix de slot de menu du client
13	order_item_modifier	business	nouveau — modifications au niveau ingredient
14	user	business	v0.1 user (noms de champs traduits)
15	role	business	v0.1 role (+ default_route, order_source)
16	role_visible_source	join	nouveau — filtre de tableau de bord par role
17	permission	reference	v0.1 permission (traduite, catalogue gele)
18	role_permission	join	v0.1 role_permission (inchangee)
19	stock_movement	audit	nouveau — journal d'audit de stock append-only
20	audit_log	audit	nouveau (security-by-design) — journal append-only d'actions sensibles
21	login_throttle	security	nouveau (security-by-design) - throttle anti-brute-force par IP
22	pin_throttle	security	nouveau (security-by-design) - throttle du PIN d'action sensible par acteur (RG-T22)

Retire de v0.1 : commande_event (remplace par les timestamps de phase sur customer_order), menu_produit (remplace par le modele menu_slot + menu_slot_option).

Total : 22 entites (19 prod-like v0.2 + audit_log, login_throttle et pin_throttle de la couche security-by-design).

Le security-by-design ajoute aussi des colonnes (au-dela des deux nouvelles entites) : cycle de vie d'auth de user + pin_hash + anonymized_at (3.14), customer_order.acting_user_id + idempotency_key (3.10), et le modele de stock en pourcentage sur ingredient (3.6) — stock_capacity, critical_stock_pct, plus le renommage de low_stock_threshold en low_stock_pct. login_throttle (3.21) est la 21e entite et pin_throttle (3.22) la 22e. Voir note 13.

---

Pour le diagramme ER et les justifications de cardinalite, voir mcd.md — le diagramme est la source de verite unique pour la representation graphique.