corentin_wakdo/docs/api/conventions.md

API Wakdo - conventions de nommage, structure et listing

Statut : v0.2 - convention de casse arbitree (snake_case, voir section 4) Perimetre : back-office admin (rendu serveur) + API REST sous /api/* Auteur methodologie : BYAN A lire avec : docs/PROJECT_CONTEXT.md, docs/merise/dictionary.md (source de verite des noms de champs), docs/merise/mct.md + mlt.md (operations metier), db/seeds/0001_rbac_and_reference.sql (catalogue des 23 permissions). NB : docs/api/byan-api.md documente l'API de la plateforme BYAN, distincte de l'API Wakdo decrite ici.

---

1. Objet

Fixer les conventions de nommage, la structure des points d'entree HTTP de Wakdo, et tenir le listing des endpoints (en service et prevus). Objectif : que chaque endpoint ajoute suive le meme moule. Les choix sont des conventions de projet (coherence, lisibilite), pas des regles universelles ; une convention peut evoluer, auquel cas ce document est mis a jour en premier.

---

2. Par quoi passe une requete

Deux hotes distincts, un seul conteneur web (Apache), routes par le Traefik de l'hote :

Client (borne / navigateur back-office)
  -> Traefik (TLS, ajoute X-Forwarded-For, route par Host)
    -> wakdo-web (Apache, vhost selon le Host)
       - vhost kiosk  : DocumentRoot src/public/borne  (statique + futur appel /api)
       - vhost admin  : DocumentRoot src/public/admin
         - fichier existant (login.html, *.css) : servi tel quel
         - sinon RewriteRule -> index.php (front controller)
    -> wakdo-app (PHP-FPM, via proxy FastCGI sur *.php)
       front controller -> Router -> Controller -> Response
    -> wakdo-db (MariaDB, requetes preparees PDO uniquement)

Consequence de nommage : le DocumentRoot du vhost admin est src/public/admin, donc le REQUEST_URI arrive sans prefixe /admin. Le Router voit /login, /api/health, etc. On n'ajoute pas de segment /admin dans les chemins de routes.

Code de reference : routes dans src/public/admin/index.php, controleurs dans src/app/Controllers/, enveloppe de reponse dans src/app/Core/Response.php, resolution (404 / 405) dans src/app/Core/Router.php.

---

3. Deux familles d'endpoints

Famille	Prefixe	Rendu	Authentification	Exemple
Pages back-office	aucun	HTML (vue serveur + layout.php)	session admin	/login, /forgot_password
API REST	/api/	JSON (enveloppe section 7)	selon la ressource (section 10)	/api/health, /api/categories (prevu)

La borne (kiosk) consommera l'API REST /api/* (P4). En attendant, elle lit un repli JSON statique sous src/public/borne/data/ (voir section 8.3).

---

4. Nommage des chemins (URL)

Deux decisions, dont une sourcee et une de coherence :

• Minuscules sur tout le chemin. Sourced : RFC 3986 §6.2.2.1 - seuls le scheme et l'hote sont insensibles a la casse, le path est sensible a la casse ; le minuscule evite les bugs de casse.
• Separateur de mots : _ (snake_case). Aucun standard n'impose - ou _ dans un segment (les deux sont des caracteres unreserved, RFC 3986 §2.3). On retient _ pour n'avoir qu'une seule convention de casse sur tout le projet : colonnes DB, champs JSON (section 8) et chemins d'URL partagent le snake_case. Cela calque les noms de tables (order_item -> /api/order_items) et reduit la charge a memoriser (Rasoir d'Ockham, mantra #37).

Autres regles :

• Noms de ressources au pluriel pour les collections : /api/categories, /api/products, /api/orders.
• Identifiant en segment pour une ressource unitaire : /api/orders/{number}, /api/products/{id}. Parametre dynamique : {nom} (groupe nomme cote Router).
• Sous-ressource par imbrication : /api/orders/{id}/items (prevu).
• Action non-CRUD par sous-chemin verbe : POST /api/orders/{id}/cancel (cf. docs/uml/security-sequence.md).
• Pas de barre oblique finale signifiante : Request::normalizePath aligne /api/health/ et /api/health.

---

5. Listing des endpoints

5.1 En service (P2)

Methode	Chemin	Auth	Rendu	Role
GET	/	(session en P3)	HTML	accueil back-office (squelette)
GET	/api/health	public	JSON (plat)	sonde de sante (DB reelle)
GET	/login	public	HTML	formulaire de connexion
POST	/login	public + CSRF	302 / HTML	authentification (mlt 12.1)
POST	/logout	session + CSRF	302	deconnexion (mlt 12.2)
GET	/forgot_password	public	HTML	demande de reinitialisation
POST	/forgot_password	public + CSRF	HTML (neutre)	envoi du lien (mlt 12.3)
GET	/reset_password	public (token en query)	HTML	formulaire nouveau mot de passe
POST	/reset_password	public + CSRF	302 / HTML	confirmation (mlt 12.3)

5.2 API kiosk - lecture catalogue + commande (prevu P4, public)

La borne est publique (aucune session) ; cf. mlt.md CREATE_ORDER, declencheur kiosk.

Methode	Chemin	Permission	Op MCT	Statut
GET	/api/categories	(lecture publique)	READ_CATALOGUE	prevu
GET	/api/products	(lecture publique)	READ_CATALOGUE	prevu
GET	/api/products/{id}	(lecture publique)	READ_CATALOGUE	prevu
GET	/api/menus	(lecture publique)	READ_CATALOGUE	prevu
GET	/api/menus/{id}	(lecture publique)	READ_CATALOGUE	prevu
POST	/api/orders	(kiosk public)	CREATE_ORDER (mlt 3.3)	prevu (idempotency_key, RG-T19)

5.3 API / pages back-office (prevu P3-P4, session + permission)

Provisoire : le choix entre endpoints JSON /api/* et pages rendues serveur pour les ecritures admin est tranche phase par phase (P3 CRUD). Les colonnes Permission renvoient au catalogue fige des 23 permissions (db/seeds/0001_rbac_and_reference.sql) ; l'imputabilite et le PIN suivent mlt.md RG-T13/RG-T14.

Commandes (cote equipier) :

Methode	Chemin	Permission	Op MCT	Note
GET	/api/orders	order.read	READ_ORDERS	filtre par role_visible_source (RG-T12)
GET	/api/orders/{number}	order.read	READ_ORDERS
POST	/api/orders (comptoir/drive)	order.create	CREATE_COUNTER_ORDER (mlt 4.1)	source auto-taggee
POST	/api/orders/{id}/deliver	order.deliver	DELIVER_ORDER (mlt 6.1)
POST	/api/orders/{id}/cancel	order.cancel	CANCEL_ORDER (mlt 7.1)	PIN + audit_log (RG-T13/14)

Catalogue (produits, menus, categories) :

Methode	Chemin	Permission	Op MCT
POST	/api/products	product.create	CREATE_PRODUCT (mlt 8.1)
PUT	/api/products/{id}	product.update	UPDATE_PRODUCT (mlt 8.2) - PIN sur prix/TVA
DELETE	/api/products/{id}	product.delete	DELETE_PRODUCT (mlt 8.3) - PIN
POST	/api/menus	menu.create	CREATE_MENU
PUT	/api/menus/{id}	menu.update	UPDATE_MENU
DELETE	/api/menus/{id}	menu.delete	DELETE_MENU - PIN
POST/PUT/DELETE	/api/categories[/{id}]	category.manage	MANAGE_CATEGORY

Stock et ingredients :

Methode	Chemin	Permission	Op MCT
GET	/api/ingredients	ingredient.manage	READ_INGREDIENTS
GET	/api/stock	stock.read	READ_STOCK
POST	/api/stock/restock	stock.manage	RESTOCK (mlt 9.1)
POST	/api/stock/count	stock.count	INVENTORY_COUNT (mlt 9.2) - PIN

Utilisateurs et RBAC :

Methode	Chemin	Permission	Op MCT
GET	/api/users	user.read	READ_USERS
POST	/api/users	user.create	CREATE_USER (mlt 10.1) - PIN
PUT	/api/users/{id}	user.update	UPDATE_USER (mlt 10.2) - PIN
POST	/api/users/{id}/deactivate	user.deactivate	DEACTIVATE_USER (mlt 10.3) - PIN
GET/PUT	/api/roles[/{id}/permissions]	role.manage	MANAGE_RBAC (mlt 10.4) - PIN

Statistiques :

Methode	Chemin	Permission	Op MCT
GET	/api/stats	stats.read	READ_STATS (mlt 11.x)

Les chemins exacts en 5.2/5.3 sont une projection a partir des operations MCT et des permissions seedees ; ils sont confirmes au moment d'ecrire chaque endpoint. Seule la section 5.1 est en service.

---

6. Methodes HTTP

Methode	Usage
GET	lecture, sans effet de bord
POST	creation, ou action de formulaire back-office (login, logout, reset)
PUT	mise a jour d'une ressource (prevu, CRUD admin P3)
DELETE	suppression d'une ressource (prevu)

Le Router fait une correspondance exacte de la methode : methode connue sur chemin connu mais non enregistree -> 405 ; chemin inconnu -> 404 (Router::dispatch). Une requete HEAD sur une route GET renvoie aujourd'hui 405 (correspondance exacte) ; un assouplissement reste possible si un besoin apparait.

---

7. Enveloppe de reponse JSON

L'API enveloppe ses reponses pour qu'un client distingue donnees et erreur de maniere uniforme.

Succes - ressource unitaire :

{ "data": { "id": 3, "name": "Big Mac", "price_cents": 590 } }

Succes - collection (total optionnel pour la pagination future) :

{ "data": [ { "id": 1 }, { "id": 2 } ], "total": 2 }

Erreur :

{ "data": null, "error": { "code": "NOT_FOUND", "message": "Resource not found" } }

Exception documentee : GET /api/health renvoie un objet de diagnostic plat (status, app_env, php_version, db, categories), hors enveloppe, car il sert le monitoring et non un client applicatif.

Type de contenu : application/json; charset=utf-8 (Response::json). Les pages back-office renvoient text/html; charset=utf-8.

---

8. Normalisation des noms de champs

8.1 Regle generale : snake_case aligne sur le dictionnaire

Les champs JSON reprennent les noms du dictionnaire (docs/merise/dictionary.md), source de verite, ce qui evite une couche de traduction entre base, code et contrat HTTP.

Categorie	Convention	Exemple
Champ simple	snake_case, anglais	display_order, image_path
Montant monetaire	entier en centimes, suffixe _cents	price_cents, total_ttc_cents
Taux de TVA	entier pour mille	vat_rate (55 = 5,5 % ; 100 = 10 %)
Booleen	prefixe is_	is_available, is_active
Horodatage	suffixe _at, ISO 8601 en sortie API	created_at, paid_at
Cle etrangere	suffixe _id	category_id, role_id
Valeur d'enumeration	minuscules snake_case	pending_payment, dine_in, kiosk
Identifiant	id (entier) ou order_number (chaine metier)	id, order_number

Les horodatages sont stockes en DATETIME ; leur exposition API se fait en ISO 8601 (a cadrer au moment d'ecrire les endpoints de lecture P4).

8.2 Codes d'erreur

SCREAMING_SNAKE_CASE, stables (un client peut s'y fier) ; le message reste lisible (non garanti stable).

Code	HTTP	Sens
NOT_FOUND	404	ressource introuvable
METHOD_NOT_ALLOWED	405	methode non autorisee sur ce chemin
VALIDATION_ERROR	422	entree invalide (champ, longueur, enum)
CONFLICT	409	conflit d'etat (ex. transition de commande concurrente)
AUTH_REQUIRED	401	authentification requise (prevu, API admin)
FORBIDDEN	403	permission insuffisante, ou jeton CSRF invalide cote formulaire
RATE_LIMITED	429	throttling (prevu)
INTERNAL_ERROR	500	erreur interne, message generique (pas de divulgation)

Codes specifiques nommes par le MLT, en surcharge du socle : CANNOT_CANCEL_IN_STATE (422) et INVALID_TRANSITION (409) pour l'annulation (mlt.md 7.1, security-sequence.md). Meme format d'enveloppe.

8.3 Divergence connue : repli JSON de la borne

Le repli statique de la borne (src/public/borne/data/categories.json, produits.json) provient des sources de l'ecole et porte un nommage different et heterogene (title/nom, prix, image, type). Ce contrat est fige par le brief ecole et consomme tel quel par le JS de la borne via data.js.

La convention canonique reste celle de 8.1. Le rapprochement se fait en un point unique : la couche data.js (bascule prevue en P4). Quand l'API exposera /api/categories et /api/products, elle servira la forme canonique ; data.js mappera vers ce que la borne attend.

Repli borne	Canonique API / dictionnaire
title (categorie)	name
nom (produit)	name
prix	price_cents
image	image_path
type	item_type (product / menu)

---

9. Authentification et sessions

• Cookie de session : WAKDO_SID (SESSION_NAME), attributs secure, HttpOnly, SameSite=Strict. Bornes de validite appliquees cote application (idle 4h, absolue 10h), pas par la duree du cookie.
• Formulaires back-office : jeton CSRF synchroniseur en champ cache _csrf, verifie sur chaque POST (/login, /logout, /forgot_password, /reset_password). Jeton invalide -> 403.
• API REST : endpoints kiosk de lecture catalogue et creation de commande publics (pas de session ; mlt.md CREATE_ORDER). Endpoints d'administration sous /api (P3/P4) : session admin + verification de permission via role_permission ; actions sensibles avec re-autorisation PIN (mlt.md RG-T13).

Le schema ApiKey / Bearer de l'API plateforme BYAN (docs/api/byan-api.md) ne s'applique pas ici.

---

10. CORS

L'API admin sous /api/* autorise l'origine du kiosk via CORS_ALLOWED_ORIGIN (valeur exacte, sans joker), configuree dans docker/apache/vhost.conf. L'origine doit correspondre a APP_URL_KIOSK.

---

11. Versionnement

Demarrage sans segment de version (/api/...), ce qui correspond a une v1 implicite. En cas de changement de contrat non retrocompatible, l'option retenue est un prefixe explicite /api/v2/... introduit a ce moment-la, en gardant /api/... pour la v1 tant que des clients en dependent.

---

12. Ou est defini quoi (recap code)

Element	Fichier
Declaration des routes	src/public/admin/index.php
Resolution / 404 / 405	src/app/Core/Router.php
Enveloppe data / error / contenu JSON	src/app/Core/Response.php
Lecture de la requete (chemin, query, corps, IP)	src/app/Core/Request.php
Controleurs	src/app/Controllers/
Acces base (requetes preparees, transaction)	src/app/Core/Database.php
Noms de champs (source de verite)	docs/merise/dictionary.md
Operations metier et permissions	docs/merise/mct.md, mlt.md, db/seeds/0001_rbac_and_reference.sql