From 08a95eb4e983a65b932ade9a371053d6be8fccad Mon Sep 17 00:00:00 2001 From: Imugiii Date: Mon, 15 Jun 2026 18:15:32 +0000 Subject: [PATCH] docs(api): conventions de nommage et listing des endpoints Documente les conventions de l'API Wakdo (chemins minuscule + snake_case, ressources au pluriel, enveloppe data/error, codes d'erreur SCREAMING_SNAKE, champs snake_case alignes sur le dictionnaire) et le listing des endpoints (en service P2 + projection P3-P5). Acte la divergence connue avec le repli JSON kiosk legacy et le point de mapping data.js. --- docs/api/conventions.md | 328 ++++++++++++++++++++++++++++++++++++++++ 1 file changed, 328 insertions(+) create mode 100644 docs/api/conventions.md diff --git a/docs/api/conventions.md b/docs/api/conventions.md new file mode 100644 index 0000000..3fbe29c --- /dev/null +++ b/docs/api/conventions.md @@ -0,0 +1,328 @@ +# 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 : + +```json +{ "data": { "id": 3, "name": "Big Mac", "price_cents": 590 } } +``` + +Succes - collection (`total` optionnel pour la pagination future) : + +```json +{ "data": [ { "id": 1 }, { "id": 2 } ], "total": 2 } +``` + +Erreur : + +```json +{ "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` |