corentin_wakdo/docs/merise/dictionary.md

Data Dictionary — Wakdo

Merise phase : P1 - Conception, step 1 (data dictionary first, mantra #33) Version : v0.2 — prod-like, 21 entities (19 prod-like + security-by-design layer, incl. the new login_throttle entity) Date : 2026-06-04 (security-by-design additions 2026-06-11) Branch : feat/p1-conception Status : prod-like — all D1-D8 + stock decisions applied (see docs/notes/revue-alignement-p1.md §7); security-by-design layer in progress (see note 13) Author : BYAN (methodology layer)

---

1. Purpose

This dictionary lists all data entities identified for Wakdo, with their attributes, types, constraints, and sources. It serves as the basis for the MCD (entities + relations), then the MLD (relational mapping), then the DDL (SQL CREATE TABLE).

Methodology: bottom-up derivation from available sources:

• School source: docs/merise/_sources/categories.json + produits.json (66 products, 9 categories)
• Business brief: docs/PROJECT_CONTEXT.md (menu composition, order flow, RBAC, service modes)
• Mockup: docs/design/maquette-borne.pdf (kiosk UX, visible screens)

All deviations between school source and final model are documented in the "Modeling notes" section at the bottom of this document.

For the entity-relationship diagram and cardinality justifications, see mcd.md. This dictionary does not duplicate that view to avoid diverging sources of truth.

---

2. General conventions

Naming

• Tables: snake_case, singular (e.g., category, product, customer_order). Singular reflects the perspective "1 row = 1 instance of the entity" (standard relational convention). Application code (PHP, JS) uses these names as-is via ORM mapping.
• Columns: snake_case. Typical suffixes: _id (FK), _at (timestamp), _cents (monetary amount in integer cents), _path (file path), _rate (rate or fraction stored as per-mille integer).
• Primary keys: column id (INT UNSIGNED AUTO_INCREMENT). No composite PK except on pure join tables.
• Foreign keys: <referenced_table>_id (e.g., category_id in product).
• ENUM values: English, snake_case (e.g., pending_payment, dine_in, kiosk).
• Code-facing strings (ENUM, permission codes, role codes): English only, consistent across DB, PHP, and JSON API.

Default types

Category	MariaDB type	Justification
Identifiers	INT UNSIGNED AUTO_INCREMENT	4 billion ids — sufficient for this project
Short labels	VARCHAR(120)	Covers most product names (max observed: 41 chars in school source)
Descriptions	TEXT	Variable length, no strict limit
Monetary amounts	INT UNSIGNED (cents)	Avoids FLOAT rounding bugs (see note 1)
Booleans	TINYINT(1)	MariaDB convention for BOOLEAN (alias)
Timestamps	DATETIME	Human-readable, timezone handled at app layer
Enumerations	ENUM('a','b','c')	DBMS-level constraint, readable (see note 2)
File paths	VARCHAR(255)	Standard POSIX path length limit

Charset and collation

• Charset: utf8mb4 (RFC 3629 — real 4-byte UTF-8, supports emoji and Asian characters). MariaDB handles utf8mb4 natively.
• Collation: utf8mb4_unicode_ci (case-insensitive, Unicode-compliant comparison).

Audit fields (present on all business tables except pure join tables)

Column	Type	Default	Role
created_at	DATETIME	CURRENT_TIMESTAMP	Creation timestamp, written once at insert
updated_at	DATETIME	CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP	Last modification timestamp, auto-updated

Soft delete

No generalized soft delete. Entities that can be temporarily deactivated carry an is_active or is_available boolean column. Hard DELETE remains possible but is reserved for admin operations with prior backup.

---

3. Entities

3.1 category

Business grouping of products and menus for display on the kiosk.

Attribute	Type	NULL	Default	Constraint	School source	Notes
id	INT UNSIGNED	NO	AUTO_INCREMENT	PK	id (1-9)	same as source
name	VARCHAR(60)	NO	—	UNIQUE	title	renamed from title
slug	VARCHAR(60)	NO	—	UNIQUE	derived from title (kebab-case lowercase)	used for URL /api/categories/burgers
image_path	VARCHAR(255)	YES	NULL	—	image	relative path, see note 8
display_order	SMALLINT UNSIGNED	NO	0	—	(added)	display order on kiosk, adjustable from admin
is_active	TINYINT(1)	NO	1	—	(added)	deactivate without deleting
created_at	DATETIME	NO	CURRENT_TIMESTAMP	—	—	audit
updated_at	DATETIME	NO	CURRENT_TIMESTAMP ON UPDATE	—	—	audit

Examples: menus, drinks, burgers, fries, snacks, wraps, salads, desserts, sauces. Volume: 9 rows at init (seed from categories.json).

---

3.2 product

A single sellable item, available a la carte or as a component in a menu slot.

Attribute	Type	NULL	Default	Constraint	School source	Notes
id	INT UNSIGNED	NO	AUTO_INCREMENT	PK	id	same as source
category_id	INT UNSIGNED	NO	—	FK -> category(id), ON DELETE RESTRICT	(derived from JSON object key)
name	VARCHAR(120)	NO	—	INDEX	nom	renamed from nom
description	TEXT	YES	NULL	—	(added)	populated later via admin
price_cents	INT UNSIGNED	NO	—	CHECK > 0	prix (FLOAT)	FLOAT -> INT cents conversion at seed (see note 1)
vat_rate	SMALLINT UNSIGNED	NO	100	CHECK IN (55, 100)	(added)	VAT rate in per-mille: 100 = 10%, 55 = 5.5%. Default 10%. See note 9
image_path	VARCHAR(255)	YES	NULL	—	image	relative path, see note 8
is_available	TINYINT(1)	NO	1	—	(added)	manual availability toggle from admin
display_order	SMALLINT UNSIGNED	NO	0	—	(added)	display order within category
created_at	DATETIME	NO	CURRENT_TIMESTAMP	—	—	audit
updated_at	DATETIME	NO	CURRENT_TIMESTAMP ON UPDATE	—	—	audit

Volume: ~53 rows at init (66 rows in produits.json minus 13 menus moved to menu).

---

3.3 menu

Fixed-price combo built around a specific burger, with customer-selectable slots (drink, side, sauce). Two price tiers: Normal and Maxi.

Attribute	Type	NULL	Default	Constraint	School source	Notes
id	INT UNSIGNED	NO	AUTO_INCREMENT	PK	id (1-13 in menus category)
category_id	INT UNSIGNED	NO	—	FK -> category(id), ON DELETE RESTRICT	implicit (category menus)
burger_product_id	INT UNSIGNED	NO	—	FK -> product(id), ON DELETE RESTRICT	(added)	the fixed burger that anchors this menu; drives ingredient customization
name	VARCHAR(120)	NO	—	INDEX	nom	e.g., "Menu Le 280"
description	TEXT	YES	NULL	—	(added)
price_normal_cents	INT UNSIGNED	NO	—	CHECK > 0	prix	Normal format price. Replaces single prix_ttc_cents.
price_maxi_cents	INT UNSIGNED	NO	—	CHECK > 0	(added)	Maxi format price (~+150 cents vs normal; see note 7)
image_path	VARCHAR(255)	YES	NULL	—	image	typically reuses the burger image
is_available	TINYINT(1)	NO	1	—	(added)
display_order	SMALLINT UNSIGNED	NO	0	—	(added)
created_at	DATETIME	NO	CURRENT_TIMESTAMP	—	—	audit
updated_at	DATETIME	NO	CURRENT_TIMESTAMP ON UPDATE	—	—	audit

Volume: 13 rows at init. Replaces the old fixed-composition menu_produit model.

---

3.4 menu_slot

A selectable slot within a menu (e.g., "drink slot", "side slot", "sauce slot"). Each slot constrains which products the customer can choose from, expressed via the join table menu_slot_option.

Attribute	Type	NULL	Default	Constraint	Notes
id	INT UNSIGNED	NO	AUTO_INCREMENT	PK
menu_id	INT UNSIGNED	NO	—	FK -> menu(id), ON DELETE CASCADE	a slot belongs to exactly one menu
name	VARCHAR(80)	NO	—	—	e.g., "Drink", "Side", "Sauce"
slot_type	ENUM('drink','side','sauce','dessert','extra')	NO	—	—	semantic role of this slot
is_required	TINYINT(1)	NO	1	—	whether the customer must fill this slot
display_order	SMALLINT UNSIGNED	NO	0	—	order of display in the menu builder

No audit fields: a slot is part of menu definition; created and updated with the menu. Composite index: (menu_id, display_order).

---

3.5 menu_slot_option

Eligible products for a given menu slot. Pure join table.

Attribute	Type	NULL	Default	Constraint	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: removing a product must not silently break menus

Primary key: composite (menu_slot_id, product_id).

Volume: ~3-5 options per slot, ~3 slots per menu, 13 menus = ~120-200 rows at init.

---

3.6 ingredient

Elementary ingredient used in product composition. Carries stock data.

Attribute	Type	NULL	Default	Constraint	Notes
id	INT UNSIGNED	NO	AUTO_INCREMENT	PK
name	VARCHAR(120)	NO	—	UNIQUE	e.g., "Sesame Bun", "Cheddar Slice", "Ketchup Portion"
unit	VARCHAR(40)	NO	—	—	packaging unit label: piece / portion / sachet 1kg / pot / bottle (free-form label, not an ENUM — units vary per ingredient)
stock_quantity	INT (signed)	NO	0	—	current stock in units. Signed INT with no CHECK >= 0: it MAY go negative when sales outrun counted stock (oversell magnitude, surfaced to managers). The system does not block an order on stock.
stock_capacity	INT	NO	—	CHECK > 0	reference "full" level in units = the 100% used to compute the stock percentage. The CHECK > 0 also guards the percentage division against divide-by-zero
pack_size	SMALLINT UNSIGNED	NO	1	CHECK > 0	units per restocking pack (e.g., 100 for a bag of 100 portions)
pack_label	VARCHAR(80)	YES	NULL	—	human label of the pack (e.g., "Sac 100 portions")
low_stock_pct	SMALLINT UNSIGNED	NO	10	CHECK BETWEEN 0 AND 100	warning band, percent of capacity: stock_quantity <= stock_capacity * low_stock_pct/100 triggers the low-stock indicator
critical_stock_pct	SMALLINT UNSIGNED	NO	5	CHECK BETWEEN 0 AND 100	auto-out-of-stock floor, percent of capacity: stock_quantity <= stock_capacity * critical_stock_pct/100 makes the product computed out-of-stock
is_active	TINYINT(1)	NO	1	—	deactivate obsolete ingredients without deleting
created_at	DATETIME	NO	CURRENT_TIMESTAMP	—	audit
updated_at	DATETIME	NO	CURRENT_TIMESTAMP ON UPDATE	—	audit

Table-level CHECK: critical_stock_pct < low_stock_pct (the critical floor sits below the warning band).

Stock decrement rule: at the paid transition, each ingredient is decremented by product_ingredient.quantity_normal or quantity_maxi (selected by order_item.format) multiplied by order_item.quantity, then adjusted by order_item_modifier rows. See note 7. Restocking rule: stock_quantity += N * pack_size (restocked in full packs). Cancellation rule: stock is re-credited when a paid order is cancelled. Stock model (percentage-based, three bands): the absolute alert threshold is replaced by a percentage model anchored on stock_capacity (the 100% reference). The stock percentage is computed, not stored: stock_pct = ROUND(stock_quantity / stock_capacity * 100). The CHECK > 0 on stock_capacity guards this division against divide-by-zero. Three bands:

• Normal — above the low band: nothing flagged.
• Low — stock_quantity <= stock_capacity * low_stock_pct/100: orderable + manager alert. The manager either pulls the product via product.is_available=0, or restocks to clear the alert.
• Critical — stock_quantity <= stock_capacity * critical_stock_pct/100: the product auto-goes out-of-stock (computed availability, see rule RG-T21 in mlt.md); no extra stored column.

---

3.7 product_ingredient

Default composition of a product (burger, wrap, etc.) in terms of ingredients. Carries customization metadata for the ingredient configurator.

Attribute	Type	NULL	Default	Constraint	Notes
product_id	INT UNSIGNED	NO	—	FK -> product(id), ON DELETE CASCADE
ingredient_id	INT UNSIGNED	NO	—	FK -> ingredient(id), ON DELETE RESTRICT	RESTRICT: cannot remove an ingredient still referenced in a product recipe
quantity_normal	SMALLINT UNSIGNED	NO	1	CHECK > 0	units consumed in Normal format (e.g., 2 for double cheese)
quantity_maxi	SMALLINT UNSIGNED	NO	1	CHECK > 0	units consumed in Maxi format. Equals quantity_normal for format-invariant ingredients (burger, sauce); higher for side and drink ingredients (Maxi enlarges side + drink only). See note 7.
is_removable	TINYINT(1)	NO	1	—	customer can remove this ingredient at no cost
is_addable	TINYINT(1)	NO	0	—	customer can add an extra unit of this ingredient
extra_price_cents	INT UNSIGNED	NO	0	CHECK >= 0	surcharge in cents when is_addable=1 and customer adds it (0 = free extra)

Primary key: composite (product_id, ingredient_id).

Volume: ~5-10 ingredients per product, ~53 products = ~300-500 rows at seed.

---

3.8 allergen

Catalogue of the 14 regulated allergens (INCO Regulation (EU) 1169/2011).

Attribute	Type	NULL	Default	Constraint	Notes
id	INT UNSIGNED	NO	AUTO_INCREMENT	PK
code	VARCHAR(30)	NO	—	UNIQUE	machine-readable code, e.g., gluten, milk, nuts
name	VARCHAR(80)	NO	—	—	display name, e.g., "Gluten", "Lait", "Fruits a coque"
description	TEXT	YES	NULL	—	optional guidance for staff

Volume: 14 rows at seed (fixed by EU regulation 1169/2011, list confirmed at seed time). Allergens for a product are computed by joining product_ingredient -> ingredient_allergen -> allergen; no manual re-entry per product.

---

3.9 ingredient_allergen

Maps which allergens each ingredient contains. Pure join table.

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

Primary key: composite (ingredient_id, allergen_id).

---

3.10 customer_order

Customer transaction: 1 order = 1 validated cart at a point in time. (Table name rationale: see modeling note 3.)

Attribute	Type	NULL	Default	Constraint	Notes
id	INT UNSIGNED	NO	AUTO_INCREMENT	PK
order_number	VARCHAR(20)	NO	—	UNIQUE	human-readable format: K/C/D-YYYY-MM-DD-NNN. Prefix by channel: K=kiosk, C=counter, D=drive. See note 4.
idempotency_key	VARCHAR(36)	YES	NULL	UNIQUE	client-generated UUID to deduplicate a retried POST /api/orders (anti-double-charge). UNIQUE rejects duplicates; multiple NULLs allowed. Security-by-design, see note 13
source	ENUM('kiosk','counter','drive')	NO	—	INDEX	input channel (who entered the order). Values in English, see note 5.
acting_user_id	INT UNSIGNED	YES	NULL	FK -> user(id), ON DELETE SET NULL	back-office staff (counter/drive) who created the order, captured under PIN. NULL for kiosk (anonymous). Targeted accountability without forcing per-person login on the kiosk. See note 13
service_mode	ENUM('dine_in','takeaway','drive')	NO	—	—	consumption mode, retained for stats/KPI only. No fiscal role (see note 9). drive source implies drive service_mode (cross-constraint enforced at app layer).
status	ENUM('pending_payment','paid','delivered','cancelled')	NO	'pending_payment'	INDEX	4-state machine: pending_payment -> paid -> delivered (+ cancelled). See note 6.
total_ht_cents	INT UNSIGNED	NO	—	CHECK >= 0	ex-VAT total, snapshot at order validation
total_vat_cents	INT UNSIGNED	NO	—	CHECK >= 0	VAT amount, snapshot
total_ttc_cents	INT UNSIGNED	NO	—	CHECK > 0	incl.-VAT total; must equal total_ht_cents + total_vat_cents (verified at MLT layer)
paid_at	DATETIME	YES	NULL	—	timestamp of transition to paid (NULL before payment)
delivered_at	DATETIME	YES	NULL	—	timestamp of transition to delivered (NULL before delivery)
cancelled_at	DATETIME	YES	NULL	—	timestamp of cancellation (NULL if not cancelled)
created_at	DATETIME	NO	CURRENT_TIMESTAMP	INDEX	used for live stats aggregations; also serves as service_day base
updated_at	DATETIME	NO	CURRENT_TIMESTAMP ON UPDATE	—	audit

Dropped from v0.1: tva_taux_pourmille (moved to line level — order_item.vat_rate_snapshot), paye_a (renamed paid_at). Machine states preparing and ready dropped (see note 6).

service_day computation (KPI grouping):

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

Computed at query time, not stored as a column (the generated-column formula with INTERVAL 4 HOUR 30 MINUTE in v0.1 MLD was incorrect and is dropped). Cutoff: 10:00.

Volume: ~100-300 orders/day at peak, ~10k rows over a 6-month demo.

---

3.11 order_item

Line of an order: a single product or a menu, with price, label, and VAT rate snapshotted at transaction time.

Attribute	Type	NULL	Default	Constraint	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	—	—	discriminator
product_id	INT UNSIGNED	YES	NULL	FK -> product(id), ON DELETE RESTRICT	non-null if item_type = 'product'
menu_id	INT UNSIGNED	YES	NULL	FK -> menu(id), ON DELETE RESTRICT	non-null if item_type = 'menu'
format	ENUM('normal','maxi')	NO	'normal'	—	applies to menu items (Normal / Maxi). For standalone products, value is normal (no individual upsizing in this model). See note 7.
label_snapshot	VARCHAR(120)	NO	—	—	label at time of order (preserved if product is renamed)
unit_price_cents_snapshot	INT UNSIGNED	NO	—	CHECK > 0	unit price incl. VAT at time of order
vat_rate_snapshot	SMALLINT UNSIGNED	NO	—	CHECK IN (55, 100)	VAT rate in per-mille at time of order (snapshotted from product.vat_rate)
quantity	SMALLINT UNSIGNED	NO	1	CHECK > 0	quantity ordered (e.g., 3 Cocas = 1 line with quantity=3)
created_at	DATETIME	NO	CURRENT_TIMESTAMP	—	audit

CHECK constraint (applicative or 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 lines per order -> 30k-50k rows over 6 months.

---

3.12 order_item_selection

The actual choices made by the customer for each slot of a menu line. 1 row = 1 slot filled for 1 order_item of type menu.

Attribute	Type	NULL	Default	Constraint	Notes
id	INT UNSIGNED	NO	AUTO_INCREMENT	PK
order_item_id	INT UNSIGNED	NO	—	FK -> order_item(id), ON DELETE CASCADE	must reference an order_item with item_type='menu'
menu_slot_id	INT UNSIGNED	NO	—	FK -> menu_slot(id), ON DELETE RESTRICT	which slot was filled
product_id	INT UNSIGNED	NO	—	FK -> product(id), ON DELETE RESTRICT	product chosen by the customer for this slot
label_snapshot	VARCHAR(120)	NO	—	—	product label at time of order

Volume: ~2-3 selections per menu line. KPI use: enables analysis of which drink/side combinations are most chosen.

---

3.13 order_item_modifier

Ingredient-level modifications applied by the customer to a product or to the fixed burger of a menu: removal (free) or addition (with optional surcharge).

Attribute	Type	NULL	Default	Constraint	Notes
id	INT UNSIGNED	NO	AUTO_INCREMENT	PK
order_item_id	INT UNSIGNED	NO	—	FK -> order_item(id), ON DELETE CASCADE	the order line being modified (product or menu)
ingredient_id	INT UNSIGNED	NO	—	FK -> ingredient(id), ON DELETE RESTRICT	the ingredient being modified
action	ENUM('remove','add')	NO	—	—	remove = free removal; add = extra unit (may have surcharge)
extra_price_cents	INT UNSIGNED	NO	0	CHECK >= 0	snapshot of product_ingredient.extra_price_cents at time of order (0 for removals)

Modifier attachment rule (see modeling note 10):

• For a standalone product (item_type='product'): the modifier targets the product directly via order_item_id.
• For a menu (item_type='menu'): the modifier targets the menu line's fixed burger via the same order_item_id. The burger is identified by menu.burger_product_id, allowing the kitchen display to resolve which ingredients are modified without ambiguity. No additional FK is needed: given order_item_id, the burger is order_item.menu_id -> menu.burger_product_id.

Stock impact: each modifier affects ingredient stock at paid transition (remove -> no decrement for that ingredient; add -> extra decrement).

---

3.14 user

Back-office user (admin, manager, kitchen staff, counter, drive). Kiosk customers are not authenticated and have no row here.

Attribute	Type	NULL	Default	Constraint	Notes
id	INT UNSIGNED	NO	AUTO_INCREMENT	PK
email	VARCHAR(254)	NO	—	UNIQUE	max length per RFC 5321
password_hash	VARCHAR(255)	NO	—	—	argon2id hash (see PASSWORD_ALGO in .env); typical length 96 chars, margin to 255
first_name	VARCHAR(60)	NO	—	—
last_name	VARCHAR(60)	NO	—	—
role_id	INT UNSIGNED	NO	—	FK -> role(id), ON DELETE RESTRICT	a user cannot exist without a role
is_active	TINYINT(1)	NO	1	—	deactivation without deletion
last_login_at	DATETIME	YES	NULL	—	useful for audit and dormant account detection
pin_hash	VARCHAR(255)	YES	NULL	—	argon2id hash of the per-staff PIN that authorises sensitive actions (price/RBAC/user/cancel/inventory). NULL = no PIN set. Security-by-design, see note 13
failed_login_attempts	SMALLINT UNSIGNED	NO	0	—	consecutive failed logins; drives degressive throttling (note 13)
last_failed_login_at	DATETIME	YES	NULL	—	timestamp of the last failed login
lockout_until	DATETIME	YES	NULL	—	end of the current throttling window (degressive backoff, not a hard indefinite lock)
password_reset_token_hash	VARCHAR(255)	YES	NULL	—	hash of the reset token (not the raw token); NULL when no reset pending
password_reset_expires_at	DATETIME	YES	NULL	—	expiry of the reset token
anonymized_at	DATETIME	YES	NULL	—	RGPD tombstone marker: when set, PII columns are nulled/replaced (note 13). The row is kept for referential integrity
created_at	DATETIME	NO	CURRENT_TIMESTAMP	—	audit
updated_at	DATETIME	NO	CURRENT_TIMESTAMP ON UPDATE	—	audit

Volume: 5-20 rows (restaurant team + 1-2 admins).

RFC 5321 email length: local-part <= 64, domain <= 255, total <= 254 (including @). VARCHAR(254) is the spec-compliant value.

PII columns: email, first_name, last_name. Subject to RGPD anonymisation (see note 13). password_hash and pin_hash are credentials, kept out of logs and API responses.

---

3.15 role

Back-office roles (RBAC). Creatable / modifiable / deactivatable from admin UI. Seed provides 5 roles; custom roles (e.g., "chef-patissier") can be added without deployment.

Attribute	Type	NULL	Default	Constraint	Notes
id	INT UNSIGNED	NO	AUTO_INCREMENT	PK
code	VARCHAR(40)	NO	—	UNIQUE	machine code, e.g., admin, manager, kitchen, counter, drive
label	VARCHAR(80)	NO	—	—	display name, e.g., Administrator, Kitchen Staff
description	TEXT	YES	NULL	—
default_route	VARCHAR(120)	YES	NULL	—	landing screen for this role (e.g., /admin/orders, /kitchen/display). Makes routing dynamic — no hardcoded role names in front-end routing.
order_source	ENUM('kiosk','counter','drive')	YES	NULL	—	auto-tagged source when this role creates an order (NULL for admin/manager who can create on behalf of any channel)
is_active	TINYINT(1)	NO	1	—	deactivation preserves history of users who held this role
created_at	DATETIME	NO	CURRENT_TIMESTAMP	—	audit
updated_at	DATETIME	NO	CURRENT_TIMESTAMP ON UPDATE	—	audit

Seed roles:

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

RBAC architecture rule (P2): application code tests permissions, not role names. Adding a new role with the right permissions requires no code change (permission-driven, not role-name-driven — per Sandhu/NIST RBAC model).

---

3.16 role_visible_source

Defines which order sources are visible on the preparation dashboard for a given role. Pure join table.

Attribute	Type	NULL	Default	Constraint	Notes
role_id	INT UNSIGNED	NO	—	FK -> role(id), ON DELETE CASCADE
source	ENUM('kiosk','counter','drive')	NO	—	—	source visible to this role on the kitchen/counter/drive display

Primary key: composite (role_id, source).

Seed data:

Role	Visible sources
kitchen	kiosk, counter, drive (all)
counter	kiosk, counter
drive	drive

---

3.17 permission

Granular permissions assignable to roles. Catalogue is fixed at seed (no UI creation).

Attribute	Type	NULL	Default	Constraint	Notes
id	INT UNSIGNED	NO	AUTO_INCREMENT	PK
code	VARCHAR(60)	NO	—	UNIQUE	format <resource>.<action>
label	VARCHAR(120)	NO	—	—	display name
description	TEXT	YES	NULL	—
created_at	DATETIME	NO	CURRENT_TIMESTAMP	—	audit

Fixed permission catalogue (23 codes — frozen before DDL):

Code	Granted to (seed default)
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 rows at seed.

---

3.18 role_permission

N-N mapping between roles and permissions. Pure join table.

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

Primary key: composite (role_id, permission_id).

Volume: ~50-100 rows at seed (admin covers all; others cover a subset).

---

3.19 stock_movement

Append-only audit log of all stock changes per ingredient. 1 row per movement (sale, cancellation, restock, inventory correction).

Attribute	Type	NULL	Default	Constraint	Notes
id	INT UNSIGNED	NO	AUTO_INCREMENT	PK
ingredient_id	INT UNSIGNED	NO	—	FK -> ingredient(id), ON DELETE RESTRICT	ingredient affected
movement_type	ENUM('sale','cancellation','restock','inventory_correction')	NO	—	INDEX	nature of the movement
delta	INT	NO	—	—	signed change: negative for consumption (sale), positive for restock/cancellation/correction
order_id	INT UNSIGNED	YES	NULL	FK -> customer_order(id), ON DELETE SET NULL	linked order for sale and cancellation movements; NULL for restock/correction
user_id	INT UNSIGNED	YES	NULL	FK -> user(id), ON DELETE SET NULL	user who triggered the movement (NULL for automated sale decrements)
note	VARCHAR(255)	YES	NULL	—	optional human note (e.g., reason for correction, pack reference)
created_at	DATETIME	NO	CURRENT_TIMESTAMP	INDEX	immutable timestamp

Immutability: no UPDATE or DELETE on this table. Corrections are new rows with movement_type='inventory_correction' and a signed delta.

Automatic movements (triggered at status transitions):

• paid transition: 1 sale row per ingredient unit consumed (accounting for modifiers).
• cancelled (from paid): 1 cancellation row per ingredient unit re-credited.

Manual movements:

• restock: manager or admin records a delivery (+= N * pack_size).
• inventory_correction: morning/evening physical count; system records the discrepancy (delta = actual - theoretical).

Volume: ~5-15 movements per order across all ingredients; index on (ingredient_id, created_at) is recommended for per-ingredient history queries.

---

3.20 audit_log

Append-only log of sensitive back-office actions, for accountability where it matters (insider threat, money handling, RBAC changes). Complements stock_movement (which is stock-specific); covers catalogue/price, user, role/permission, and order cancellation events. Security-by-design addition (see note 13).

Attribute	Type	NULL	Default	Constraint	Notes
id	INT UNSIGNED	NO	AUTO_INCREMENT	PK
actor_user_id	INT UNSIGNED	YES	NULL	FK -> user(id), ON DELETE SET NULL	staff who performed the action, captured via PIN for sensitive operations. NULL if not attributable to an individual
actor_role_id	INT UNSIGNED	YES	NULL	FK -> role(id), ON DELETE SET NULL	role context at action time (denormalised so the trail survives user anonymisation)
action_code	VARCHAR(60)	NO	—	INDEX	MCT operation / permission code, e.g. product.update, order.cancel, role.manage, user.deactivate
entity_type	VARCHAR(40)	YES	NULL	—	affected table name, e.g. product, customer_order, role, user
entity_id	INT UNSIGNED	YES	NULL	—	PK of the affected row
summary	VARCHAR(255)	YES	NULL	—	short non-personal description, e.g. "price_cents 880 -> 920", "added permission stock.manage"
details	JSON	YES	NULL	—	optional before/after diff. For user-targeted actions, stores changed field names, not PII values
created_at	DATETIME	NO	CURRENT_TIMESTAMP	INDEX	immutable timestamp

Immutability: no UPDATE or DELETE at application layer (same discipline as stock_movement). Indexes: (actor_user_id, created_at), (entity_type, entity_id), (action_code, created_at). Retention: own window (~12 months, legitimate-interest / fiscal traceability), decoupled from user PII lifecycle (note 13). A scheduled purge (cron) removes rows past the window.

Logged operations (sensitive set): UPDATE_PRODUCT (8.2, incl. price), 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: low (~10-50 sensitive actions/day) — orders of magnitude below stock_movement.

---

3.21 login_throttle

Per-source-IP brute-force throttle. Complements the per-account counter already on user (failed_login_attempts / lockout_until), one row per source IP. Security-by-design addition (see note 13).

Attribute	Type	NULL	Default	Constraint	Notes
id	INT UNSIGNED	NO	AUTO_INCREMENT	PK
ip_address	VARCHAR(45)	NO	—	UNIQUE	source IP, one row per IP, upserted; 45 chars holds a full IPv6 literal
failed_attempts	SMALLINT UNSIGNED	NO	0	—	consecutive failed logins from this IP in the current window
window_started_at	DATETIME	NO	CURRENT_TIMESTAMP	—	start of the current counting window
lockout_until	DATETIME	YES	NULL	—	end of the degressive backoff window; NULL = not throttled
last_attempt_at	DATETIME	NO	CURRENT_TIMESTAMP	—	timestamp of the last failed attempt

No FK: an IP is not a modelled entity. Rows are appended/upserted by IP; the window resets when expired. A daily cron purges rows with no active lockout whose last_attempt_at is older than 24h.

---

4. Modeling notes

Note 1 — Why INT UNSIGNED in cents for prices

Storing a price as FLOAT or DECIMAL(10,2) is technically valid but introduces two risks:

1. FLOAT rounding: 0.1 + 0.2 = 0.30000000000000004 in IEEE 754 floating-point. Summing 100 order lines can produce cent-level discrepancies vs business reality.
2. FLOAT-to-string conversion: different PHP/MariaDB driver versions may serialize floats with variable precision.

Storing as INT UNSIGNED (cents: 880 for EUR 8.80) eliminates these risks. Conversion to EUR for display is done in PHP at output: number_format($cents / 100, 2).

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

Note 2 — Why ENUM rather than a reference table

ENUMs (service_mode, status, item_type, action, slot_type) could have been reference tables. Choice retained: ENUM.

Advantages in this context:

• Values are stable and limited (3-7 values max), unlikely to evolve frequently.
• DBMS-level constraint instead of runtime FK; simpler queries.
• Directly readable in SQL: WHERE status = 'paid'.

Cost of a future change: ALTER TABLE ... MODIFY COLUMN ... ENUM(...) to add a value. Acceptable given changes are expected to be rare.

If these ENUMs later require multilingual labels or descriptions, they will be migrated to reference tables. Not in scope for this iteration.

Note 3 — Why customer_order and not order

ORDER is an SQL reserved word (used in ORDER BY). Three approaches exist:

• Quote the name everywhere: `order` — requires quoting in every SQL statement, error-prone and non-portable across DBMS dialects.
• Use an alias at ORM level: possible but adds a mapping layer.
• Rename: customer_order (chosen) — unambiguous, self-documenting, no quoting required.

Alternative considered and rejected: purchase (less domain-specific), transaction (also reserved or ambiguous). customer_order matches the domain language and avoids all conflicts.

order_item is retained as the line table name: item is not reserved, and the order_ prefix makes the parent relationship clear.

Note 4 — Order number prefix by channel

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

Rationale: the prefix encodes the channel, which is useful for rapid visual identification by kitchen and counter staff without querying the source column. The sequential counter NNN restarts daily per channel. Collision-free within a day given expected volume.

Alternative rejected: neutral prefix W- for all channels (simpler, but loses channel readability for staff).

Note 5 — source vs service_mode (channel vs consumption mode)

Two distinct dimensions, kept separate:

	source	service_mode
Nature	input channel (who entered the order)	consumption mode (where the customer eats)
Values	kiosk, counter, drive	dine_in, takeaway, drive
Used for	authentication, analytics, permission filtering	KPI, capacity (no fiscal role)

The two dimensions are independent for kiosk and counter (a kiosk customer can choose dine_in or takeaway). drive is the only case where both dimensions align: source=drive implies service_mode=drive. This cross-constraint is verified at app layer.

Note 6 — Reduced 4-state machine

v0.1 had 6 states (pending_payment, paid, preparing, ready, delivered, cancelled). v0.2 reduces to 4 states: pending_payment -> paid -> delivered (+ cancelled).

Rationale (Decision 4 from revue-alignement-p1.md §7): in a fast-food context, the kitchen display (KDS) is a visual system — staff see the ticket and act. preparing and ready were intermediate states that added complexity without proportional business value. The single kitchen action is deliver (counter/drive staff hands over the order), collapsing preparing + ready + delivered into one gesture. KPI is total time: delivered_at - paid_at (SLA ~10 min). KDS color coding is computed from now - paid_at, no extra stored state.

Dropped states and timestamps: preparing_at, ready_at are not stored.

Note 7 — Normal / Maxi format cascade

The Maxi format enlarges the side and the drink only. The burger is unchanged and the sauce portion is unchanged (a sauce pot is the same in both formats). This scope is explicit so the stock model stays faithful.

Price side — not modeled at individual component price level:

• menu carries two prices: price_normal_cents and price_maxi_cents.
• order_item.format records which format the customer chose (normal or maxi).
• order_item.unit_price_cents_snapshot captures the actual price paid (Normal or Maxi).
• No individual price per slot component is stored; the price differential is a menu-level attribute, consistent with how fast-food menus tend to be priced in practice.

Stock side — modeled via a format multiplier on the recipe:

• product_ingredient carries quantity_normal and quantity_maxi.
• At the paid transition, the decrement uses quantity_maxi when order_item.format='maxi', otherwise quantity_normal.
• For burger and sauce ingredients, quantity_maxi = quantity_normal (format-invariant).
• For side and drink ingredients, quantity_maxi > quantity_normal (Maxi consumes more).
• The format cascades from the menu line (order_item.format) to its slot selections; a standalone product line defaults to normal.
• Single product per choice (e.g., one Fries product), not separate medium/large products.

Calibration: the Maxi surcharge is in the ~1.50 EUR range for this model (derived from internal data; cross-checked against market magnitude for plausibility. Wakdo is a fictional pastiche so exact prices are not copied from a real chain).

Calibration: the Maxi surcharge is in the ~1.50 EUR range for this model (derived from internal data; cross-checked against market magnitude for plausibility. Wakdo is a fictional pastiche so exact prices are not copied from a real chain).

Note 8 — Image storage: path in VARCHAR vs BLOB in DB

image_path columns (category, product, menu) store a relative path from the public root (e.g., /uploads/products/classic-burger.jpg), not an absolute server path. PHP resolves via a prefix from .env (UPLOAD_DIR=public/uploads).

BLOB storage was considered and rejected:

Criterion	image_path VARCHAR (chosen)	BLOB in DB
Kiosk performance	Apache serves files in ms (OS cache)	PHP reads DB + streams, multiplied latency
HTTP caching	ETag, Last-Modified, browser cache, CDN native	must be reimplemented in PHP
DB backup size	Megabytes (paths only)	Gigabytes (66 products x ~200 KB + responsive variants)
Image pipeline	convert, webp, optimization = standard filesystem tools	must be reinvented in PHP

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

Note 9 — VAT rule in French fast-food (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)

Model consequence: VAT rate is an attribute of the product (vat_rate in per-mille: 100 = 10%, 55 = 5.5%), not of the order or the service mode. Default: 100 (10%). The 5.5% rate applies to products in resealable containers (bottled water, juice bottles). VAT is computed line by line; the rate is snapshotted on order_item.vat_rate_snapshot at transaction time to preserve historical integrity if legislation changes.

service_mode is retained on customer_order for stats and KPI only (capacity planning, per-mode revenue breakdown). It has no fiscal computation role.

Note 10 — Ingredient configurator and modifier attachment

order_item_modifier attaches to an order_item row via order_item_id, regardless of whether the line is a standalone product or a menu.

For a standalone product (item_type='product'): order_item_id directly identifies the product being modified.

For a menu (item_type='menu'): the modifiable product is the fixed burger, identified via order_item.menu_id -> menu.burger_product_id. The kitchen display resolves: modifier.order_item_id -> order_item -> menu -> menu.burger_product_id -> product.name. No additional FK column is needed on order_item_modifier. This keeps the modifier table simple and avoids a nullable target_product_id column that would only be populated for menu lines.

Constraint enforced at app layer: order_item_modifier rows for a menu line reference only ingredients belonging to menu.burger_product_id via product_ingredient.

Note 11 — menu_slot eligibility: category filter vs explicit product list

Two options were considered:

• Category filter: menu_slot.category_id points to a category; all products in that category are eligible. Simple, but a category may contain products not offered in this slot (e.g., a premium drink added to the "drinks" category should not automatically appear in all menu slots).
• Explicit product list menu_slot_option(menu_slot_id, product_id) (chosen): each eligible product is listed explicitly per slot. More verbose at seed time but precise — no accidental eligibility when the catalogue grows. Enables per-slot pricing overrides in the future without structural change.

The explicit list adds one entity (menu_slot_option, entity 3.5) but eliminates a class of correctness bugs. Consistent with the prod-like ambition of this model.

Note 12 — commande_event dropped

v0.1 carried a commande_event append-only audit table (event sourcing pattern). Dropped in v0.2 (Decision 1, revue-alignement-p1.md §7).

Rationale: in a restaurant context, the back-office account is shared per workstation, not individual. Per-person attribution of a state transition has no business value. The actual need (phase durations, time-of-day stats) is covered by phase timestamps on customer_order (paid_at, delivered_at, cancelled_at) without the complexity of an event store.

The 4-state machine combined with 3 phase timestamps provides all KPI data needed:

• Time-to-deliver: delivered_at - paid_at
• Cancellation rate and timing: cancelled_at - created_at
• Volume by hour: HOUR(created_at) / service_day computation

For stock audit, stock_movement (entity 3.19) provides the append-only audit trail where it is genuinely needed (inventory reconciliation).

Note 13 — Security-by-design data additions (2026-06-11)

These additions extend the prod-like model with a security-by-design layer. They do not replace any v0.2 decision; they add accountability, auth lifecycle, and abuse resistance.

Accountability — hybrid shared-account + PIN. Back-office sessions stay shared per workstation for the routine flow (a fast-food terminal is shared, equipiers rotate). A per-staff PIN (user.pin_hash, argon2id) authorises a defined set of sensitive actions (price/menu edits 8.2/8.3/8.6, order cancellation 7.1, inventory correction 9.2, user management 10.1-10.3, RBAC 10.4). Those actions write the acting user_id into audit_log (3.20). This resolves the circular justification that dropped commande_event in v0.1 (events were considered useless because accounts were shared): accountability is recorded where it matters, at near-zero friction for the routine 95%. customer_order.acting_user_id captures the staff for counter/drive orders taken under PIN; kiosk orders stay anonymous.

Auth lifecycle. password_reset_token_hash + password_reset_expires_at enable a reset path (the token is stored hashed, the raw token is e-mailed once). Brute-force resistance uses degressive throttling rather than a hard indefinite lock: failed_login_attempts + lockout_until implement an exponential backoff per (account + source IP), so a fat-finger streak does not lock out a whole kitchen mid-service (15 h continuous). Failed logins are written to audit_log.

RGPD anonymisation vs audit retention. user PII (email, first_name, last_name) is subject to the right to erasure (Cr 3.d). Erasure anonymises rather than hard-deletes: the row is kept, email becomes a non-identifying unique placeholder (anon-<id>@wakdo.invalid, RFC 2606 reserved domain), names are cleared, password_hash/pin_hash are invalidated, and anonymized_at is set. The audit_log retains its own retention window (~12 months, legitimate-interest / fiscal traceability) and keeps pointing at the anonymised principal, so erasure and accountability coexist without breaking referential integrity.

Abuse resistance on the anonymous kiosk. customer_order.idempotency_key (client UUID, UNIQUE) deduplicates a retried POST /api/orders so a network retry does not create a duplicate paid order. Stock is decremented with a single atomic statement (UPDATE ingredient SET stock_quantity = stock_quantity - :units WHERE id = :id): no operation gates on a stock read, so the row self-locks for the duration of the write — no lost update and no deadlock-ordering concern. This replaces the earlier pessimistic SELECT ... FOR UPDATE approach (treatment-layer rule, see mlt.md); it adds no column here.

Percentage stock model + computed availability. ingredient carries stock_capacity (the 100% reference), low_stock_pct (warning band) and critical_stock_pct (auto-out-of-stock floor) — see 3.6. stock_quantity is signed and may go negative (oversell magnitude surfaced to managers); the system does not block an order on stock. Effective product orderability is computed (rule RG-T21 in mlt.md): product.is_available = 1 AND each non-removable (is_removable=0) ingredient of its product_ingredient has stock_quantity > stock_capacity * critical_stock_pct/100. At the critical band a product auto-goes out-of-stock with no write and no cascade; a manual pull (product.is_available=0) is a hard override; restock above the critical band makes the product orderable again on its own.

Per-IP brute-force throttle. login_throttle (3.21) tracks failed_attempts and lockout_until per source IP (one upserted row per IP), complementing the per-account counter on user. This adds a second throttling dimension so a single IP hammering many accounts is slowed independently of any one account's counter. A daily cron purges idle, non-locked rows.

References: docs/notes/revue-alignement-p1.md §7 (D-decisions), security-by-design impact map (2026-06-11). Threat model and data-classification matrix: PROJECT_CONTEXT.md §19 (to come).

---

5. Entity count summary

#	Entity	Type	Replaces / new
1	category	business	v0.1 categorie (renamed + translated)
2	product	business	v0.1 produit (+ vat_rate)
3	menu	business	v0.1 menu (+ burger FK, 2 prices)
4	menu_slot	business	new — replaces menu_produit fixed composition
5	menu_slot_option	join	new — eligibility list per slot
6	ingredient	business	new — ingredient configurator + stock
7	product_ingredient	join	new — recipe + customization metadata
8	allergen	reference	new — INCO 1169/2011
9	ingredient_allergen	join	new — maps allergens to ingredients
10	customer_order	business	v0.1 commande (renamed, 4-state machine, phase timestamps)
11	order_item	business	v0.1 ligne_commande (+ format, vat_rate_snapshot)
12	order_item_selection	business	new — customer menu slot choices
13	order_item_modifier	business	new — ingredient-level modifications
14	user	business	v0.1 user (translated field names)
15	role	business	v0.1 role (+ default_route, order_source)
16	role_visible_source	join	new — per-role dashboard filter
17	permission	reference	v0.1 permission (translated, catalogue frozen)
18	role_permission	join	v0.1 role_permission (unchanged)
19	stock_movement	audit	new — append-only stock audit log
20	audit_log	audit	new (security-by-design) — append-only sensitive-action log
21	login_throttle	security	new (security-by-design) - per-IP brute-force throttle

Dropped from v0.1: commande_event (replaced by phase timestamps on customer_order), menu_produit (replaced by menu_slot + menu_slot_option model).

Total: 21 entities (19 prod-like v0.2 + audit_log and login_throttle from the security-by-design layer).

Security-by-design also adds columns (beyond the two new entities): user auth-lifecycle + pin_hash + anonymized_at (3.14), customer_order.acting_user_id + idempotency_key (3.10), and the percentage stock model on ingredient (3.6) — stock_capacity, critical_stock_pct, plus the rename of low_stock_threshold to low_stock_pct. login_throttle (3.21) is the 21st entity. See note 13.

---

For the ER diagram and cardinality justifications, see mcd.md — the diagram is the single source of truth for graphical representation.