refactor(find): use polymorphic outputs for not found cases

Replace not-found exceptions in Arcadia find/show flows with typed outputs (Found*/NotFoundOutput) and map not-found results in presenters/responses while preserving HTTP 404 problem details.

Adjust architecture and unit tests to cover concrete output classes, and remove obsolete Arcadia not-found exception classes and their tests.

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

2026-10-05 15:50:01 +02:00

4.2 KiB

Raw Permalink Blame History

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
2. Matrice de Mapping Exceptions -> Codes HTTP
3. Format de Réponse (Problem Details)
4. Distinctions 400 Bad Request vs 422 Unprocessable Content
5. Ressources absentes dans les use cases de lecture

1. Convention REST & RFC 7807

L'API exprime toutes les réponses d'erreur au format standardisé 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: ressource déjà existante ou verrouillée).
`NotFoundException`	`Application`	404	`Resource Not Found`	Ressource introuvable considérée comme exceptionnelle.
`NotFoundOutput` (polymorphisme)	`Application` / `Presentation`	404	`Resource Not Found`	Ressource absente attendue sur un use case de lecture (pas d'exception levée).
`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 :

{
  "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).

5. Ressources absentes dans les use cases de lecture

Pour les use cases de consultation (Find* / Show*), Arcadia API privilégie désormais un retour polymorphique :

Output quand la ressource existe
NotFoundOutput quand la ressource n'existe pas

Ce cas n'est pas traité comme une erreur exceptionnelle dans le cœur applicatif ; la couche Presentation convertit NotFoundOutput en réponse HTTP 404 au format Problem Details.

4.2 KiB Raw Permalink Blame History