> ⚠️ **MODE DEV STRICT (pas PROD)**  
> - **Aucune transition**, **aucun fallback**, **aucune rétro-compat**.  
> - Soit on règle un point proprement soit on n'y touche pas. pas de zone de : "transition ou entre deux".  
> - Toute contribution qui introduit une zone grise, un compromis ou un retour au legacy est **refusée**.


IMPORTANT : 

Répond toujours en francais de préférence 

Si une ou plusieurs de mes instructions impliquent des modifications à faire Dans l'architecture cela est tout à fait possible : il n'est pas écrit ON RESTE EN V4 ACTUELLE ET ON NE BOUGE RIEN il est préscrit : TOUT CHANGEMENT APPORTE DOIT S'INSCRIRE DANS LA COHERENCE ET L'HARMONIE DE L'ENSEMBLE et doit respecter les principes ou en érigé de nouveau harmonieusement avec les précédents

Doctrine (gravée) : pas de transition progressive, pas de compromis fonctionnels. On prolonge V4 en respectant ses principes (GET en lecture, un bus de commandes, admin whitelisté, pas de métier en UI) mais on pousse l’architecture pour maximiser propreté, sécurité et évolutivité.

Si il y a des choix à faire concernant la mise en place de ces modifications 
Si des changement remettent en question de façon importante l'architecture 
Tu interromps immédiatement et systématiquement la tâche en cours Pour me l'indiquer clairement. m'exposer ce que tu propose pour faire muter l'ensemble
Ne laisses jamais planer aucune ambiguïté grave, si certaines de mes consignes te semblent floues étrange etc,Idem Tu m'arrêtes et tu me demandes des précisions.

# Documentation V4 — Guide canon + Kit anti‑dérive

**Mots-clés normatifs** : “DOIT”, “NE DOIT PAS”, “DEVRAIT”, “NE DEVRAIT PAS”, “PEUT” sont à lire selon RFC 2119/8174.  
Dans ce projet, **DEVRAIT** est proscrit au profit de **DOIT/NE DOIT PAS**. **PEUT** est réservé aux exemples, jamais aux règles.

**Commencer ici (obligatoire)** :
1) Lire `commandbus-arbiter-reactor.md`.  
2) Lire `data-model-invariants.md`.  
3) Toute mutation boards DOIT passer par **POST /api/commands** (Bus).  
4) Si votre tâche semble exiger un endpoint REST mutant → **abandonner** et ouvrir une issue d’architecture.  
5) PRs sans ces prérequis → **refusées**.

Ce document est la référence unique et normative pour le backend V4. Il formalise la « ligne rouge » (contrat HTTP/JSON, sécurité, périmètre), l’architecture, et les garde‑fous CI pour éviter toute dérive lors des évolutions futures.

## Navigation
- [HTTP/JSON](canonical-http-json.md) • [Routing](http-routing.md) • [Sécurité](security.md) • [Packs](packs.md) • [Fichiers](files-attachments.md)
- [Modèle & invariants](data-model-invariants.md) • [Bus/Arbitre/Réacteur](commandbus-arbiter-reactor.md) • [UI/UX](ui-ux-rules.md)
- [Gouvernance & PR](governance-pr.md) • [Migration V2/V3 → V4](migration-v2-v3-to-v4.md) • [Annexes](appendix-examples.md) • [Tests & E2E](testing.md)

## Objectifs
- Simplicité et uniformité des réponses **HTTP/JSON** (succès/erreur).
- **Zéro double logique** (pas de chemin parallèle legacy).
- **Séparation claire** du noyau et des packs MCC (tags/ui/datasets/rules).
- **Sécurité par défaut** (CSRF, rate‑limit auth, 404/403 canoniques).
- **Gardes CI** actives (greps anti‑legacy, liste d’autorisation des routes mutantes).

## Ligne rouge (invariants)
- Toujours répondre en JSON via `Response::ok(...)` ou `Response::error(...)` (pas d’enveloppe bricolée à la main).
- `Response::json(...)` est un encodeur brut (pas de normalisation de l’enveloppe). Ne pas l’utiliser pour les réponses publiques.
- Binaire: utiliser `Response::binary(...)` avec `Content-Type` spécifique, `Content-Disposition`, `Content-Length`, `ETag` si disponible.
- Routes mutantes strictement **acceptées via liste d’autorisation** (voir `http-routing.md`).
- CSRF obligatoire pour toute requête mutante (sauf login/register) et rate‑limit sur auth.
- Aucun contrôleur ne doit créer un JSON d’erreur de forme legacy (voir `ci-guards.md`).
- **Identifiants stricts (IDs only)**: les commandes NonBoard acceptent uniquement des identifiants numériques stables pour référencer les entités (ex. catégories de notifications: `categoryId` obligatoire). Les alias UI (slugs, labels) NE DOIVENT PAS être acceptés côté back dans les payloads.

## Architecture (vue d’ensemble)
- `Infrastructure/Http` : `HttpKernel`, `Router`, `Request`, `Response` (helpers `ok/error/binary`).
- `Interfaces/Http` : contrôleurs (surface HTTP), middlewares (`AuthMiddleware`, `CsrfMiddleware`, `RateLimitMiddleware`, `ErrorHandlingMiddleware`).
- `Application` : `CommandBus`, handlers (création/mouvements/renommages, bus non‑board).
- `Domain` : règles métier (Boards, Rules, UserFiles…).
- `Infrastructure/Packs` : `PackLoader`, `MccValidator`, `DatasetStore`, registres (tags/ui/règles).
- `public/index.php` : composition runtime (wiring des contrôleurs, routes, middlewares).

## Contribution (Do/Don’t)
- DO: utiliser `Response::ok/error`, codes d’erreur symboliques stables, messages lisibles.
- DO: ajouter les tests lorsque vous touchez au contrat HTTP/JSON ou aux middlewares.
- DON’T: retourner du HTML, du texte brut, ou un JSON sans `ok`.
- DON’T: étendre les routes mutantes sans mise à jour de la liste d’autorisation et des tests.

## Identifiants & Références (ID only)
- Les surfaces HTTP (controllers/handlers) doivent opérer sur des IDs numériques stables. Les slugs/labels sont réservés à l’UI et ne sont pas des entrées valides pour les mutations.
- Exemple Notifications: `User.SubscribeCategory`, `User.UnsubscribeCategory`, `User.SetCategoryFrequencyOverride`, `User.SubscribeAndSetPref` exigent `categoryId > 0`. `categorySlug` est refusé (`422 INVALID_PAYLOAD`).
- Bénéfices: pas d’ambiguïté ni de collision, pas de dérive entre environnements (prod/dev), tests plus déterministes.

## Révisions et gouvernance
- Toute modification du contrat public (structure JSON, codes d’erreur, routes) requiert validation et ajustement simultané: docs + tests + guards CI.
- Les packs MCC ne peuvent pas introduire d’API HTTP: uniquement des contributions déclaratives consommées côté UI.
