corentin_wakdo/docs/merise/mlt.md

Model of Logical Treatments (MLT) — Wakdo

Merise phase : P1 - Conception, step 4 (derived from MCT) Version : v0.2 — prod-like, 4-state machine Date : 2026-06-04 Branch : feat/p1-conception Status : prod-like — all D1-D8 + stock decisions applied (see docs/notes/revue-alignement-p1.md §7) Author : BYAN (methodology layer)

---

1. Purpose

The MLT (Model of Logical Treatments) refines each MCT operation by specifying:

• preconditions — what must be true before execution
• business rules — validation, computation, business logic
• postconditions — the state guaranteed after success
• outputs — produced data or emitted events
• error cases — alternative outputs when a condition fails

It bridges the MCT (conceptual level) and the PHP/SQL implementation (physical level). All entity/attribute references use the names from docs/merise/dictionary.md (English, snake_case). All monetary amounts are in integer cents.

Tag conventions:

• [PRE] — precondition; must be satisfied for the operation to execute
• [RG] — business rule (regle de gestion); logic applied during execution
• [POST] — postcondition; database state guaranteed after success
• [OUT] — output; data or event produced
• [ERR] — error case; alternative output when a condition fails

---

2. Transverse business rules

These rules apply to multiple operations and are centralised here to avoid repetition.

Rule code	Label	Operations concerned
RG-T01	CSRF token verified on every back-office POST/PUT/DELETE form	AUTH, all admin ops
RG-T02	Session active + user.is_active = 1 verified on each authenticated request	All domains 3-10
RG-T03	Permission verified via role_permission before executing operation	All domains 3-10
RG-T04	All monetary amounts are manipulated in integer cents; EUR conversion at output only	3.3, 4.1, 8.1, 8.4
RG-T05	Snapshots (label_snapshot, unit_price_cents_snapshot, vat_rate_snapshot) on order_item are not modified after INSERT (historical integrity of placed orders — design guarantee)	3.3, 4.1, 8.2, 8.5
RG-T06	All SQL queries use PDO with prepared statements; no user data concatenated into SQL	All operations
RG-T07	Status transition UPDATE statements include AND status = <expected_status> in the WHERE clause (optimistic concurrency protection against double transition)	6.1, 7.1
RG-T08	Operations touching multiple tables execute in an atomic database transaction; partial failure triggers full rollback	3.3, 4.1, 7.1, 8.4, 9.1, 9.2
RG-T09	Cross-constraint on customer_order: source = 'drive' implies service_mode = 'drive'; verified at order creation. Materialisable as a MariaDB CHECK: CHECK (source != 'drive' OR service_mode = 'drive').	3.3, 4.1
RG-T10	VAT computation is line-by-line: each order_item carries its own vat_rate_snapshot (per-mille integer snapshotted from product.vat_rate). Order totals (total_ht_cents, total_vat_cents, total_ttc_cents) are the sum of line-level amounts.	3.3, 4.1
RG-T11	Stock decrements at the pending_payment -> paid transition and re-credits at paid -> cancelled are within the same database transaction as the status update (no orphan decrement).	3.3, 4.1, 7.1
RG-T12	Dashboard filter by source: each role's visible sources are read from role_visible_source; the query uses WHERE customer_order.source IN (role_visible_sources).	6.1

---

3. Domain 1 — Order lifecycle (kiosk)

3.1 LOAD_CATALOGUE

Corresponds to MCT section 3.1

Tag	Content
[PRE-1]	Request originates from the kiosk endpoint (public, no authentication required)
[PRE-2]	Current time is within the service window (10:00-01:00); outside the window the kiosk displays a closed message
[RG-1]	Read all category rows with is_active = 1, ordered by category.display_order ASC
[RG-2]	For each category, read product rows with is_available = 1 and matching category_id, ordered by product.display_order ASC
[RG-3]	Read all menu rows with is_available = 1; for each menu, load menu_slot rows ordered by menu_slot.display_order ASC; for each slot, load eligible products via menu_slot_option JOIN product (where product.is_available = 1)
[RG-4]	For each product, compute allergens by joining product_ingredient -> ingredient_allergen -> allergen (no manual re-entry per product)
[RG-5]	For each product with product_ingredient rows, load ingredient composition (for the configurator)
[RG-6]	Prices are returned in integer cents; EUR conversion is performed client-side
[POST-1]	No database write; database state unchanged
[OUT-1]	JSON response: {data: {categories: [...], products: {...}, menus: [{..., slots: [{..., options: [...]}]}]}}
[ERR-1]	DB unreachable: response {data: null, error: {code: "DB_ERROR"}} and front-end falls back to static JSON

---

3.2 COMPOSE_CART

Corresponds to MCT section 3.2

