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

package/ddd-skills/ddd-repositorios-persistencia/references/transacciones-ts.md

@@ -0,0 +1,301 @@
+# La transacción es del repositorio
+
+El dominio nunca es el lugar para gestionar transacciones; sus operaciones son demasiado finas y no deben saber que existen. Los libros las sitúan en la capa de aplicación, a menudo con una fachada transaccional o de forma declarativa [IDDD cap. 12; PHP: Repositories, "Managing Transactions"].
+
+Con el paquete la transacción baja un nivel más: es del repositorio, igual que todo lo demás de la persistencia `[Fuera de los libros: convención de @archi-code/ddd]`. La aplicación nunca abre, une ni cierra transacciones y no hay ningún puerto para hacerlo. Un caso de uso recibe solo los roles del repositorio que usa (`AggregateFinder`, `AggregateSaver`, `AggregateRemover`), el `EventBus`, el `Clock` y sus puertos propios; nunca una dependencia `transactions`, `unitOfWork` o parecida.
+
+## Por qué basta con el repositorio
+
+Un caso de uso modifica un solo agregado y lo guarda una vez [IDDD cap. 10]. El agregado es el límite de consistencia, así que la "transacción por agregado" de los libros se traduce en **una escritura atómica por agregado, garantizada por el repositorio** `[Fuera de los libros: convención de @archi-code/ddd]`. No queda nada que la aplicación tenga que envolver: cargar es una lectura, y `save` o `remove` es una sola escritura atómica.
+
+Lo que hace el adaptador del repositorio, y nadie más:
+
+* Que cada `save` y cada `remove` sea atómico. En MongoDB, un documento por agregado: una sola escritura, atómica por sí misma. Si el agregado ocupa varias tablas SQL, el repositorio abre la transacción de la base de datos **dentro** de `save`/`remove`, con su propia conexión o sesión, y la confirma o la revierte antes de volver.
+* La versión de concurrencia optimista, que es solo suya: recuerda la de cada agregado que cargó o guardó en un `WeakMap<Order, number>` privado (`versions`; `0` si no lo conoce, es nuevo). Una versión almacenada distinta de la recordada (o un id ya ocupado al dar de alta) es `ConcurrencyException('Order', order.id.value, version)`.
+* La conexión, la sesión y el pool.
+* Envolver los errores del driver en `InternalErrorException` con `{ cause }`.
+* `this.versions.set(order, version + 1)` solo tras escribir con éxito y, al cargar, `Order.fromPrimitives(...)` seguido de `this.versions.set(order, row.version)`. El agregado no declara ni mapea la versión y el caso de uso nunca la ve.
+
+## Varias tablas en PostgreSQL
+
+`[Fuera de los libros: esquema propio siguiendo IDDD cap. 6]`
+
+Si las líneas del pedido viven en su propia tabla, guardar el pedido son varias sentencias, y el repositorio las agrupa en una transacción de la base de datos dentro de `save`. `SqlConnection` y `PgPool` describen, de forma estructural, los métodos de `pg` que usa; en `infrastructure/persistence/pg-pool.ts`:
+
+```ts
+export interface SqlConnection {
+  query<Row>(text: string, values?: unknown[]): Promise<{ rows: Row[]; rowCount: number | null }>;
+}
+
+export interface PgPool extends SqlConnection {
+  connect(): Promise<SqlConnection & { release(destroy?: boolean): void }>;
+}
+```
+
+```sql
+CREATE TABLE orders (
+  id           UUID        PRIMARY KEY,
+  version      INT         NOT NULL,
+  customer_id  UUID        NOT NULL,
+  status       TEXT        NOT NULL,
+  data         JSONB       NOT NULL
+);
+
+CREATE TABLE order_lines (
+  order_id     UUID        NOT NULL REFERENCES orders (id) ON DELETE CASCADE,
+  position     INT         NOT NULL,
+  sku          TEXT        NOT NULL,
+  quantity     INT         NOT NULL,
+  unit_price   JSONB       NOT NULL,
+  PRIMARY KEY (order_id, position)
+);
+```
+
+En `infrastructure/persistence/postgres-order-repository.ts`:
+
+```ts
+import type { AggregateFinder, AggregateSaver, PrimitiveTypes } from '@archi-code/ddd/domain';
+import { ConcurrencyException } from '@archi-code/ddd/application';
+import { InternalErrorException } from '@archi-code/ddd/infrastructure';
+import { Order, OrderId } from '../../domain/order/order';
+import type { PgPool } from './pg-pool';
+
+type OrderPrimitives = PrimitiveTypes<Order>;
+
+interface OrderRow {
+  version: number;
+  data: Omit<OrderPrimitives, 'lines'>;
+  items: OrderPrimitives['lines']['items'];
+}
+
+export class PostgresOrderRepository implements AggregateFinder<Order>, AggregateSaver<Order> {
+  private readonly versions = new WeakMap<Order, number>();
+
+  constructor(private readonly pool: PgPool) {}
+
+  async findById(id: OrderId): Promise<Order | null> {
+    const { rows } = await this.pool.query<OrderRow>(
+      `SELECT o.version, o.data,
+              COALESCE(
+                json_agg(
+                  json_build_object('sku', l.sku, 'quantity', l.quantity, 'unitPrice', l.unit_price)
+                  ORDER BY l.position
+                ) FILTER (WHERE l.order_id IS NOT NULL),
+                '[]'
+              ) AS items
+         FROM orders o
+         LEFT JOIN order_lines l ON l.order_id = o.id
+        WHERE o.id = $1
+        GROUP BY o.id`,
+      [id.value],
+    );
+    const row = rows[0];
+    if (row === undefined) {
+      return null;
+    }
+    const order = Order.fromPrimitives({ ...row.data, lines: { items: row.items } });
+    this.versions.set(order, row.version);
+    return order;
+  }
+
+  async save(order: Order): Promise<void> {
+    const version = this.versions.get(order) ?? 0;
+    const { lines, ...data } = order.toPrimitives();
+    const client = await this.pool.connect();
+    let broken = false;
+    try {
+      await client.query('BEGIN');
+      const { rowCount } =
+        version === 0
+          ? await client.query(
+              'INSERT INTO orders (id, version, customer_id, status, data) VALUES ($1, 1, $2, $3, $4) ON CONFLICT (id) DO NOTHING',
+              [data.id, data.customerId, data.status, data],
+            )
+          : await client.query(
+              'UPDATE orders SET version = version + 1, status = $3, data = $4 WHERE id = $1 AND version = $2',
+              [data.id, version, data.status, data],
+            );
+      if (rowCount === 0) {
+        throw new ConcurrencyException('Order', order.id.value, version);
+      }
+      await client.query('DELETE FROM order_lines WHERE order_id = $1', [data.id]);
+      for (const [position, line] of lines.items.entries()) {
+        await client.query(
+          'INSERT INTO order_lines (order_id, position, sku, quantity, unit_price) VALUES ($1, $2, $3, $4, $5)',
+          [data.id, position, line.sku, line.quantity, line.unitPrice],
+        );
+      }
+      await client.query('COMMIT');
+    } catch (error) {
+      await client.query('ROLLBACK').catch(() => {
+        broken = true;
+      });
+      if (error instanceof ConcurrencyException) {
+        throw error;
+      }
+      throw new InternalErrorException(`writing order ${order.id.value}`, { cause: error });
+    } finally {
+      client.release(broken);
+    }
+    this.versions.set(order, version + 1);
+  }
+}
+```
+
+* La transacción empieza y termina dentro de `save`: el caso de uso solo ve una escritura que se hace entera o no se hace.
+* El `UPDATE` con `version = $2` bloquea la fila del pedido hasta el `COMMIT`; otro `save` del mismo pedido espera y después no casa ninguna fila, así que recibe `ConcurrencyException`.
+* `this.versions.set(order, version + 1)` se hace solo después del `COMMIT`: si la transacción se revierte, el repositorio sigue recordando la versión anterior y el caso de uso puede descartar el objeto y volver a cargarlo.
+* Si el `ROLLBACK` falla (la conexión se cayó), se relanza el error del trabajo, no el del `ROLLBACK`, y `release(true)` destruye la conexión en vez de devolver al pool una con la transacción a medias.
+* La lectura es una sola sentencia, así que ve el pedido y sus líneas en el mismo instante.
+* Un `remove` sigue el mismo patrón: `DELETE FROM orders WHERE id = $1 AND version = $2` dentro de su propia transacción (las líneas caen con `ON DELETE CASCADE`).
+
+Con MongoDB no hace falta nada de esto: el pedido es un documento y `replaceOne` lo escribe de forma atómica (`MongoOrderRepository` en `ddd-skills/ddd-repositorios-persistencia/references/implementacion-ts.md`).
+
+## Eventos y guardado
+
+El caso de uso guarda y después publica: `await this.orders.save(order)` y `await this.events.publish(order.pullDomainEvents())`. Si `publish` falla después de `save`, el cambio queda guardado y 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 (una bandeja de salida, *outbox*, dentro del mismo documento o en la misma transacción de `save`), y un proceso aparte (*relay*) los entrega después a través de un `EventChannel` `[Fuera de los libros: convención de @archi-code/ddd]`. En el repositorio de PostgreSQL de arriba es una sentencia más antes del `COMMIT`:
+
+```ts
+for (const event of order.pullDomainEvents()) {
+  await client.query('INSERT INTO order_outbox (event_id, body) VALUES ($1, $2)', [
+    event.eventId,
+    { ...event },
+  ]);
+}
+```
+
+El repositorio toma los eventos con `pullDomainEvents()`, así que el `publish` posterior del caso de uso recibe una lista vacía y no envía nada: los casos de uso no cambian. Es persistencia, así que pertenece al adaptador del repositorio.
+
+## Uso en un caso de uso
+
+El caso de uso carga, cambia, guarda y publica, sin abrir nada. Si el comando es seguro de repetir contra el estado recargado, la aplicación puede reintentar una o dos veces ante `ConcurrencyException`; si no, el conflicto llega al usuario como 409 [IDDD cap. 10; IDDD apéndice A]. Cada intento vuelve a cargar y vuelve a guardar dentro de `handle`, en un bucle con límite `[Fuera de los libros: convención de @archi-code/ddd]`. Un caso de uso que ejecuta un listener no reintenta por su cuenta: reintenta la reentrega del canal.
+
+```ts
+import { AggregateNotFoundException, ConcurrencyException, UseCase, ValueObjectBuilder } from '@archi-code/ddd/application';
+import type { Clock, EventBus } from '@archi-code/ddd/application';
+import type { AggregateFinder, AggregateSaver } from '@archi-code/ddd/domain';
+import { Order, OrderId, OrderLine } from '../../domain/order/order';
+import type { OrderEvent } from '../../domain/order/order';
+
+export interface AddOrderLineInput {
+  orderId: string;
+  sku: string;
+  quantity: number;
+  unitPrice: { amount: number; currency: string };
+}
+
+interface AddOrderLineCommand {
+  orderId: OrderId;
+  line: OrderLine;
+}
+
+const ATTEMPTS = 3;
+
+export class AddOrderLine extends UseCase<AddOrderLineInput, AddOrderLineCommand, void> {
+  constructor(
+    private readonly orders: AggregateFinder<Order> & AggregateSaver<Order>,
+    private readonly events: EventBus<OrderEvent>,
+    private readonly clock: Clock,
+  ) {
+    super();
+  }
+
+  protected toCommand(input: AddOrderLineInput): AddOrderLineCommand {
+    return ValueObjectBuilder.build({
+      orderId: () => new OrderId(input.orderId),
+      line: () =>
+        OrderLine.fromPrimitives({
+          sku: input.sku,
+          quantity: input.quantity,
+          unitPrice: input.unitPrice,
+        }),
+    });
+  }
+
+  protected async handle(command: AddOrderLineCommand): Promise<void> {
+    for (let attempt = 1; ; attempt += 1) {
+      const order = await this.orders.findById(command.orderId);
+      if (order === null) {
+        throw new AggregateNotFoundException('Order', command.orderId.value);
+      }
+      order.addLine(command.line, this.clock);
+      try {
+        await this.orders.save(order);
+      } catch (error) {
+        if (error instanceof ConcurrencyException && attempt < ATTEMPTS) {
+          continue;
+        }
+        throw error;
+      }
+      await this.events.publish(order.pullDomainEvents());
+      return;
+    }
+  }
+}
+```
+
+`AggregateNotFoundException` la lanza el caso de uso, no el repositorio: `findById` devuelve `null`. Solo se reintenta el `save`: un error de `publish` no vuelve a guardar el pedido.
+
+## En tests
+
+Los tests de la aplicación usan el `InMemoryOrderRepository` que el proyecto escribe en `test/support/` (`ddd-skills/ddd-repositorios-persistencia/references/tests-repositorios.md`) y un `DomainEventBus` sobre `InMemoryEventChannel`; no hay nada que revertir ni que contar, porque cada `save` del repositorio en memoria es atómico y comprueba la versión igual que uno real. En `test/contexts/sales/application/add-order-line.spec.ts`:
+
+```ts
+import { describe, expect, it } from 'vitest';
+import {
+  DomainEventBus,
+  EventRegistry,
+  FixedClock,
+  InMemoryEventChannel,
+} from '@archi-code/ddd/infrastructure';
+import { AddOrderLine } from '../../../../src/contexts/sales/application/add-order-line/add-order-line';
+import {
+  CustomerId,
+  Order,
+  OrderId,
+  OrderLines,
+  ShippingAddress,
+} from '../../../../src/contexts/sales/domain/order/order';
+import type { OrderEvent } from '../../../../src/contexts/sales/domain/order/order';
+import { InMemoryOrderRepository } from '../../../support/in-memory-order-repository';
+
+describe('Two customers add a line to the same order at once', () => {
+  it('the second one retries with the reloaded order and both lines are kept', async () => {
+    const clock = new FixedClock('2026-03-01T09:30:00Z');
+    const orders = new InMemoryOrderRepository();
+    const channel = new InMemoryEventChannel();
+    const addOrderLine = new AddOrderLine(
+      orders,
+      new DomainEventBus<OrderEvent>(channel, new EventRegistry<OrderEvent>()),
+      clock,
+    );
+    const order = Order.place(
+      OrderId.generate(),
+      CustomerId.generate(),
+      OrderLines.fromPrimitives({
+        items: [{ sku: 'TORCH-01', quantity: 2, unitPrice: { amount: 4990, currency: 'EUR' } }],
+      }),
+      ShippingAddress.fromPrimitives({ street: 'Calle Mayor 1', city: 'Huelva', country: 'ES' }),
+      clock,
+    );
+    await orders.save(order);
+    const unitPrice = { amount: 1990, currency: 'EUR' };
+
+    await Promise.all([
+      addOrderLine.execute({ orderId: order.id.value, sku: 'HELMET-02', quantity: 1, unitPrice }),
+      addOrderLine.execute({ orderId: order.id.value, sku: 'GLOVES-03', quantity: 1, unitPrice }),
+    ]);
+
+    const stored = await orders.findById(order.id);
+    expect(stored?.toPrimitives().lines.items).toHaveLength(3);
+    expect(channel.sent).toMatchObject([
+      { eventName: 'OrderLineAdded', sku: 'HELMET-02' },
+      { eventName: 'OrderLineAdded', sku: 'GLOVES-03' },
+    ]);
+  });
+});
+```
+
+Los dos casos de uso cargan el pedido en la versión 1; el primero guarda, el segundo recibe `ConcurrencyException`, vuelve a cargar y guarda sobre la versión 2. La atomicidad de un repositorio real (sus varias tablas, su outbox) se prueba en su propio spec, con la suite de contrato de `ddd-skills/ddd-repositorios-persistencia/references/tests-repositorios.md` contra la base de datos de verdad.

