@archi-code/ddd 0.0.0-stage → 3.0.0-alpha.2

package/ddd-skills/ddd-servicios-capa-aplicacion/references/capa-aplicacion-ts.md

@@ -0,0 +1,264 @@
+# Capa de aplicación en TypeScript
+
+## Plantilla de caso de uso
+
+Un caso de uso extiende `UseCase<Input, Command, Output>` de `@archi-code/ddd/application`. `execute(input)` llama a `toCommand(input)` y después a `handle(command)`; no hay que escribir `execute`.
+
+```ts
+import type { AggregateFinder, AggregateSaver } from '@archi-code/ddd/domain';
+import { AggregateNotFoundException, NotAllowedException, UseCase, ValueObjectBuilder } from '@archi-code/ddd/application';
+import type { Clock, EventBus } from '@archi-code/ddd/application';
+
+export interface SalesPermissions {
+  canCancelOrders(requester: CustomerId): Promise<boolean>;
+}
+
+export interface CancelOrderInput {
+  orderId: string;
+  requesterId: string;
+  reason: string | null;
+}
+
+interface CancelOrderCommand {
+  orderId: OrderId;
+  requester: CustomerId;
+  reason: CancellationReason;
+}
+
+export class CancelOrder extends UseCase<CancelOrderInput, CancelOrderCommand, void> {
+  private readonly cancellation = new OrderCancellation();
+
+  constructor(
+    private readonly orders: AggregateFinder<Order> & AggregateSaver<Order>,
+    private readonly events: EventBus<OrderEvent>,
+    private readonly permissions: SalesPermissions,
+    private readonly clock: Clock,
+  ) {
+    super();
+  }
+
+  protected toCommand(input: CancelOrderInput): CancelOrderCommand {
+    return ValueObjectBuilder.build({
+      orderId: () => new OrderId(input.orderId),
+      requester: () => new CustomerId(input.requesterId),
+      reason: () => new CancellationReason(input.reason as string),
+    });
+  }
+
+  protected async handle(command: CancelOrderCommand): Promise<void> {
+    if (!(await this.permissions.canCancelOrders(command.requester))) {
+      throw new NotAllowedException(`Customer ${command.requester.value} may not cancel orders`);
+    }
+    const order = await this.orders.findById(command.orderId);
+    if (order === null) {
+      throw new AggregateNotFoundException('Order', command.orderId.value);
+    }
+    this.cancellation.cancel(order, command.requester, command.reason, this.clock);
+    await this.orders.save(order);
+    await this.events.publish(order.pullDomainEvents());
+  }
+}
+```
+
+Autorizar, cargar, invocar el dominio, guardar y publicar, y ninguna regla de negocio: que solo el cliente del pedido pueda cancelarlo lo comprueba el servicio de dominio `OrderCancellation`, y que no esté ya cancelado, `order.cancel`. Coincide con la forma de IDDD: parámetros, repositorio, comando sobre el agregado [IDDD cap. 4] y con la anatomía de *DDD in PHP* [PHP: Application].
+
+* El caso de uso pide solo los roles de repositorio que usa (`AggregateFinder<Order> & AggregateSaver<Order>`), los puertos `EventBus` y `Clock` del paquete, y los puertos de aplicación propios (`SalesPermissions`). Nunca una dependencia de transacciones (un runner de transacciones o una unidad de trabajo): no existe puerto de transacciones `[Fuera de los libros: convención de @archi-code/ddd]`.
+* `UseCase` no trae ayudas (`findOrFail`, `saveAndPublish`): todos los pasos se escriben en `handle` `[Fuera de los libros: convención de @archi-code/ddd]`.
+* Se guarda antes de publicar, y se publica lo que devuelve `pullDomainEvents()`.
+* La aplicación nunca abre, une ni cierra transacciones. IDDD pone el control de la transacción en el servicio de aplicación [IDDD cap. 14]; con el paquete esa responsabilidad pasa al adaptador del repositorio, que hace atómico cada `save` y `remove` (una escritura de documento en Mongo; si el agregado ocupa varias tablas SQL, abre y confirma o deshace una transacción de la base de datos dentro de `save`/`remove`, con su propia conexión o sesión), comprueba la versión y envuelve los errores del driver en `InternalErrorException` con `{ cause }` `[Fuera de los libros: convención de @archi-code/ddd]`. Ver `ddd-skills/ddd-repositorios-persistencia/references/transacciones-ts.md`.
+
+## Entrada
+
+* Primitivos o DTO o comando [PHP: Application, citando a Vernon]. Con el paquete, dos tipos por caso de uso `[Fuera de los libros: convención de @archi-code/ddd]`: el `Input`, plano y de primitivos (se puede serializar y encolar si un día hace falta [PHP: Application]), y el `Command`, de value objects, que construye `toCommand`.
+* La conversión a value objects ocurre en `toCommand` con `ValueObjectBuilder.build`: si algún campo no es válido lanza una sola `ValidationException` con el `field` y el `code` de cada problema (`ValueObjectBuilder.buildList` nombra los elementos de una lista por posición, `lines.1.quantity`), y `handle` no llega a ejecutarse.
+* El adaptador de entrada solo comprueba la forma de la petición (que un campo sea texto); las reglas de cada valor son de los value objects.
+* Nunca recibas el agregado desde el controlador.
+
+## Salida
+
+IDDD presenta varias opciones [IDDD cap. 14]:
+
+| Opción | Cuándo |
+|---|---|
+| Devolver un identificador o nada | Comandos (lo normal) |
+| DTO construido desde el agregado | El cliente necesita el resultado inmediato |
+| Transformador de datos que elige el cliente | Varios clientes con formatos distintos |
+| Método sin retorno y puerto de salida | Estilo hexagonal estricto |
+
+Con el paquete, la salida es el tercer parámetro de tipo: `UseCase<PlaceOrderInput, PlaceOrderCommand, string>` devuelve el id (`order.id.value`), `void` nada. Nunca el agregado.
+
+Para pantallas, mejor una consulta de lectura aparte que devuelve un DTO sin pasar por el agregado: una interfaz de aplicación implementada en infraestructura directamente sobre la base de datos (ver `ddd-skills/ddd-repositorios-persistencia/GUIA.md` y `ddd-skills/ddd-event-sourcing-cqrs/GUIA.md`).
+
+## Command bus
+
+*DDD in PHP* presenta el bus de comandos (Tactician) para enlazar cada comando con su manejador; los objetos request se parecen ya a comandos [PHP: Application]. El paquete no trae bus de comandos `[Fuera de los libros: convención de @archi-code/ddd]`: el composition root construye cada caso de uso y se lo pasa al punto de entrada, que llama a `execute(input)`. Lo común a todos los casos de uso ya está en `UseCase.execute` (dejar pasar las excepciones del paquete y envolver cualquier otro error en `UnexpectedErrorException` con `cause`), y la atomicidad de cada escritura es del repositorio.
+
+## Eventos en la capa de aplicación
+
+* La aplicación puede registrar suscriptores para guardar y reenviar eventos, dejando el dominio libre de mensajería [IDDD cap. 4]. Con el paquete, los suscriptores son listeners (`EventListener` con `@ListensTo`) que el composition root conecta con `bus.subscribe(listener)`; cada uno ejecuta un solo caso de uso.
+* Con outbox, los eventos se guardan en la transacción y la publicación ocurre fuera (`ddd-skills/ddd-eventos-dominio/GUIA.md`). Con el paquete, el caso de uso siempre llama a `events.publish(order.pullDomainEvents())` después de `save`; si `publish` falla después de `save`, el evento puede perderse. Cuando un evento no puede perderse, el repositorio escribe el agregado y sus eventos pendientes en la misma escritura atómica (un outbox dentro del mismo documento o en la misma transacción de base de datos de `save`) y un relay los entrega después por un `EventChannel`; los casos de uso no cambian `[Fuera de los libros: convención de @archi-code/ddd]`.
+
+## Conflictos de concurrencia
+
+Cada repositorio comprueba la versión del agregado y lanza `ConcurrencyException` (409) si otro lo cambió después de cargarlo. Si el comando es seguro de repetir sobre el nuevo estado, el caso de uso puede reintentarlo [IDDD cap. 10; IDDD apéndice A]: un bucle en `handle` en el que cada intento vuelve a cargar el agregado y vuelve a guardarlo; pocos intentos y después se relanza. Un caso de uso que ejecuta un listener no reintenta por sí mismo: reintenta la reentrega del canal.
+
+```ts
+import { DomainException } from '@archi-code/ddd/domain';
+import { ConcurrencyException } from '@archi-code/ddd/application';
+
+export interface ProductPricing {
+  priceForSale(sku: Sku): Promise<Money | null>;
+}
+
+export class ProductNotSellable extends DomainException {
+  constructor(sku: string) {
+    super(`Product ${sku} is not for sale`, ['ORD003']);
+  }
+}
+
+const ATTEMPTS = 3;
+
+export class AddOrderLine extends UseCase<AddOrderLineInput, AddOrderLineCommand, void> {
+  constructor(
+    private readonly orders: AggregateFinder<Order> & AggregateSaver<Order>,
+    private readonly pricing: ProductPricing,
+    private readonly events: EventBus<OrderEvent>,
+    private readonly clock: Clock,
+  ) {
+    super();
+  }
+
+  protected toCommand(input: AddOrderLineInput): AddOrderLineCommand {
+    return ValueObjectBuilder.build({
+      orderId: () => new OrderId(input.orderId),
+      sku: () => new Sku(input.sku),
+      quantity: () => new Quantity(input.quantity),
+    });
+  }
+
+  protected async handle({ orderId, sku, quantity }: AddOrderLineCommand): Promise<void> {
+    const unitPrice = await this.pricing.priceForSale(sku);
+    if (unitPrice === null) {
+      throw new ProductNotSellable(sku.value);
+    }
+    const line = new OrderLine({ sku, quantity, unitPrice });
+    for (let attempt = 1; ; attempt += 1) {
+      try {
+        const order = await this.orders.findById(orderId);
+        if (order === null) {
+          throw new AggregateNotFoundException('Order', orderId.value);
+        }
+        order.addLine(line, this.clock);
+        await this.orders.save(order);
+        await this.events.publish(order.pullDomainEvents());
+        return;
+      } catch (error) {
+        if (!(error instanceof ConcurrencyException) || attempt === ATTEMPTS) {
+          throw error;
+        }
+      }
+    }
+  }
+}
+```
+
+`ProductPricing` es un puerto de dominio (la interfaz en `domain/` con value objects, implementada en infraestructura por la capa anticorrupción) y `ProductNotSellable` una regla de dominio. `AddOrderLineInput` (`orderId`, `sku`, `quantity` como primitivos) y `AddOrderLineCommand` (`OrderId`, `Sku`, `Quantity`) siguen el patrón de `CancelOrder`. Nunca se reintenta con el agregado ya cargado, y un caso de uso nunca se llama a sí mismo ni a otro para reintentar.
+
+## Errores
+
+* El dominio lanza `DomainException` con nombre y código propio (`class OrderCannotBeCancelled extends DomainException`, `super(message, ['ORD002'])`); los value objects y `ValueObjectBuilder.build` lanzan `ValidationException`.
+* La aplicación añade las suyas: `AggregateNotFoundException('Order', id)` cuando `findById` devuelve `null`, `NotAllowedException(message)` cuando el solicitante no puede ejecutar la acción, `ApplicationException` para otros errores de aplicación. Al traducir otro error, siempre con `{ cause: error }`.
+* Los errores se dejan propagar: no se capturan en `handle` para relanzarlos; `execute` deja pasar las excepciones del paquete y envuelve el resto en `UnexpectedErrorException` (de `@archi-code/ddd/application`).
+* El punto de entrada los clasifica con `ExceptionClassifier.classify(error)` de `@archi-code/ddd/infrastructure`, que no sabe de ningún protocolo: `NotFound` (`AggregateNotFoundException`), `NotAllowed` (`NotAllowedException`), `Conflict` (`ConcurrencyException`), `Malformed` (`TypePrimitiveException`, `RequiredValueException`), `Invalid` (`ValidationException` y cualquier otra `DomainException`), `Rejected` (otros errores de aplicación) e `Internal` (`UnexpectedErrorException`, `InvalidEventDefinitionException` y lo demás). Cada protocolo traduce el `ExceptionKind` a sus códigos (en HTTP: 404, 403, 409, 400, 422, 400 y 500), usa `error.code` para los códigos propios (`ORD001` → 409), oculta el mensaje de `Internal`, devuelve los `errors` de una `ValidationException` y registra él mismo los fallos internos `[Fuera de los libros: convención de @archi-code/ddd]`. Un controlador HTTP usa el `toHttpError` del proyecto (en `interfaces/http/`; completo en `ddd-skills/ddd-arquitectura/references/estructura-hexagonal-ts.md`):
+
+```ts
+import type { Logger } from '@archi-code/ddd/application';
+import { toHttpError } from './httpError';
+
+interface HttpRequest {
+  params: { orderId: string };
+  auth: { customerId: string };
+  body: { reason?: unknown };
+}
+
+interface HttpResponse {
+  status: number;
+  body?: unknown;
+}
+
+export class CancelOrderController {
+  constructor(
+    private readonly cancelOrder: CancelOrder,
+    private readonly logger: Logger,
+  ) {}
+
+  async cancel(request: HttpRequest): Promise<HttpResponse> {
+    try {
+      await this.cancelOrder.execute({
+        orderId: request.params.orderId,
+        requesterId: request.auth.customerId,
+        reason: typeof request.body.reason === 'string' ? request.body.reason : null,
+      });
+      return { status: 204 };
+    } catch (error) {
+      return toHttpError(error, this.logger);
+    }
+  }
+}
+```
+
+La identidad del solicitante sale del token (`request.auth`), nunca del cuerpo.
+
+## Tests
+
+Con adaptadores en memoria: `InMemoryOrderRepository`, que el proyecto escribe en `test/support/` (uno por agregado; cada `save` y `remove` es atómico y comprueba la versión; cómo se escribe, en `ddd-skills/ddd-repositorios-persistencia/references/tests-repositorios.md`), y del paquete `DomainEventBus` sobre `InMemoryEventChannel` (`channel.sent` lista lo publicado). Los puertos propios se sustituyen por objetos simples.
+
+```ts
+import { describe, expect, it } from 'vitest';
+import { NotAllowedException } from '@archi-code/ddd/application';
+import {
+  DomainEventBus,
+  EventRegistry,
+  FixedClock,
+  InMemoryEventChannel,
+} from '@archi-code/ddd/infrastructure';
+import { InMemoryOrderRepository } from '../support/in-memory-order-repository';
+
+const clock = new FixedClock('2026-03-01T09:30:00Z');
+
+function salesWith(permissions: SalesPermissions) {
+  const orders = new InMemoryOrderRepository();
+  const channel = new InMemoryEventChannel();
+  const events = new DomainEventBus<OrderEvent>(channel, new EventRegistry<OrderEvent>());
+  const cancelOrder = new CancelOrder(orders, events, permissions, clock);
+  return { orders, channel, cancelOrder };
+}
+
+const everyoneMayCancel: SalesPermissions = { canCancelOrders: async () => true };
+const nobodyMayCancel: SalesPermissions = { canCancelOrders: async () => false };
+
+describe('Cancelling an order', () => {
+  it('a customer cancels her own pending order', async () => {
+    const { orders, channel, cancelOrder } = salesWith(everyoneMayCancel);
+    await orders.save(aPendingOrderOf(laura));
+
+    await cancelOrder.execute({ orderId, requesterId: laura, reason: 'Wrong size' });
+
+    expect(channel.sent).toMatchObject([
+      { eventName: 'OrderCancelled', orderId, reason: 'Wrong size' },
+    ]);
+  });
+
+  it('a customer whose account may not cancel orders is refused', async () => {
+    const { orders, channel, cancelOrder } = salesWith(nobodyMayCancel);
+    await orders.save(aPendingOrderOf(laura));
+
+    await expect(
+      cancelOrder.execute({ orderId, requesterId: laura, reason: 'Wrong size' }),
+    ).rejects.toThrow(NotAllowedException);
+    expect(channel.sent).toEqual([]);
+  });
+});
+```
+
+`aPendingOrderOf`, `laura` y `orderId` son fábricas y datos de `test/support/` del proyecto; el modelo (`Order`, `CancellationReason`, `OrderCancelled`…) es el de `ddd-skills/ddd-agregados/references/implementacion-ts.md` y `OrderCancellation` el de `ddd-skills/ddd-servicios-capa-aplicacion/references/ejemplo-ecommerce.md`. Estos tests comprueban orquestación. Que un pedido ya cancelado no se pueda cancelar otra vez se prueba en `Order`, y que otro cliente no pueda cancelarlo, en `OrderCancellation`; no aquí.