Tag	Content
[PRE-1]	Catalogue loaded into front-end memory (LOAD_CATALOGUE completed)
[PRE-2]	Selected item (product or menu) is present in the loaded catalogue with is_available = 1
[RG-1]	Cart is a JavaScript in-memory structure (array of items); no database persistence at this stage
[RG-2]	Each item contains: type (product or menu), item_id, label, unit_price_cents (snapshot from catalogue), quantity, format (normal or maxi, for menus), slot_selections (array of {menu_slot_id, product_id, label} for menu items), modifiers (array of {ingredient_id, action, extra_price_cents})
[RG-3]	Format Normal/Maxi (menu items only): normal uses menu.price_normal_cents; maxi uses menu.price_maxi_cents. No individual component price change is stored; the price differential is at menu level.
[RG-4]	Ingredient modifier rules: action = 'remove' requires is_removable = 1 on product_ingredient (free); action = 'add' requires is_addable = 1 (may carry extra_price_cents). These constraints are verified at cart composition time against the loaded catalogue.
[RG-5]	If an item with the same (type, item_id, format, slot_selections, modifiers) already exists in the cart, its quantity is incremented rather than adding a new item
[RG-6]	Cart total recomputed after each change: SUM(unit_price_cents * quantity + modifier_extras) across all items
[POST-1]	No database write; cart in-memory state updated
[OUT-1]	Cart summary displayed with TTC total
[ERR-1]	If a product becomes is_available = 0 between catalogue load and order submission, the server-side validation in CREATE_ORDER catches it

---

3.3 CREATE_ORDER

Corresponds to MCT section 3.3

Tag	Content
[PRE-1]	Cart contains at least 1 item (items.length >= 1)
[PRE-2]	Order number entered by customer is non-empty (front-end validation)
[PRE-3]	POST JSON body is valid (schema validation at API layer)
[RG-1]	Server-side availability check: for each item, verify product.is_available = 1 or menu.is_available = 1. If any item is unavailable, reject with list of unavailable articles.
[RG-2 — service_day]	service_day for a given order is computed at query time as: CASE WHEN HOUR(created_at) < 10 THEN DATE(created_at) - INTERVAL 1 DAY ELSE DATE(created_at) END. Cutoff is 10:00. This is NOT stored as a column — computed at query time only. The v0.1 formula with INTERVAL 4 HOUR 30 MINUTE was incorrect and is dropped.
[RG-3 — order number]	Order number format: K-YYYY-MM-DD-NNN where NNN is the sequential counter for the current service_day for the kiosk source (SELECT COUNT + 1 with a table-level lock or serialised insert to avoid duplicate generation under concurrency). Source is kiosk (set by the kiosk endpoint, derived from the public entry point).
[RG-4 — VAT by line]	For each order_item: vat_rate_snapshot is copied from product.vat_rate. Line amounts: unit_ttc = unit_price_cents_snapshot; unit_ht = ROUND(unit_ttc * 1000 / (1000 + vat_rate_snapshot)); unit_vat = unit_ttc - unit_ht. Order totals: total_ttc_cents = SUM(unit_ttc * quantity) across all lines; total_ht_cents = SUM(unit_ht * quantity); total_vat_cents = total_ttc_cents - total_ht_cents. Invariant: total_ttc_cents = total_ht_cents + total_vat_cents (verified before INSERT).
[RG-5 — atomic transaction]	All writes within one database transaction: (1) INSERT customer_order (status pending_payment, source kiosk, service_mode from cart, computed totals); (2) INSERT order_item rows (label_snapshot, unit_price_cents_snapshot, vat_rate_snapshot, quantity, format, item_type, product_id or menu_id); (3) INSERT order_item_selection rows for each slot filled in a menu item (order_item_id, menu_slot_id, product_id, label_snapshot); (4) INSERT order_item_modifier rows for each ingredient modification (order_item_id, ingredient_id, action, extra_price_cents snapshot); (5) for each ingredient consumed: compute units = (order_item.format = 'maxi' ? product_ingredient.quantity_maxi : product_ingredient.quantity_normal) * order_item.quantity, adjusted by modifiers (remove => no decrement for that ingredient; add => extra decrement); UPDATE ingredient.stock_quantity -= units; INSERT stock_movement (type sale, delta = -units, order_id, user_id = NULL for kiosk); (6) UPDATE customer_order SET status = paid, paid_at = NOW(). All six steps commit together or roll back entirely.
[RG-6 — cross-constraint]	Source kiosk implies no particular service_mode constraint; the customer selects dine_in or takeaway. The drive cross-constraint (RG-T09) does not apply to kiosk-originated orders.
[RG-7 — immutability]	After INSERT, label_snapshot, unit_price_cents_snapshot, and vat_rate_snapshot are not modified even if the source product is later renamed or repriced (see RG-T05).
[POST-1]	One customer_order row exists with status = 'paid', source = 'kiosk', all totals computed, paid_at set. The pending_payment phase is not observable outside the transaction.
[POST-2]	N order_item rows exist, each referencing either a product_id (item_type='product') or a menu_id (item_type='menu') — exclusivity constraint verified.
[POST-3]	customer_order.order_number is unique in the database (UNIQUE constraint).
[POST-4]	ingredient.stock_quantity decremented for each consumed ingredient unit; one stock_movement row of type sale per affected ingredient.
[OUT-1]	HTTP 201: {data: {id: int, order_number: string, status: 'paid'}}
[OUT-2]	Logical event ORDER_CREATED available for preparation domain (preparation display refreshes via polling or server push depending on implementation)
[ERR-1]	Empty cart: HTTP 422, {error: {code: "EMPTY_CART"}}
[ERR-2]	Unavailable item: HTTP 422, {error: {code: "ITEM_UNAVAILABLE", items: [...]}}
[ERR-3]	DB error / timeout: HTTP 500 with rollback, {error: {code: "DB_ERROR"}}