package/ddd-skills/ddd-servicios-capa-aplicacion/GUIA.md

@@ -0,0 +1,99 @@
+# Servicios de dominio y capa de aplicación
+
+> Parte del skill `archi-code-ddd`: léela solo cuando ese skill te dirija aquí. Los ejemplos están escritos con la API de `@archi-code/ddd` (las clases de su `src`) y se copian tal cual; las guías son la fuente de verdad: el paquete solo se aparta de ellas donde lo marca `[Fuera de los libros: convención de @archi-code/ddd]`, y cualquier otra discrepancia es un defecto del paquete.
+>
+> **Cuándo consultar esta guía.** Servicios de dominio y servicios de aplicación (casos de uso) en DDD con TypeScript. Cubre cuándo una operación merece un servicio de dominio y cuándo pertenece a una entidad o value object, cómo evitar el modelo anémico, cómo escribir casos de uso finos (cargar, invocar, guardar, publicar), comandos y DTOs de entrada, salida mediante DTOs o read models, command bus, dónde queda la transacción (en el repositorio), seguridad y autorización, manejo de errores y tests de la capa de aplicación con adaptadores en memoria. Consúltala siempre que se escriba o revise un "service", "manager", "handler", "use case" o "interactor", cuando la lógica de negocio esté en servicios en vez de en el modelo, al decidir dónde va una regla que implica varios objetos, o al conectar un controlador con el dominio, aunque no se mencione DDD.
+
+## Con @archi-code/ddd
+
+[Fuera de los libros: convención de @archi-code/ddd]
+
+* Un caso de uso extiende `UseCase<Input, Command, Output>`: un `Input` de primitivos, un `Command` de value objects que construye `toCommand` con `ValueObjectBuilder.build` (informa de todos los campos a la vez), y `handle`, sin ayudas de la clase base, carga, cambia, guarda (`await this.orders.save(order)`) y publica (`await this.events.publish(order.pullDomainEvents())`). No hay puerto de transacciones: el caso de uso recibe solo los roles de repositorio que usa (`AggregateFinder`, `AggregateSaver`, `AggregateRemover`), `EventBus`, `Clock` y sus puertos propios, y el repositorio garantiza que cada `save` o `remove` es una escritura atómica. Una acción de negocio por caso de uso, con nombre de verbo del negocio (`PlaceOrder`, `AddOrderLine`).
+* Un caso de uso nunca importa ni llama a otro: las acciones se encadenan con eventos y listeners `<Acción>On<Evento>` decorados con `@ListensTo`, que solo mapean el evento a la entrada de un caso de uso. No hay bus de comandos: el punto de entrada llama a `execute(input)`.
+* Los servicios de dominio son clases sin base en `domain/` que reciben agregados y value objects, y pueden leer con un contrato `AggregateFinder` o un puerto de dominio; nunca guardan ni publican, y no tocan la persistencia.
+* Errores: `AggregateNotFoundException` (404) y `NotAllowedException` (403) en el caso de uso, `DomainException` con código propio en el dominio, y en los puntos de entrada `ExceptionClassifier.classify(error)`, cuyo `ExceptionKind` cada protocolo traduce a sus códigos; `execute` envuelve cualquier error ajeno al paquete en `UnexpectedErrorException` con `cause`.
+* Un `ConcurrencyException` se reintenta, si el comando es seguro de repetir, con un bucle en `handle` con un límite de intentos en el que cada intento vuelve a cargar el agregado y vuelve a guardarlo. Un caso de uso que ejecuta un listener no reintenta por sí mismo: reintenta la reentrega del canal.
+* Un caso de uso que ejecuta un listener para registrar un hecho no lanza si falta el agregado: retorna, para que el canal no lo reentregue sin fin.
+
+Dos cosas con el mismo nombre ("servicio") y papeles opuestos. Confundirlas es la vía más rápida hacia un modelo anémico [IDDD cap. 7 y cap. 14].
+
+| | Servicio de dominio | Servicio de aplicación |
+|---|---|---|
+| Contiene lógica de negocio | **Sí** | **No** |
+| Vive en | `domain/` | `application/` |
+| Nombre | Del lenguaje ubicuo | Del caso de uso |
+| Estado | Sin estado [IDDD cap. 7] | Sin estado; coordina |
+| Transacciones y seguridad | Nunca [IDDD cap. 7] | Seguridad sí; transacciones según IDDD sí [IDDD cap. 14], con el paquete las garantiza el repositorio `[Fuera de los libros: convención de @archi-code/ddd]` |
+| Quién lo llama | Servicios de aplicación (u otros de dominio) | Adaptadores de entrada (HTTP, mensajes, CLI) |
+
+Ninguno es un servicio SOA remoto ni tiene por qué ser pesado [IDDD cap. 7].
+
+
+## Paso 1. ¿Dónde va esta lógica?
+
+Árbol de decisión `[Fuera de los libros: síntesis de IDDD cap. 7, cap. 10 y cap. 14]`:
+
+1. ¿Es una regla sobre el estado de **un** agregado? → método del agregado.
+2. ¿Es un cálculo o comportamiento sobre unos valores? → método del value object.
+3. ¿Es un proceso de negocio relevante, una transformación de una composición a otra, o un cálculo que necesita **varios** objetos de dominio y queda forzado en cualquiera de ellos? → **servicio de dominio** [IDDD cap. 7].
+4. ¿Es coordinación: cargar, decidir qué invocar, guardar, publicar, autorizar? → **servicio de aplicación** [IDDD cap. 14].
+5. ¿Es formato, protocolo o traducción de otro sistema? → adaptador o ACL.
+
+Si la "lógica" es una regla con nombre que decide si algo cumple un criterio (cliente moroso, pedido apto para envío urgente), suele ser una **Specification**, no un servicio (ver `ddd-skills/ddd-value-objects-entidades/GUIA.md`).
+
+Antes de crear un servicio de dominio, asegúrate de que lo necesitas. Usarlos por defecto lleva al modelo anémico [IDDD cap. 7]. IDDD admite una "mini capa" de servicios de dominio en algunos contextos, pero avisa de que es un camino peligroso [IDDD cap. 7].
+
+## Paso 2. Servicios de dominio
+
+* Interfaz con el lenguaje del modelo; el nombre de la operación forma parte del lenguaje ubicuo; sin estado [IDDD cap. 7, citando a Evans].
+* Reciben y devuelven objetos de dominio, no DTOs ni primitivos.
+* Algunos tienen implementación técnica en infraestructura, sobre todo los de integración, con interfaz en el dominio (ver la ACL en `ddd-skills/ddd-context-mapping/GUIA.md`) [IDDD cap. 7].
+* Pueden leer agregados por repositorio para cálculos o validaciones de composición [IDDD cap. 5 y cap. 7], pero **no modifican varios agregados** en una misma operación. Con el paquete, el servicio lee con `AggregateFinder` (el contrato del dominio) o el caso de uso le pasa los agregados ya cargados; nunca recibe `AggregateSaver` ni `AggregateRemover`.
+* El paquete no trae clase base: un servicio de dominio es una clase normal; una regla con nombre que decide si algo cumple un criterio es una `Specification<T>` de `@archi-code/ddd/domain`.
+
+Ejemplos e implementación en `ddd-skills/ddd-servicios-capa-aplicacion/references/servicios-dominio-ts.md`.
+
+## Paso 3. Servicios de aplicación
+
+* Clientes directos del modelo; un método por flujo de caso de uso; según IDDD controlan transacciones y seguridad [IDDD cap. 14]. Con el paquete la seguridad sigue en el caso de uso, pero la transacción pasa al repositorio `[Fuera de los libros: convención de @archi-code/ddd]`.
+* **Finos.** Si crecen, la lógica de dominio se escapa y el modelo se vuelve anémico [IDDD cap. 4 y cap. 14; PHP: Application].
+* Forma típica: recibir parámetros, obtener el agregado del repositorio, ejecutar un comando sobre él, guardar [IDDD cap. 4].
+* Entrada con primitivos, DTOs o, mejor, objetos comando [PHP: Application, citando a Vernon]. Con el paquete, un `Input` plano de primitivos y un `Command` de value objects que construye `toCommand` `[Fuera de los libros: convención de @archi-code/ddd]`.
+* Salida: identificador, DTO de lectura, o nada (con un puerto de salida), según lo que necesite el cliente [IDDD cap. 14]. Es el tipo `Output` de `UseCase`; nunca el agregado.
+* Transacciones: IDDD las pone en el servicio de aplicación [IDDD cap. 14]. Con el paquete la aplicación nunca abre, une ni cierra transacciones y no hay puerto para ello: el adaptador del repositorio es responsable de todo lo de persistencia (que cada `save`/`remove` sea atómico, la comprobación de versión con `ConcurrencyException`, la conexión o sesión, envolver los errores del driver en `InternalErrorException` con `{ cause }`). "Una transacción por agregado" se traduce en "una escritura atómica por agregado, garantizada por el repositorio" `[Fuera de los libros: convención de @archi-code/ddd]`.
+
+Plantilla, variantes y errores frecuentes en `ddd-skills/ddd-servicios-capa-aplicacion/references/capa-aplicacion-ts.md`.
+
+## Paso 4. Seguridad
+
+* La autorización del caso de uso ("¿puede este usuario cancelar pedidos?") es responsabilidad de la aplicación [IDDD cap. 14]: el caso de uso consulta un puerto de aplicación propio (`SalesPermissions`) y lanza `NotAllowedException` (403).
+* Si la regla es de negocio ("solo el cliente que hizo el pedido puede cancelarlo"), pertenece al modelo y se expresa con conceptos del contexto (`Customer`, no `User`) [IDDD cap. 2].
+* La identidad del solicitante viene del token en el adaptador, nunca del cuerpo de la petición; el adaptador la pone en el `Input` y `toCommand` la convierte en value object.
+* La autenticación (quién es el solicitante) la resuelve la plataforma o el adaptador de entrada según las normas del proyecto; esta guía solo cubre dónde encaja la autorización en la arquitectura.
+
+## Paso 5. Probar
+
+* Servicios de dominio: tests unitarios con objetos de dominio reales [IDDD cap. 7].
+* Servicios de aplicación: con repositorios y adaptadores **en memoria**; comprueban orquestación, no reglas de negocio [IDDD cap. 12; PHP: Application]. El repositorio en memoria lo escribe el proyecto en `test/support/`, uno por agregado (`InMemoryOrderRepository`, como en `ddd-skills/ddd-repositorios-persistencia/references/tests-repositorios.md`); del paquete: `DomainEventBus` sobre `InMemoryEventChannel` (`channel.sent`) y `FixedClock`.
+* Las reglas de negocio se prueban en el agregado o el value object, no a través del caso de uso.
+
+## Señales de alarma
+
+* `OrderService` con 40 métodos y entidades con solo getters y setters [Destilado cap. 5].
+* `if` sobre el estado de una entidad dentro del servicio de aplicación.
+* Servicios de dominio llamados `XxxManager`, `XxxHelper`, `XxxUtils` [Destilado cap. 5].
+* Un servicio de dominio que abre transacciones o comprueba permisos de usuario.
+* Un caso de uso que abre o maneja transacciones, o recibe un runner de transacciones o una unidad de trabajo: eso va dentro del adaptador del repositorio.
+* Un caso de uso que guarda dos agregados.
+* El caso de uso devuelve el agregado al controlador.
+* Un caso de uso que importa o llama a otro caso de uso.
+* Tests de reglas de negocio escritos contra el caso de uso con mocks de todo.
+
+## Ejemplo
+
+`ddd-skills/ddd-servicios-capa-aplicacion/references/ejemplo-ecommerce.md`: lo que Ventas añade al `Order` de `ddd-skills/ddd-agregados/references/implementacion-ts.md` (`OrderAbove`, `Customer`, `OrderCancellation`), caso de uso `PlaceOrder`, listener `RegisterReservationOnStockReserved` con su caso de uso `RegisterReservation` y su test. El servicio de dominio `ShippingCostCalculator` está en `ddd-skills/ddd-servicios-capa-aplicacion/references/servicios-dominio-ts.md`, y `CancelOrder` y `AddOrderLine` en `ddd-skills/ddd-servicios-capa-aplicacion/references/capa-aplicacion-ts.md`.
+
+## Siguiente guía
+
+* Si las lecturas se complican o hay mucho volumen → `ddd-skills/ddd-event-sourcing-cqrs/GUIA.md`.
+* Para revisar un proyecto existente con todo esto → `ddd-skills/ddd-auditoria-refactorizacion/GUIA.md`.