From b3f02510b5df7f47c9cb10370709aca5ad0cf76c Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?J=C3=A9r=C3=A9my=20Munsch?= <github@jeremydev.ovh>
Date: Thu, 13 Aug 2026 12:34:12 +0200
Subject: [PATCH] docs: update README and add Exceptions documentation

Added a section for Exception Management in README and created a new document detailing exception handling and HTTP status codes.
---
 README.md                   |  5 ++++
 documentation/Exceptions.md | 60 +++++++++++++++++++++++++++++++++++++
 2 files changed, 65 insertions(+)
 create mode 100644 documentation/Exceptions.md

diff --git a/README.md b/README.md
index d0b5ce8..7b19943 100644
--- a/README.md
+++ b/README.md
@@ -6,6 +6,7 @@ Arcadia API est une application construite en respectant les principes de la **C
 
 - [Architecture](#architecture)
 - [Principes d'implémentation](#principes-dimplémentation)
+- [Gestion des Exceptions](#gestion-des-exceptions)
 - [Tests & Assurance Qualité](#tests--assurance-qualité)
 
 ---
@@ -28,6 +29,10 @@ L'application est découpée en couches strictes respectant la règle de dépend
 - **Pattern Presenter** : Les Use Cases (dans `Application`) retournent un `Output` agnostique. La couche `Presentation` utilise ensuite des `Presenters` spécifiques (ex: API) pour transformer cet `Output` en une vue exploitable par l'interface finale (JSON).
 - **Validation** : La validation stricte du format (ex: HTTP) est gérée dans la couche `Presentation` (via les `FormRequest`). La validation des règles métier est garantie au coeur du `Domain` par les `Value Objects`, qui lèvent des exceptions de type `InvalidArgumentException` traduites en HTTP 422 par le gestionnaire d'erreurs global.
 
+## Gestion des Exceptions
+
+Consulter le document [documentation/Exceptions.md](documentation/Exceptions.md) pour la matrice complète de correspondance entre le type d'exception (`DomainException`, `ValidationException`, `NotFoundException`, `ConflictException`) et les codes HTTP RFC 7807 (`400`, `404`, `409`, `422`, `429`, `500`).
+
 ## Tests & Assurance Qualité
 
 Consulter le document [TEST.md](TEST.md) pour la stratégie de test en pyramide (Unit, Integration, Feature, Arch) et les commandes d'exécution avec couverture de code.
diff --git a/documentation/Exceptions.md b/documentation/Exceptions.md
new file mode 100644
index 0000000..80768e4
--- /dev/null
+++ b/documentation/Exceptions.md
@@ -0,0 +1,60 @@
+# Gestion des Exceptions & Codes HTTP — Arcadia API
+
+Ce document récapitule la stratégie de gestion des exceptions et la correspondance avec les codes de statut HTTP dans **Arcadia API**.
+
+## Sommaire
+
+- [1. Convention REST & RFC 7807](#1-convention-rest--rfc-7807)
+- [2. Matrice de Mapping Exceptions ➔ Codes HTTP](#2-matrice-de-mapping-exceptions--codes-http)
+- [3. Format de Réponse (Problem Details)](#3-format-de-réponse-problem-details)
+- [4. Distinctions 400 Bad Request vs 422 Unprocessable Content](#4-distinctions-400-bad-request-vs-422-unprocessable-content)
+
+---
+
+## 1. Convention REST & RFC 7807
+
+L'API exprime toutes les réponses d'erreur au format **RFC 7807 / RFC 9457 Problem Details** avec l'en-tête HTTP :
+`Content-Type: application/problem+json`
+
+---
+
+## 2. Matrice de Mapping Exceptions ➔ Codes HTTP
+
+| Type d'Exception | Couche Origine | Code HTTP | Titre RFC 7807 | Usage & Description |
+|---|---|---|---|---|
+| `ValidationException` | `Presentation` | **422** | `Unprocessable Entity` | Échec de validation HTTP (`FormRequest`), champs invalides ou manquants. |
+| `DomainException` | `Domain` | **422** | `Unprocessable Entity` | Violation d'un invariant ou d'une règle métier au cœur du Domaine (ex: `ValueObject`). |
+| `ConflictException` | `Domain` / `Application` | **409** | `Conflict` | Conflit d'état métier (ex: compte déjà supprimé, ressource déjà existante/verrouillée). |
+| `NotFoundException` | `Domain` / `Application` | **404** | `Resource Not Found` | Ressource introuvable dans le répertoire / BDD. |
+| `HttpExceptionInterface` (403) | `Presentation` | **403** | `Forbidden` | Accès refusé par les politiques d'autorisation HTTP. |
+| `ThrottleRequestsException` | `Infra` | **429** | `Too Many Requests` | Dépassement du quota de requêtes API (Rate Limiting). |
+| `Throwable` / `Exception` | Transverse | **500** | `Internal Server Error` | Erreur système non captée (détails masqués hors mode debug). |
+
+---
+
+## 3. Format de Réponse (Problem Details)
+
+Chaque réponse d'erreur retourne une structure JSON standardisée :
+
+```json
+{
+  "type": "http://localhost/errors/422",
+  "title": "Unprocessable Entity",
+  "status": 422,
+  "detail": "Invalid employee number format",
+  "instance": "/api/v1/employees",
+  "invalidParams": [
+    {
+      "name": "domain_invariant",
+      "reason": "Invalid employee number format"
+    }
+  ]
+}
+```
+
+---
+
+## 4. Distinctions 400 Bad Request vs 422 Unprocessable Content
+
+- **HTTP 400 (Bad Request)** : Réservé aux erreurs de **syntaxe ou de structure HTTP** (ex: JSON illisible, guillemets mal fermés, en-têtes HMAC malformés). Le serveur ne peut pas parser le message.
+- **HTTP 422 (Unprocessable Content)** : Convention **REST & Laravel**. La requête est du JSON syntaxiquement valide, mais son contenu viole les règles de validation HTTP (`FormRequest`) ou les invariants du domaine métier (`DomainException`).