---

3.4 DISPLAY_CONFIRMATION

Corresponds to MCT section 3.4

Tag	Content
[PRE-1]	CREATE_ORDER returned HTTP 201 with {id, order_number, status: 'paid'}
[RG-1]	Order number displayed prominently on the confirmation screen
[RG-2]	After a configurable delay (suggestion: 15 seconds), the kiosk auto-resets for the next customer
[POST-1]	No database write
[OUT-1]	Confirmation screen displayed with order number
[ERR-1]	If API response is an error: generic error message displayed with option to retry

---

4. Domain 2 — Order lifecycle (counter and drive)

4.1 CREATE_COUNTER_ORDER

Corresponds to MCT section 4.1

Tag	Content
[PRE-1]	Actor is authenticated (valid session, user.is_active = 1)
[PRE-2]	Actor holds permission order.create (verified via role_permission)
[PRE-3]	Cart contains at least 1 item
[RG-1]	Creation logic identical to CREATE_ORDER (RG-1 through RG-7 apply), with the following differences: source is auto-tagged from role.order_source (counter role -> counter, drive role -> drive); service_mode is selected by the staff member (dine_in / takeaway / drive); user_id is set to the authenticated user's id in stock_movement rows (instead of NULL for kiosk).
[RG-2 — cross-constraint]	If source = 'drive' then service_mode must be 'drive' (RG-T09); verified before INSERT. HTTP 422 if violated.
[RG-3 — order number]	Format: C-YYYY-MM-DD-NNN for counter source; D-YYYY-MM-DD-NNN for drive source. Sequential NNN counter is per source per service_day.
[RG-4 — stock]	Same stock decrement logic as CREATE_ORDER RG-5; stock_movement.user_id is set to the authenticated staff member's id.
[POST-1]	One customer_order row with status = 'paid', source = 'counter' or 'drive', paid_at set.
[POST-2]	N order_item rows with snapshots. Slot selections and modifiers written identically to kiosk flow.
[POST-3]	Stock decremented; movements logged with actor user_id.
[OUT-1]	HTTP 201: {data: {id: int, order_number: string, status: 'paid'}}. Order number communicated to customer.
[ERR-1]	Same error cases as CREATE_ORDER (ERR-1, ERR-2, ERR-3)
[ERR-2]	Cross-constraint violation (source = drive but service_mode != drive): HTTP 422, {error: {code: "INVALID_SERVICE_MODE"}}

---

5. Domain 3 — Preparation display (kitchen)

5.1 LIST_ORDERS_DISPLAY

Corresponds to MCT section 5.1

Tag	Content
[PRE-1]	Actor is authenticated, is_active = 1
[PRE-2]	Actor holds permission order.read
[RG-1 — source filter]	Retrieve visible sources for the actor's role: SELECT source FROM role_visible_source WHERE role_id = :role_id. Kitchen sees all three; counter sees kiosk and counter; drive sees drive.
[RG-2 — query]	SELECT customer_order.*, order_item.* FROM customer_order JOIN order_item ON order_item.order_id = customer_order.id WHERE customer_order.status = 'paid' AND customer_order.source IN (:visible_sources) ORDER BY customer_order.paid_at ASC
[RG-3 — item detail]	For each order line of type menu, also load order_item_selection rows (slot choices). For all lines, load order_item_modifier rows (ingredient modifications). Display uses snapshots (label_snapshot, quantity, format); no re-join on product or menu tables needed.
[RG-4 — KDS colour]	Colour indicator computed at render time: elapsed = NOW() - customer_order.paid_at; green if elapsed < SLA threshold (configurable, approx. 10 min); amber if approaching; red if exceeded. Not stored; computed client-side or in PHP before response.
[RG-5 — read only]	Kitchen staff perform no status transition from this view. No UPDATE is issued by this operation.
[POST-1]	No database write
[OUT-1]	List of orders with status paid, filtered by role, sorted by paid_at ascending, with full item detail (selections, modifiers, KDS colour)

---

6. Domain 4 — Delivery to customer

6.1 DELIVER_ORDER

Corresponds to MCT section 6.1

