ldc-arcadia-api/documentation/Architecture/03-execution-et-transactions.md
Jérémy Munsch 0d2b0124ee docs(architecture): add global architecture documentation for Arcadia API
docs(architecture): add request lifecycle documentation for Arcadia API

docs(architecture): add execution, transactions, and domain events documentation for Arcadia API

docs(architecture): add guide for creating a new use case in Arcadia API

docs(exceptions): summarize exception handling and HTTP status codes in Arcadia API

docs(tests): outline testing strategy and conventions for Arcadia API

style(openapi): correct description formatting in OpenAPI documentation

chore: remove outdated exceptions documentation

test: remove obsolete tests documentation
2026-08-21 10:41:07 +02:00

4.1 KiB

Exécution, Transactions & Événements de Domaine - Arcadia API

Ce document détaille le fonctionnement de l'exécuteur de cas d'usage (LaravelExecutor), de la gestion des transactions SQL et du cycle de vie des Événements de Domaine (Domain Events).


⚡ 1. Le Fluent Builder (UsecaseBuilder)

Pour garantir un typage strict et une exécution homogène à travers toute l'application, les Use Cases sont exécutés via un builder fluent :

$result = UsecaseBuilder::using($this->executor)
    ->do($this->usecase)            // Le Use Case à exécuter
    ->from($input)                  // Le DTO Input entrant
    ->with(new CustomPresenter())   // (Optionnel) Le Presenter
    ->run();                        // Exécute et retourne le View (ou l'Output)

Le builder garantit à la compilation (PHPStan Niveau 10) que les types d'Input, d'Output et de View concordent parfaitement.


🛡️ 2. Gestion des Transactions (Transactional)

Pour distinguer clairement les opérations de lecture (Query) des opérations d'écriture (Command) :

  • Cas d'Usage en Lecture (Query) : N'implémente pas Transactional. Exécuté directement sans overhead de transaction de base de données.
  • Cas d'Usage en Écriture (Command) : Implémente le marqueur Shared\DDD\Usecase\Transactional.
namespace Application\Security\Usecases\CreateClient;

use Shared\DDD\Usecase\Transactional;
use Shared\DDD\Usecase\Usecase;

/** @implements Usecase<Input, Output> */
final readonly class CreateClient implements Transactional, Usecase
{
    public function execute(BaseInput $input): Output
    {
        // Cette méthode sera automatiquement enveloppée dans
        // DB::transaction(...) par le LaravelExecutor
    }
}

📢 3. Événements de Domaine & Sécurité Post-Commit

Dans les architectures événementielles, un problème classique survient lorsqu'un événement est émis pendant une transaction SQL qui échoue ensuite (rollback) : les écouteurs ont déjà envoyé des notifications ou loggué des actions erronées.

Arcadia API résout ce problème via le pattern TransactionalDomainEventDispatcher :

sequenceDiagram
    autonumber
    participant UseCase as Cas d'Usage
    participant Dispatcher as TransactionalDomainEventDispatcher (Buffer)
    participant DB as Base de Données
    participant Executor as LaravelExecutor
    participant LaravelBus as Laravel Event Bus

    Executor->>DB: DB::beginTransaction()
    Executor->>UseCase: execute(input)
    UseCase->>Dispatcher: dispatch(BrandCreated)
    Note over Dispatcher: Événement stocké dans le buffer mémoire (non émis)
    UseCase-->>Executor: Output
    
    alt Succès de la Transaction
        Executor->>DB: DB::commit()
        Executor->>Dispatcher: release()
        Dispatcher->>LaravelBus: dispatch(BrandCreated)
        Note over LaravelBus: Les Listeners sont déclenchés après le commit garanti
    else Exception / Rollback
        Executor->>DB: DB::rollBack()
        Executor->>Dispatcher: clear()
        Note over Dispatcher: Le buffer est vidé, aucun événement fantôme n'est émis
    end

💻 4. Comment Émettre un Événement dans le Domaine ?

Dans un service ou un Use Case de domaine, injectez simplement Shared\DDD\Event\DomainEventDispatcher :

namespace Domain\Services;

use Domain\Events\BrandCreated;
use Shared\DDD\Event\DomainEventDispatcher;

final readonly class BrandResolver
{
    public function __construct(
        private BrandRepository $brands,
        private DomainEventDispatcher $dispatcher,
    ) {}

    public function resolve(string $brandName): Brand
    {
        // Logique de résolution / création...
        $brand = Brand::create(...);
        $this->brands->persist($brand);

        // Déclencher l'événement métier
        $this->dispatcher->dispatch(new BrandCreated($brand));

        return $brand;
    }
}

Enregistrer un Écouteur (Listener)

Dans Infra\Providers\EventServiceProvider.php :

use Domain\Events\BrandCreated;
use Infra\Listeners\LogBrandCreated;

Event::listen(
    BrandCreated::class,
    LogBrandCreated::class,
);