package/ddd-skills/ddd-servicios-capa-aplicacion/references/ejemplo-ecommerce.md

@@ -0,0 +1,321 @@
+# Ejemplo: dónde va cada lógica en Ventas
+
+| Lógica | Dónde | Por qué |
+|---|---|---|
+| El total es la suma de las líneas | `OrderLines` (composite `Composite({ items: [OrderLine] })`, método `total()`) | Cálculo sobre valores |
+| Un pedido confirmado no admite líneas nuevas | `Order` (agregado) | Regla sobre su estado |
+| Gastos de envío según zona y promociones | `ShippingCostCalculator` (servicio de dominio) | Necesita el pedido, la zona, las tarifas y la promoción; forzado en cualquiera de ellos |
+| Envío gratis a partir de un importe | `OrderAbove` (`Specification<Order>`) | Regla con nombre que decide si un pedido cumple un criterio |
+| Solo el cliente que hizo el pedido puede cancelarlo | `OrderCancellation` (servicio de dominio), con concepto `Customer`, sobre `Order.cancel` | Regla de negocio [IDDD cap. 2] |
+| Quien pide cancelar tiene permiso para cancelar pedidos (rol, sesión activa) | `SalesPermissions` (puerto de aplicación) consultado por `CancelOrder`, que lanza `NotAllowedException` | Autorización del caso de uso [IDDD cap. 14] |
+| Cargar pedido, cancelar, guardar, publicar | `CancelOrder` (caso de uso) | Coordinación |
+| Cuando Almacén reserva, registrar en el pedido | listener `RegisterReservationOnStockReserved` y su caso de uso `RegisterReservation` `[Fuera de los libros: convención de @archi-code/ddd]` | Reacción a evento; invoca al agregado |
+| Precio vigente de una referencia | `ProductPricing` (puerto de dominio, ACL en infraestructura) | Viene de otro contexto |
+
+## El modelo
+
+`Order` y sus value objects (`OrderId`, `CustomerId`, `Sku`, `Quantity`, `Money`, `OrderLine`, `OrderLines`, `ShippingAddress`, `OrderStatus`, `ReservationId`, `CancellationReason`), sus eventos (`OrderPlaced`, `OrderLineAdded`, `OrderCancelled`…, unidos en `OrderEvent`) y sus errores son los de `ddd-skills/ddd-agregados/references/implementacion-ts.md`; no se redefinen aquí. Lo que usan los ejemplos de esta guía (`ddd-skills/ddd-servicios-capa-aplicacion/references/servicios-dominio-ts.md` y `ddd-skills/ddd-servicios-capa-aplicacion/references/capa-aplicacion-ts.md`):
+
+```ts
+static place(
+  id: OrderId,
+  customerId: CustomerId,
+  lines: OrderLines,
+  address: ShippingAddress,
+  clock: { now(): Date },
+): Order;
+addLine(line: OrderLine, clock: { now(): Date }): void;
+registerStockReservation(reservation: ReservationId, clock: { now(): Date }): void;
+cancel(reason: CancellationReason, clock: { now(): Date }): void;
+total(): Money;
+```
+
+Lo que añade Ventas en esta guía:
+
+```ts
+import { AggregateRoot, BooleanType, DomainException, Required, Specification, StringType } from '@archi-code/ddd/domain';
+import type { PrimitiveTypes } from '@archi-code/ddd/domain';
+
+export class OrderAbove extends Specification<Order> {
+  constructor(private readonly minimum: Money) {
+    super();
+  }
+
+  isSatisfiedBy(order: Order): boolean {
+    return order.total().covers(this.minimum);
+  }
+}
+
+export class CustomerBlocked extends DomainException {
+  constructor(customerId: string) {
+    super(`Customer ${customerId} is blocked and cannot place orders`, ['CUS001']);
+  }
+}
+
+export class CustomerName extends Required(StringType) {}
+export class Blocked extends Required(BooleanType) {}
+
+export class Customer extends AggregateRoot<CustomerId> {
+  private constructor(
+    id: CustomerId,
+    readonly name: CustomerName,
+    private _blocked: Blocked,
+  ) {
+    super(id);
+  }
+
+  static fromPrimitives(primitives: PrimitiveTypes<Customer>): Customer {
+    return new Customer(
+      new CustomerId(primitives.id),
+      new CustomerName(primitives.name),
+      new Blocked(primitives.blocked),
+    );
+  }
+
+  get blocked(): Blocked {
+    return this._blocked;
+  }
+
+  placeOrder(
+    id: OrderId,
+    lines: OrderLines,
+    address: ShippingAddress,
+    clock: { now(): Date },
+  ): Order {
+    if (this._blocked.value) {
+      throw new CustomerBlocked(this.id.value);
+    }
+    return Order.place(id, this.id, lines, address, clock);
+  }
+
+  toPrimitives(): PrimitiveTypes<Customer> {
+    return { id: this.id.value, name: this.name.value, blocked: this._blocked.value };
+  }
+}
+
+export class NotTheCustomerOfOrder extends DomainException {
+  constructor(orderId: string) {
+    super(`Only the customer who placed order ${orderId} can cancel it`, ['ORD004']);
+  }
+}
+
+export class OrderCancellation {
+  cancel(
+    order: Order,
+    requester: CustomerId,
+    reason: CancellationReason,
+    clock: { now(): Date },
+  ): void {
+    if (!order.customerId.equals(requester)) {
+      throw new NotTheCustomerOfOrder(order.id.value);
+    }
+    order.cancel(reason, clock);
+  }
+}
+```
+
+* `OrderAbove` usa `Money.covers` (misma moneda e importe mayor o igual).
+* `OrderCancellation` es un servicio de dominio: la regla relaciona a quien pide con el pedido (`CustomerId`), y el estado lo sigue protegiendo `Order.cancel`, que lanza `OrderCannotBeCancelled` si el pedido ya está cancelado.
+
+## `PlaceOrder`
+
+`ProductPricing` y `ProductNotSellable` son los de `ddd-skills/ddd-servicios-capa-aplicacion/references/capa-aplicacion-ts.md`.
+
+```ts
+import type { AggregateFinder, AggregateSaver } from '@archi-code/ddd/domain';
+import { AggregateNotFoundException, UseCase, ValueObjectBuilder } from '@archi-code/ddd/application';
+import type { Clock, EventBus } from '@archi-code/ddd/application';
+
+export interface PlaceOrderInput {
+  customerId: string;
+  lines: { sku: string; quantity: number }[];
+  shippingAddress: { street: string; city: string; country: string };
+}
+
+interface PlaceOrderCommand {
+  customerId: CustomerId;
+  lines: { sku: Sku; quantity: Quantity }[];
+  shippingAddress: ShippingAddress;
+}
+
+export class PlaceOrder extends UseCase<PlaceOrderInput, PlaceOrderCommand, string> {
+  constructor(
+    private readonly customers: AggregateFinder<Customer>,
+    private readonly orders: AggregateSaver<Order>,
+    private readonly pricing: ProductPricing,
+    private readonly events: EventBus<OrderEvent>,
+    private readonly clock: Clock,
+  ) {
+    super();
+  }
+
+  protected toCommand(input: PlaceOrderInput): PlaceOrderCommand {
+    return ValueObjectBuilder.build({
+      customerId: () => new CustomerId(input.customerId),
+      lines: () =>
+        ValueObjectBuilder.buildList(input.lines, (line) =>
+          ValueObjectBuilder.build({
+            sku: () => new Sku(line.sku),
+            quantity: () => new Quantity(line.quantity),
+          }),
+        ),
+      shippingAddress: () => ShippingAddress.fromPrimitives(input.shippingAddress),
+    });
+  }
+
+  protected async handle(command: PlaceOrderCommand): Promise<string> {
+    const customer = await this.customers.findById(command.customerId);
+    if (customer === null) {
+      throw new AggregateNotFoundException('Customer', command.customerId.value);
+    }
+    const items = await Promise.all(
+      command.lines.map(async ({ sku, quantity }) => {
+        const unitPrice = await this.pricing.priceForSale(sku);
+        if (unitPrice === null) {
+          throw new ProductNotSellable(sku.value);
+        }
+        return new OrderLine({ sku, quantity, unitPrice });
+      }),
+    );
+    const lines = new OrderLines({ items });
+    const order = customer.placeOrder(
+      OrderId.generate(),
+      lines,
+      command.shippingAddress,
+      this.clock,
+    );
+    await this.orders.save(order);
+    await this.events.publish(order.pullDomainEvents());
+    return order.id.value;
+  }
+}
+```
+
+* Las lecturas de otros agregados y contextos (`Customer`, precios) van antes de invocar al dominio [IDDD cap. 10].
+* `Customer` actúa como fábrica (comprueba que no está bloqueado) pero no se modifica ni se guarda: el caso de uso pide `AggregateFinder<Customer>` y `AggregateSaver<Order>`, y solo se guarda `Order`: una escritura atómica, un agregado; que esa escritura sea atómica lo garantiza el repositorio, no el caso de uso `[Fuera de los libros: convención de @archi-code/ddd]`.
+* El id nuevo sale del value object (`OrderId.generate()`), no del repositorio.
+* `toCommand` informa de todos los campos a la vez, también los de cada línea (`lines.0.quantity`).
+
+Los gastos de envío se han dejado fuera de este caso de uso para mantenerlo alineado con el `Order` de `ddd-skills/ddd-agregados/GUIA.md`; si el negocio los incorpora al pedido, el caso de uso carga lo que `ShippingCostCalculator` necesita, lo invoca y pasa el `Money` resultante a `placeOrder`.
+
+## Registrar la reserva de stock
+
+Una reacción a un evento es un listener `<Acción>On<Evento>`, decorado con `@ListensTo` y con un nombre de consumidor estable, que solo traduce el evento a la entrada de un caso de uso. Ese caso de uso registra un hecho que ya ocurrió: si el pedido no existe, retorna en vez de lanzar (el canal lo reentregaría sin fin), y `registerStockReservation` es idempotente, porque la entrega es al menos una vez.
+
+```ts
+import { EventBase } from '@archi-code/ddd/domain';
+import type { AggregateFinder, AggregateSaver, EventMetadata } from '@archi-code/ddd/domain';
+import { EventListener, ListensTo, UseCase, ValueObjectBuilder } from '@archi-code/ddd/application';
+import type { Clock, EventBus } from '@archi-code/ddd/application';
+
+export class StockReserved extends EventBase {
+  static readonly eventName = 'StockReserved';
+
+  constructor(
+    readonly reservationId: string,
+    readonly orderId: string,
+    metadata?: EventMetadata,
+  ) {
+    super(metadata);
+  }
+}
+
+export interface RegisterReservationInput {
+  orderId: string;
+  reservationId: string;
+}
+
+interface RegisterReservationCommand {
+  orderId: OrderId;
+  reservationId: ReservationId;
+}
+
+export class RegisterReservation extends UseCase<
+  RegisterReservationInput,
+  RegisterReservationCommand,
+  void
+> {
+  constructor(
+    private readonly orders: AggregateFinder<Order> & AggregateSaver<Order>,
+    private readonly events: EventBus<OrderEvent>,
+    private readonly clock: Clock,
+  ) {
+    super();
+  }
+
+  protected toCommand(input: RegisterReservationInput): RegisterReservationCommand {
+    return ValueObjectBuilder.build({
+      orderId: () => new OrderId(input.orderId),
+      reservationId: () => new ReservationId(input.reservationId),
+    });
+  }
+
+  protected async handle(command: RegisterReservationCommand): Promise<void> {
+    const order = await this.orders.findById(command.orderId);
+    if (order === null) {
+      return;
+    }
+    order.registerStockReservation(command.reservationId, this.clock);
+    await this.orders.save(order);
+    await this.events.publish(order.pullDomainEvents());
+  }
+}
+
+@ListensTo(StockReserved, { consumer: 'register-reservation-on-stock-reserved' })
+export class RegisterReservationOnStockReserved extends EventListener<StockReserved> {
+  constructor(private readonly registerReservation: RegisterReservation) {
+    super();
+  }
+
+  async handle(event: StockReserved): Promise<void> {
+    await this.registerReservation.execute({
+      orderId: event.orderId,
+      reservationId: event.reservationId,
+    });
+  }
+}
+```
+
+## Test del flujo
+
+El test comprueba lo que el listener provoca, no que se le llame, y entrega el mismo evento dos veces. `aPendingOrderOf`, `laura` y `orderId` son fábricas y datos de `test/support/` del proyecto, y `InMemoryOrderRepository` es el repositorio en memoria que el proyecto escribe allí (`ddd-skills/ddd-repositorios-persistencia/references/tests-repositorios.md`), como en `ddd-skills/ddd-servicios-capa-aplicacion/references/capa-aplicacion-ts.md`:
+
+```ts
+import { describe, expect, it } from 'vitest';
+import {
+  DomainEventBus,
+  EventRegistry,
+  FixedClock,
+  InMemoryEventChannel,
+} from '@archi-code/ddd/infrastructure';
+import { InMemoryOrderRepository } from '../support/in-memory-order-repository';
+
+const clock = new FixedClock('2026-03-01T09:30:00Z');
+const reservationId = '0f1e2d3c-4b5a-4968-8776-655443322110';
+
+describe('Registering the stock reservation of an order', () => {
+  it('the order keeps the reservation the warehouse made, also when it is delivered twice', async () => {
+    const orders = new InMemoryOrderRepository();
+    const registry = new EventRegistry<StockReserved>().register(
+      StockReserved,
+      (json) => new StockReserved(json.reservationId as string, json.orderId as string, json),
+    );
+    const channel = new InMemoryEventChannel();
+    const bus = new DomainEventBus<StockReserved>(channel, registry);
+    const sales = new DomainEventBus<OrderEvent>(channel, new EventRegistry<OrderEvent>());
+    await bus.subscribe(
+      new RegisterReservationOnStockReserved(
+        new RegisterReservation(orders, sales, clock),
+      ),
+    );
+    await orders.save(aPendingOrderOf(laura));
+    const reserved = new StockReserved(reservationId, orderId, { clock });
+
+    await bus.publish([reserved]);
+    await bus.publish([reserved]);
+
+    const order = await orders.findById(new OrderId(orderId));
+    expect(order?.stockReservation?.value).toBe(reservationId);
+  });
+});
+```