Tag	Content
[PRE-1]	Actor is authenticated, holds permission order.deliver
[PRE-2]	Targeted order exists and status = 'paid'
[PRE-3]	Order source is in the actor's visible sources (verified via role_visible_source)
[RG-1]	UPDATE customer_order SET status = 'delivered', delivered_at = NOW(), updated_at = NOW() WHERE id = :id AND status = 'paid'
[RG-2 — concurrency]	The AND status = 'paid' clause in the UPDATE protects against concurrent double-delivery: if two staff members click simultaneously, only the first succeeds (second receives 0 rows affected).
[RG-3]	delivered is a terminal status: no further transition is defined from this status (application constraint, not enforced as a DB trigger).
[POST-1]	customer_order.status = 'delivered', delivered_at set, lifecycle complete. Order passes to history.
[OUT-1]	HTTP 200 with confirmation. Order disappears from the paid queue.
[ERR-1]	Invalid transition (status was not paid when UPDATE executed — concurrency): HTTP 409, {error: {code: "INVALID_TRANSITION"}}
[ERR-2]	Order source not in actor's visible sources: HTTP 403, {error: {code: "FORBIDDEN"}}

---

7. Domain 5 — Cancellation

7.1 CANCEL_ORDER

Corresponds to MCT section 7.1

Tag	Content
[PRE-1]	Actor is authenticated, holds permission order.cancel
[PRE-2]	Targeted order exists
[PRE-3]	customer_order.status is in ['pending_payment', 'paid']. Terminal statuses delivered and cancelled cannot transition to cancelled.
[RG-1 — status update]	UPDATE customer_order SET status = 'cancelled', cancelled_at = NOW(), updated_at = NOW() WHERE id = :id AND status IN ('pending_payment', 'paid')
[RG-2 — concurrency]	The AND status IN (...) clause protects against concurrent cancellation (see RG-T07).
[RG-3 — stock re-credit — conditional]	Re-credit applies only if the order was at status paid before cancellation. Orders at pending_payment had not yet decremented stock (the decrement occurs at the paid transition). For each order_item line of a paid order, recompute ingredient units consumed: (order_item.format = 'maxi' ? product_ingredient.quantity_maxi : product_ingredient.quantity_normal) * order_item.quantity, adjusted by order_item_modifier rows (remove modifier -> ingredient was not decremented, so no re-credit; add modifier -> ingredient had extra decrement, so extra re-credit). UPDATE ingredient.stock_quantity += units. INSERT stock_movement (type cancellation, delta = +units, order_id, user_id of actor).
[RG-4 — transaction]	Status update and stock re-credit (when applicable) execute in the same database transaction (RG-T11).
[RG-5 — history]	Order is not physically deleted; retained for history and stats. Cancelled orders are excluded from revenue totals but included in volume counts in READ_STATS. order_item rows are not deleted (ON DELETE CASCADE is not triggered); they allow reconstruction of what was ordered.
[POST-1]	customer_order.status = 'cancelled', cancelled_at set, terminal state.
[POST-2]	If prior status was paid: ingredient.stock_quantity re-credited; one stock_movement row of type cancellation per affected ingredient.
[OUT-1]	HTTP 200 with cancellation confirmation
[ERR-1]	Attempt to cancel a delivered or already cancelled order: HTTP 422, {error: {code: "CANNOT_CANCEL_IN_STATE", current_status: "..."}}
[ERR-2]	Concurrent cancellation (0 rows affected by UPDATE): HTTP 409, {error: {code: "INVALID_TRANSITION"}}

---

8. Domain 6 — Catalogue management

8.1 CREATE_PRODUCT

Corresponds to MCT section 8.1

Tag	Content
[PRE-1]	Actor authenticated, holds permission product.create
[PRE-2]	category_id references an existing category with is_active = 1
[RG-1]	Form validation: name non-empty, price_cents > 0, category_id valid, vat_rate in (55, 100)
[RG-2]	Image upload (optional): validate MIME type (JPEG, PNG, WEBP), max size configurable (suggestion: 2 MB), store under UPLOAD_DIR/products/, record relative path in image_path
[RG-3]	is_available = 1 by default at INSERT
[RG-4]	display_order set to MAX(display_order) + 1 for the target category, or 0 if first product
[POST-1]	One product row in the database with all valid fields
[OUT-1]	Redirect to category product list with success message
[ERR-1]	Validation failure: inline field errors displayed
[ERR-2]	Invalid image (type or size): specific error message

---

8.2 UPDATE_PRODUCT

Corresponds to MCT section 8.2

Tag	Content
[PRE-1]	Actor authenticated, holds permission product.update
[PRE-2]	Target product.id exists
[RG-1]	Same validations as CREATE_PRODUCT on modified fields
[RG-2]	If a new image is uploaded, the old image file is deleted from the filesystem (volume cleanup)
[RG-3]	label_snapshot, unit_price_cents_snapshot, vat_rate_snapshot in historical order_item rows are not modified (see RG-T05)
[POST-1]	product updated, updated_at refreshed
[OUT-1]	Redirect to product list with success message

---

8.3 DELETE_PRODUCT

Corresponds to MCT section 8.3

