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

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

@@ -0,0 +1,294 @@
+# 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 comprobación optimista de la versión: una versión almacenada distinta de `order.version` (o un id ya ocupado al dar de alta) es `ConcurrencyException('Order', order.id.value, order.version)`.
+* La conexión, la sesión y el pool.
+* Envolver los errores del driver en `InternalErrorException` con `{ cause }`.
+* `markPersisted()` tras escribir con éxito y, al cargar, `Order.fromPrimitives(row).restoreVersion(version)`.
+
+## 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, InternalErrorException } from '@archi-code/ddd/exceptions';
+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> {
+  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];
+    return row ? Order.fromPrimitives({ ...row.data, lines: { items: row.items } }).restoreVersion(row.version) : null;
+  }
+
+  async save(order: Order): Promise<void> {
+    const { lines, ...data } = order.toPrimitives();
+    const client = await this.pool.connect();
+    let broken = false;
+    try {
+      await client.query('BEGIN');
+      const { rowCount } =
+        order.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, order.version, data.status, data],
+            );
+      if (rowCount === 0) {
+        throw new ConcurrencyException('Order', order.id.value, order.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);
+    }
+    order.markPersisted();
+  }
+}
+```
+
+* 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`.
+* `markPersisted()` se llama solo después del `COMMIT`: si la transacción se revierte, el objeto conserva su versión y el caso de uso puede descartarlo 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.toJSON(),
+  ]);
+}
+```
+
+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 { UseCase } from '@archi-code/ddd/application';
+import type { Clock, EventBus } from '@archi-code/ddd/application';
+import { ValueObjects } from '@archi-code/ddd/domain';
+import type { AggregateFinder, AggregateSaver } from '@archi-code/ddd/domain';
+import { AggregateNotFoundException, ConcurrencyException } from '@archi-code/ddd/exceptions';
+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 ValueObjects.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 `ValueObjects.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 `HttpErrorMapper` en los puntos de entrada; `execute` envuelve cualquier error ajeno al paquete en `InternalErrorException` 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`.

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 { ValueObjects } from '@archi-code/ddd/domain';
+import type { AggregateFinder, AggregateSaver } from '@archi-code/ddd/domain';
+import { UseCase } from '@archi-code/ddd/application';
+import type { Clock, EventBus } from '@archi-code/ddd/application';
+import { AggregateNotFoundException, NotAllowedException } from '@archi-code/ddd/exceptions';
+
+export interface SalesPermissions {
+  canCancelOrders(requester: CustomerId): Promise<boolean>;
+}
+
+export interface CancelOrderInput {
+  orderId: string;
+  requesterId: string;
+  reason: string;
+}
+
+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 ValueObjects.build({
+      orderId: () => new OrderId(input.orderId),
+      requester: () => new CustomerId(input.requesterId),
+      reason: () => new CancellationReason(input.reason),
+    });
+  }
+
+  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 `ValueObjects.build`: si algún campo no es válido lanza una sola `ValidationException` con el `field` y el `code` de cada problema (`ValueObjects.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 `InternalErrorException` 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 { ConcurrencyException, DomainException } from '@archi-code/ddd/exceptions';
+
+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 ValueObjects.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 `ValueObjects.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 `InternalErrorException`.
+* El punto de entrada los traduce con `HttpErrorMapper` de `@archi-code/ddd/infrastructure`: 404 `AggregateNotFoundException`, 403 `NotAllowedException`, 409 `ConcurrencyException`, 422 `ValidationException` y cualquier otra `DomainException` (regla de negocio), 400 otros errores de aplicación y 500, con mensaje genérico, para lo demás. Los códigos propios se ajustan por código (`new HttpErrorMapper({ statusByCode: { ORD001: 409 } })`) `[Fuera de los libros: convención de @archi-code/ddd]`.
+
+```ts
+import type { HttpErrorMapper } from '@archi-code/ddd/infrastructure';
+
+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 errors: HttpErrorMapper,
+  ) {}
+
+  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 : '',
+      });
+      return { status: 204 };
+    } catch (error) {
+      return this.errors.map(error);
+    }
+  }
+}
+```
+
+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/exceptions';
+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', aggregateId: 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í.