Tag	Content
[PRE-1]	Actor authenticated, holds permission product.delete
[PRE-2]	Target product.id exists
[RG-1]	Pre-check (PHP): is the product referenced in menu_slot_option.product_id? If yes, display blocking message listing the menus.
[RG-2]	Pre-check (PHP): is the product the burger_product_id of any menu? If yes, block with message to delete or reassign the menu first.
[RG-3]	Pre-check (PHP): is the product referenced in order_item.product_id (historical orders)? FK ON DELETE RESTRICT blocks at DB level. Recommended response: propose deactivation (is_available=0) rather than deletion.
[RG-4]	FK constraints (menu_slot_option.product_id ON DELETE RESTRICT, order_item.product_id ON DELETE RESTRICT) enforce the constraint even if the PHP check is bypassed.
[POST-1]	Product deleted if no FK constraint was blocking
[OUT-1]	Redirect to product list with success message
[ERR-1]	Product in menu slot: HTTP 422 or inline message with blocking menu list
[ERR-2]	Product in historical orders: message proposing deactivation instead

---

8.4 CREATE_MENU

Corresponds to MCT section 8.4

Tag	Content
[PRE-1]	Actor authenticated, holds permission menu.create
[PRE-2]	burger_product_id references an existing, available product
[PRE-3]	At least one menu_slot is defined with at least one menu_slot_option
[RG-1]	Validation: name non-empty, price_normal_cents > 0, price_maxi_cents > 0, burger_product_id valid, all product_id values in slot options exist
[RG-2]	Transaction: INSERT menu, then INSERT menu_slot rows (name, slot_type, is_required, display_order), then INSERT menu_slot_option rows (menu_slot_id, product_id)
[RG-3]	Valid slot_type values (from dictionary ENUM): drink, side, sauce, dessert, extra
[POST-1]	One menu row, N menu_slot rows, M menu_slot_option rows in the database
[OUT-1]	Redirect to menu list with success message
[ERR-1]	Invalid configuration (no slot, no option): business error message
[ERR-2]	Slot option product unavailable: warning (menu can be created; product availability is checked at order time)

---

8.5 UPDATE_MENU

Corresponds to MCT section 8.5

Tag	Content
[PRE-1]	Actor authenticated, holds permission menu.update
[PRE-2]	Target menu.id exists
[RG-1]	Same validations as CREATE_MENU on modified fields
[RG-2]	If slot configuration is modified: DELETE FROM menu_slot_option WHERE menu_slot_id IN (SELECT id FROM menu_slot WHERE menu_id = :id), then DELETE FROM menu_slot WHERE menu_id = :id, then re-INSERT (delete-and-reinsert pattern, atomic in transaction)
[RG-3]	label_snapshot values in historical order_item_selection rows are not affected (see RG-T05)
[POST-1]	menu updated; menu_slot and menu_slot_option rebuilt
[OUT-1]	Redirect with success message

---

8.6 DELETE_MENU

Corresponds to MCT section 8.6

Tag	Content
[PRE-1]	Actor authenticated, holds permission menu.delete
[PRE-2]	Target menu.id exists
[RG-1]	Pre-check (PHP): is the menu referenced in order_item.menu_id? FK ON DELETE RESTRICT. If yes, propose deactivation (is_available=0) instead of deletion.
[RG-2]	If no historical reference: DELETE menu triggers CASCADE to menu_slot (which cascades to menu_slot_option)
[POST-1]	menu, its menu_slot rows, and its menu_slot_option rows deleted
[OUT-1]	Redirect with success message
[ERR-1]	Menu in historical orders: message proposing deactivation instead

---

8.7 MANAGE_CATEGORY

Corresponds to MCT section 8.7

Tag	Content
[PRE-1]	Actor authenticated, holds permission category.manage
[RG-CREATE]	name and slug non-empty and unique in the database; display_order set to MAX + 1
[RG-UPDATE]	UPDATE name, slug, image_path, display_order, is_active
[RG-DEACTIVATE]	Deactivation (is_active=0) does not auto-deactivate child products/menus in the DB (no CASCADE on is_active). PHP layer proposes to the admin to also deactivate child products/menus, or the kiosk filter on category.is_active = 1 implicitly hides them.
[RG-DELETE]	Physical deletion blocked if product.category_id or menu.category_id references this category (FK ON DELETE RESTRICT). Propose deactivation.
[POST-CREATE]	New category row in database
[POST-UPDATE]	category updated, updated_at refreshed
[OUT-1]	Confirmation, redirect to category list

---

8.8 MANAGE_INGREDIENT

Corresponds to MCT section 8.8

Tag	Content
[PRE-1]	Actor authenticated, holds permission ingredient.manage
[RG-CREATE-ING]	name non-empty and UNIQUE; unit non-empty; pack_size >= 1; low_stock_threshold >= 0; stock_quantity defaults to 0 at creation
[RG-UPDATE-ING]	UPDATE name, unit, pack_size, pack_label, low_stock_threshold, is_active
[RG-DEACTIVATE-ING]	is_active=0 hides ingredient from configurator. Physical deletion blocked if referenced in product_ingredient (FK ON DELETE RESTRICT) or stock_movement (FK ON DELETE RESTRICT).
[RG-COMPOSITION]	UPDATE product_ingredient: for each ingredient in a product's recipe, set quantity_normal, quantity_maxi, is_removable, is_addable, extra_price_cents. Delete-and-reinsert pattern within transaction.
[RG-ALLERGEN]	Manage ingredient_allergen: INSERT or DELETE (ingredient_id, allergen_id) pairs. Allergen list is read-only (14 rows fixed by EU regulation 1169/2011).
[POST-1]	ingredient / product_ingredient / ingredient_allergen rows updated
[OUT-1]	Confirmation, redirect to ingredient list or product composition form

---

9. Domain 7 — Stock management

9.1 RESTOCK

Corresponds to MCT section 9.1

Tag	Content
[PRE-1]	Actor authenticated, holds permission stock.manage
[PRE-2]	Target ingredient exists and is_active = 1
[PRE-3]	Number of packs N >= 1
[RG-1]	delta = N * ingredient.pack_size
[RG-2]	Transaction: UPDATE ingredient SET stock_quantity = stock_quantity + :delta WHERE id = :id; INSERT stock_movement (ingredient_id, movement_type=restock, delta=+delta, order_id=NULL, user_id=actor, note=optional)
[RG-3]	stock_movement is append-only: no UPDATE or DELETE on this table (corrections are new rows)
[POST-1]	ingredient.stock_quantity incremented by delta. One stock_movement row of type restock inserted.
[OUT-1]	Confirmation with new stock level displayed

---

9.2 INVENTORY_COUNT

Corresponds to MCT section 9.2

Tag	Content
[PRE-1]	Actor authenticated, holds permission stock.count
[PRE-2]	Target ingredient exists
[PRE-3]	actual_quantity >= 0 (physical count is non-negative)
[RG-1]	delta = actual_quantity - ingredient.stock_quantity (may be negative if actual < theoretical)
[RG-2]	Transaction: UPDATE ingredient SET stock_quantity = :actual_quantity WHERE id = :id; INSERT stock_movement (ingredient_id, movement_type=inventory_correction, delta=computed, order_id=NULL, user_id=actor, note=optional)
[RG-3]	delta = 0 is a valid correction (physical count matches theoretical); a movement row is still inserted for audit completeness
[POST-1]	ingredient.stock_quantity = actual_quantity. One stock_movement row of type inventory_correction inserted.
[OUT-1]	Confirmation with reconciled stock level and discrepancy displayed

---

9.3 READ_STOCK

Corresponds to MCT section 9.3

Tag	Content
[PRE-1]	Actor authenticated, holds permission stock.read
[RG-1]	SELECT * FROM ingredient WHERE is_active = 1 ORDER BY name ASC
[RG-2]	Low-stock alert computed at render time: stock_quantity <= low_stock_threshold -> flag low_stock: true in response. Not stored as a column.
[RG-3]	Optional movement history for a given ingredient: SELECT * FROM stock_movement WHERE ingredient_id = :id ORDER BY created_at DESC LIMIT :n
[POST-1]	No database write
[OUT-1]	Ingredient list with stock_quantity, low_stock_threshold, pack_size, pack_label, low_stock flag

---

10. Domain 8 — User and role management

10.1 CREATE_USER

Corresponds to MCT section 10.1

Tag	Content
[PRE-1]	Actor authenticated, holds permission user.create
[PRE-2]	Email does not already exist in user.email (UNIQUE constraint)
[PRE-3]	role_id references an existing, active role
[RG-1]	Validation: email conforms to RFC 5321 (PHP FILTER_VALIDATE_EMAIL), first_name and last_name non-empty, role_id valid
[RG-2]	Password hash: password_hash($password, PASSWORD_ARGON2ID). Minimum password length: 8 characters.
[RG-3]	is_active = 1 by default; last_login_at = NULL at creation
[POST-1]	One user row with argon2id password_hash, valid role_id
[OUT-1]	Redirect to user list with success message
[ERR-1]	Duplicate email: message "This email is already in use"
[ERR-2]	Password too short: inline validation message

---

10.2 UPDATE_USER

Corresponds to MCT section 10.2

Tag	Content
[PRE-1]	Actor authenticated, holds permission user.update
[PRE-2]	Target user.id exists
[RG-1]	If a new password is supplied (non-empty field): rehash via PASSWORD_ARGON2ID and replace existing hash
[RG-2]	If password field is empty: existing hash is preserved unchanged
[RG-3]	Email update subject to UNIQUE constraint (pre-check before UPDATE)
[POST-1]	user updated, updated_at refreshed
[OUT-1]	Redirect with success message

---

10.3 DEACTIVATE_USER

Corresponds to MCT section 10.3

Tag	Content
[PRE-1]	Actor authenticated, holds permission user.deactivate
[PRE-2]	Actor is not targeting their own account ($targetUserId !== $currentUserId)
[RG-1]	UPDATE user SET is_active = 0, updated_at = NOW() WHERE id = :id
[RG-2]	The user's potentially active session is invalidated on next request: middleware checks user.is_active = 1 on each authenticated request
[POST-1]	user.is_active = 0; user cannot log in; history remains intact
[OUT-1]	Redirect with success message
[ERR-1]	Self-deactivation attempt: HTTP 403, {error: {code: "SELF_DEACTIVATION_FORBIDDEN"}}

---

10.4 MANAGE_RBAC

Corresponds to MCT section 10.4

Tag	Content
[PRE-1]	Actor authenticated, holds permission role.manage
[PRE-2]	Target role.id exists (for permission update) or role fields are valid (for role creation)
[PRE-3]	All submitted permission_id values exist in the permission catalogue
[RG-1 — permissions]	Transaction: DELETE FROM role_permission WHERE role_id = :id; INSERT new (role_id, permission_id) pairs for each selected permission
[RG-2]	Permissions are not modifiable via this operation: they are read-only to populate the selection form. Permission catalogue is frozen at seed.
[RG-3]	Effect is immediate for new requests; sessions of users bearing this role see the change on the next permission check (sessions store role_id; permissions are reloaded from DB on each check).
[RG-4 — custom role]	Creating a custom role: INSERT role (code UNIQUE, label, description, default_route nullable, order_source nullable); INSERT role_visible_source rows as needed.
[RG-5 — order_source]	role.order_source controls the auto-tagging of customer_order.source when this role creates an order. NULL for admin and manager (they can create on behalf of any channel).
[POST-1]	role_permission reflects exactly the selected permissions for this role
[OUT-1]	Redirect with success message

---

11. Domain 9 — Stats and KPI

11.1 READ_STATS

Corresponds to MCT section 11.1

Tag	Content
[PRE-1]	Actor authenticated, holds permission stats.read
[RG-1 — service_day]	service_day expression used in all stats aggregations: CASE WHEN HOUR(customer_order.created_at) < 10 THEN DATE(customer_order.created_at) - INTERVAL 1 DAY ELSE DATE(customer_order.created_at) END. Cutoff at 10:00. No stored column. The v0.1 formula with INTERVAL 4 HOUR 30 MINUTE is dropped.
[RG-2 — revenue]	Revenue queries filter status != 'cancelled'; they sum total_ttc_cents from customer_order. Cancelled orders are excluded from revenue but appear in volume counts with status = 'cancelled' filter.
[RG-3 — top products]	SELECT label_snapshot, SUM(quantity) AS total_sold FROM order_item JOIN customer_order ON ... WHERE customer_order.status != 'cancelled' GROUP BY label_snapshot ORDER BY total_sold DESC LIMIT 10
[RG-4 — delivery time KPI]	Average delivery time: AVG(TIMESTAMPDIFF(SECOND, paid_at, delivered_at)) on orders with status = 'delivered'. SLA reference approx. 10 min (configurable).
[RG-5 — breakdown]	Breakdowns available by source (kiosk/counter/drive) and service_mode (dine_in/takeaway/drive) for capacity planning. service_mode carries no fiscal role (see dictionary note 9).
[POST-1]	No database write
[OUT-1]	Stats dashboard data: revenue by service_day, order counts, top products, cancellation rate, average delivery time, breakdown by source/service_mode

---

12. Domain 10 — Back-office authentication

12.1 AUTHENTICATE_USER

Corresponds to MCT section 12.1

Tag	Content
[PRE-1]	Login form submitted with email and password
[PRE-2]	CSRF token of the form is valid (anti-CSRF protection)
[RG-1]	Lookup: SELECT * FROM user WHERE email = :email AND is_active = 1 LIMIT 1
[RG-2]	Password verification: password_verify($password, $user->password_hash). On failure: same generic error whether the email does not exist or the password is wrong (protection against email enumeration).
[RG-3]	On success: session_regenerate(true) (session ID regeneration, protection against session fixation)
[RG-4]	Session storage: $_SESSION['user_id'], $_SESSION['role_id'], $_SESSION['logged_in_at']
[RG-5]	UPDATE: UPDATE user SET last_login_at = NOW() WHERE id = :id
[RG-6]	Session timeouts: idle timeout 4h (detection via last-activity timestamp in session); absolute timeout 10h (detection via logged_in_at)
[RG-7]	Redirect target is role.default_route (dynamic; no hardcoded role name in routing logic)
[POST-1]	PHP session open with user_id and role_id; user.last_login_at updated
[OUT-1]	Redirect to role.default_route
[ERR-1]	Incorrect credentials or inactive account: generic message "Email or password incorrect" (no distinction to prevent enumeration)
[ERR-2]	Invalid CSRF token: HTTP 403

---

12.2 LOGOUT_USER

Corresponds to MCT section 12.2

Tag	Content
[PRE-1]	Valid session open (session_id() non-empty, $_SESSION['user_id'] present)
[RG-1]	$_SESSION = [] (clear session data)
[RG-2]	If session cookie exists, expire it: setcookie(session_name(), '', time() - 3600, '/', '', true, true)
[RG-3]	session_destroy()
[POST-1]	PHP session destroyed; no authenticated access possible with the old cookie
[OUT-1]	Redirect to login page

---

13. Automated treatments — Crons (outside user interactions)

These treatments are executed by the wakdo-cron service container in the maintenance window 01:30-09:30 (outside active service). They are outside the MCT scope (technical treatments, no user trigger) but are documented here for consistency with PROJECT_CONTEXT.

13.1 Stats aggregation (cron 04:30)

Tag	Content
[TRIGGER]	Cron: 30 4 * * *
[RG-1]	service_day to aggregate: computed per order (see RG-1 of READ_STATS). At 04:30 the service_day in progress is the previous calendar day.
[RG-2]	Aggregations by service_day: order count, TTC revenue (sum total_ttc_cents where status != 'cancelled'), top products (by label_snapshot, COUNT in order_item)
[POST-1]	Stats available for admin dashboard (direct queries on customer_order filtered by service_day, or an aggregation table if implemented)

13.2 Expired sessions purge (cron every 15 min)

Tag	Content
[TRIGGER]	Cron: */15 * * * *
[RG-1]	File-based sessions (default): find /tmp/sessions -mmin +240 -delete
[RG-2]	DB-based sessions (option): DELETE FROM php_sessions WHERE updated_at < NOW() - INTERVAL 4 HOUR
[POST-1]	Expired sessions deleted; users inactive for more than 4h are forced to re-login

13.3 DB backup (cron 03:00)

Tag	Content
[TRIGGER]	Cron: 0 3 * * *
[RG-1]	mysqldump of the wakdo database to a dated file in the backup volume
[RG-2]	Retention: keep the last 7 dumps; delete older ones
[POST-1]	SQL dump available for restoration

---

14. State machine — consistency recap (MLT)

Summary of customer_order.status transitions covered in the MLT, with corresponding operations, SQL condition, concurrency protection, and phase timestamp set.

Transition	MLT operation	SQL condition	Concurrency protection	Phase timestamp set
-> pending_payment (creation)	CREATE_ORDER (3.3), CREATE_COUNTER_ORDER (4.1)	INSERT with status pending_payment	Atomic transaction	created_at
pending_payment -> paid	CREATE_ORDER (3.3), CREATE_COUNTER_ORDER (4.1)	UPDATE in same transaction	Atomic transaction	paid_at
paid -> delivered	DELIVER_ORDER (6.1)	WHERE status = 'paid'	AND status in WHERE	delivered_at
pending_payment/paid -> cancelled	CANCEL_ORDER (7.1)	WHERE status IN ('pending_payment', 'paid')	AND status IN WHERE	cancelled_at

Terminal statuses (no further transition defined from these states): delivered, cancelled.

Dropped from v0.1:

• paid -> preparing and preparing -> ready transitions — intermediate states removed.
• MARQUER_EN_PREPARATION (v0.1 MLT section 4.2) — dropped.
• MARQUER_PRETE (v0.1 MLT section 4.3) — dropped.
• preparing and ready in the cancellable state set — the cancellable set is now ['pending_payment', 'paid'] only.
• commande_event table and v0.1 RG-T10 — replaced by phase timestamps on customer_order.

---

15. Residual notes and open points

15.1 service_day — not materialised as a column

The service_day computation is documented (RG-2 of CREATE_ORDER, RG-1 of READ_STATS): CASE WHEN HOUR(created_at) < 10 THEN DATE(created_at) - INTERVAL 1 DAY ELSE DATE(created_at) END (cutoff 10:00). It is computed at query time, not stored. For high-frequency stats queries, a MariaDB generated column VIRTUAL or STORED could be added at DDL time to avoid per-row recomputation, but this is not a blocker for the RNCP scope. The v0.1 formula with INTERVAL 4 HOUR 30 MINUTE was incorrect and is dropped.

15.2 order_item_modifier for menu items

For a menu line (item_type='menu'), modifiers target the fixed burger identified via order_item.menu_id -> menu.burger_product_id. The constraint that modifiers reference only ingredients belonging to the burger's product_ingredient is enforced at the application layer, not at the DB FK layer (see dictionary note 10). This is a known trade-off: a multi-column FK or a DB trigger would be needed to enforce it at DB level. Documenting it as an application invariant is the retained approach for this project scope.

15.3 Order number NNN counter — concurrency

The sequential NNN counter per (source, service_day) could produce duplicates under high concurrency if implemented naively as SELECT COUNT + 1. The recommended implementation at DDL/code time is either: (a) a table-level advisory lock around the count-and-insert sequence; or (b) a dedicated sequence table with an atomic increment. The UNIQUE constraint on order_number provides the last-resort guard (INSERT would fail and the application retries). This is not a blocker for the RNCP demo volume.