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

package/ddd-skills/ddd-auditoria-refactorizacion/GUIA.md

@@ -0,0 +1,85 @@
+# Auditoría y refactorización con DDD
+
+> 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.** Auditar un proyecto existente contra las reglas de DDD y planificar su refactorización incremental. Incluye un script que escanea un repositorio TypeScript en busca de síntomas (dominio que importa frameworks u ORM, setters y campos públicos, servicios gigantes, repositorios de partes internas, importaciones entre contextos, transacciones con varios agregados, transacciones abiertas en la capa de aplicación), una lista de comprobación estratégica y táctica con severidad, un informe con formato fijo y un plan de migración por pasos (tests de caracterización, capa anticorrupción, extracción de contextos y agregados, estrangulamiento del legado). Consúltala siempre que alguien pida revisar, auditar, evaluar o "pasar a DDD" un código existente, modernizar un monolito, sacar un servicio de un sistema heredado, o pregunte "¿está bien hecho este DDD?", aunque solo pegue unos ficheros.
+
+## Con @archi-code/ddd
+
+[Fuera de los libros: convención de @archi-code/ddd]
+
+* En código hecho con el paquete, aplica además cada punto de `ddd-skills/archi-code-ddd/what-not-to-do.md` como lista de comprobación: el paquete da las clases base, pero no impide un agregado anémico con setters, un caso de uso CRUD, dos agregados guardados en el mismo caso de uso o un caso de uso que abre su propia transacción (la transacción es del repositorio).
+* La dirección de dependencias es la del paquete: el dominio importa solo `@archi-code/ddd/domain`, `@archi-code/ddd/exceptions` y `@archi-code/validation`; importar `/application` o `/infrastructure` (por ejemplo `SystemClock`) o un adaptador de `infrastructure/` del proyecto desde el dominio es un hallazgo de severidad alta (A8 de la lista).
+* El reloj es un puerto (`Clock`; `FixedClock` en tests): `new Date()` en dominio o aplicación es un hallazgo (A9).
+* El escáner detecta guardados de cualquier variable (`this.orders.save(...)`, `this.customers.remove(...)`) dentro del mismo bloque transaccional o de la misma clase de aplicación, transacciones abiertas o recibidas en dominio y aplicación (bloques transaccionales, `startSession`, runners de transacciones, unidades de trabajo), imports de `@archi-code/ddd/application` o `/infrastructure` desde el dominio, `new Date()` en dominio y aplicación, y campos de estado primitivos con el prefijo `_` del paquete (`private _status: string`). Marca `amount: number` o `status: string` también dentro de los eventos: ahí son esperables, porque el payload de un evento son primitivos.
+
+No puedes cambiar todo el código mal diseñado de una vez; puedes hacer bien tu parte e integrarte con el resto [IDDD cap. 2]. Esta guía convierte esa idea en un procedimiento: medir, priorizar y cambiar por pasos seguros.
+
+
+## Paso 1. Escaneo automático
+
+Si tienes acceso al repositorio, desde la carpeta del paquete (la que contiene `ddd-skills/`; `SKILL.md` explica cómo localizarla):
+
+```bash
+python3 -I ddd-skills/ddd-auditoria-refactorizacion/scripts/scan_ddd_smells.py <ruta-del-repo> --json informe-escaneo.json
+```
+
+El script es heurístico y solo lee ficheros. Detecta los síntomas de `ddd-skills/ddd-auditoria-refactorizacion/references/lista-comprobacion.md` que se pueden ver con patrones de texto. Lo que no detecta (lenguaje, invariantes, límites de contexto) se revisa a mano en el paso 2.
+
+Si solo tienes fragmentos pegados, aplica la misma lista leyendo el código.
+
+## Paso 2. Revisión manual
+
+Recorre `ddd-skills/ddd-auditoria-refactorizacion/references/lista-comprobacion.md` en este orden. La integración entre contextos va primero porque un problema de límites invalida mejoras tácticas:
+
+1. **Integración entre contextos:** términos con varios significados en el mismo código, contextos implícitos, clases de dominio importadas entre contextos, integraciones por base de datos, sistemas externos sin ACL.
+2. **Arquitectura:** dependencias del dominio, dónde están las transacciones (con el paquete, solo dentro de los adaptadores de repositorio), qué expone la API.
+3. **Táctico:** modelo anémico (prueba de salud de IDDD), agregados grandes, referencias directas entre agregados en vez de ids, setters en vez de métodos de negocio, primitivos en el estado en vez de value objects, repositorios de partes o con métodos de negocio en vez de los roles `AggregateFinder`/`AggregateSaver`/`AggregateRemover`, casos de uso CRUD o que guardan varios agregados, listeners con reglas de negocio, eventos ausentes o mal nombrados.
+
+Para modelo anémico usa las dos preguntas de IDDD: ¿el "modelo de dominio" son sobre todo getters y setters sin lógica de negocio? ¿Los componentes que lo usan contienen la mayor parte de la lógica? Dos "sí" indican anemia [IDDD cap. 1, reformulado]. Extender `AggregateRoot` no responde a ninguna de las dos: un agregado del paquete con `setStatus` y las reglas en el `handle` del caso de uso sigue siendo anémico.
+
+## Paso 3. Informe
+
+Recoge el alcance, los hallazgos con evidencia (fichero y línea) y severidad, el plan por fases y la deuda de modelo aceptada.
+
+Severidad `[Fuera de los libros]`:
+
+| Nivel | Criterio |
+|---|---|
+| Crítica | Corrompe datos o reglas de negocio hoy (invariantes sin proteger, varios agregados en una transacción con conflictos, eventos que se pierden) |
+| Alta | Impide cambiar el Core Domain con seguridad (lenguaje mezclado, dominio acoplado al ORM, lógica en controladores) |
+| Media | Encarece el cambio (primitivos en el estado, setters, repositorios de partes, `new Date()` en vez de `Clock`) |
+| Baja | Estilo y nomenclatura |
+
+## Paso 4. Plan de refactorización
+
+Secuencia y técnicas en `ddd-skills/ddd-auditoria-refactorizacion/references/plan-migracion.md`. Principios:
+
+* **Primero red de seguridad:** tests de caracterización sobre el comportamiento actual antes de mover nada `[Fuera de los libros]`.
+* **Proteger antes de reconstruir:** una capa anticorrupción entre el código nuevo y el heredado, para no hablar su lenguaje [Destilado cap. 4].
+* **Pasos pequeños y desplegables.**
+* **No reescribir de golpe.** El estrangulamiento progresivo (strangler fig) y los contextos burbuja (bubble context, Evans) permiten convivir con el legado `[Fuera de los libros]`.
+
+## Cómo usar las demás guías
+
+| Hallazgo | Guía para resolverlo |
+|---|---|
+| Integraciones frágiles, modelo ajeno filtrado | `ddd-skills/ddd-context-mapping/GUIA.md` |
+| Dominio acoplado a frameworks | `ddd-skills/ddd-arquitectura/GUIA.md` |
+| Primitivos en el estado, setters, identidades | `ddd-skills/ddd-value-objects-entidades/GUIA.md` |
+| Agregados grandes o transacciones múltiples | `ddd-skills/ddd-agregados/GUIA.md` |
+| Eventos perdidos o mal diseñados, listeners con reglas | `ddd-skills/ddd-eventos-dominio/GUIA.md` |
+| Repositorios tipo DAO, versión sin comprobar, transacciones o unidades de trabajo en los casos de uso | `ddd-skills/ddd-repositorios-persistencia/GUIA.md` |
+| Casos de uso gordos o CRUD | `ddd-skills/ddd-servicios-capa-aplicacion/GUIA.md` |
+| Lecturas complejas | `ddd-skills/ddd-event-sourcing-cqrs/GUIA.md` |
+
+## Señales de que la auditoría va mal
+
+* Recomendar "pasar todo a DDD". DDD táctico donde no hay complejidad es un coste sin beneficio [IDDD cap. 1].
+* Proponer una reescritura completa.
+* Hallazgos sin evidencia (sin fichero ni línea).
+* Recomendar microservicios antes de tener claros los contextos.
+
+## Ejemplo
+
+`ddd-skills/ddd-auditoria-refactorizacion/references/ejemplo-auditoria.md`: auditoría resumida de un backend de pedidos hecho con `@archi-code/ddd` y mal usado (agregado anémico con setters, `UpdateOrder` CRUD, pedido y cliente guardados en la misma transacción, casos de uso con su propia unidad de trabajo, estado como `string`), con el código antes y después, hallazgos y plan por fases.

package/ddd-skills/ddd-auditoria-refactorizacion/references/ejemplo-auditoria.md

@@ -0,0 +1,316 @@
+# Ejemplo: auditoría de un backend de pedidos hecho con @archi-code/ddd
+
+Caso inventado para mostrar el nivel esperado del informe. El equipo usa el paquete, pero lo usa mal: tiene las clases base, no el modelo.
+
+## Contexto
+
+API en TypeScript con Express y MongoDB, contexto `sales`, unos 120 ficheros. `Order` extiende `AggregateRoot` y los casos de uso extienden `UseCase`. Síntomas: pedidos enviados sin líneas, puntos de fidelidad duplicados cuando dos pedidos del mismo cliente llegan a la vez (`ConcurrencyException` sobre `Customer` que tumba el alta del pedido) y estados escritos con erratas (`"shiped"`).
+
+## Escaneo
+
+```
+[alta ] dominio-importa-capa-exterior-del-paquete: 2
+[alta ] varios-agregados-en-una-transaccion: 3
+[media] dinero-como-number: 4
+[media] new-date-en-dominio-o-aplicacion: 7
+[media] setter-en-dominio: 11
+[media] transaccion-en-aplicacion: 2
+[baja ] estado-como-string: 2
+```
+
+La prueba de anemia da dos "sí" [IDDD cap. 1]: `Order` tiene `setStatus`, `setTotal` y `setLines`, y las reglas (no enviar un pedido vacío, no tocar uno enviado) están en `UpdateOrder`.
+
+## Código auditado (antes)
+
+```ts
+import { AggregateRoot, CreatedAt, UpdatedAt } from '@archi-code/ddd/domain';
+import { OrderMapper } from '../../infrastructure/order-mapper';
+
+class Order extends AggregateRoot<OrderId, OrderEvent> {
+  private _status: string;
+  private _total: number;
+  // …
+  setStatus(status: string): void {
+    this._status = status;
+    this._updatedAt = new UpdatedAt(new Date());
+  }
+
+  setTotal(total: number): void {
+    this._total = total;
+  }
+
+  static mapper = new OrderMapper();
+}
+
+class UpdateOrder extends UseCase<UpdateOrderInput, UpdateOrderInput, void> {
+  protected toCommand(input: UpdateOrderInput): UpdateOrderInput {
+    return input;
+  }
+
+  protected handle(input: UpdateOrderInput): Promise<void> {
+    return this.unitOfWork.run(async () => {
+      const order = await this.orders.findById(new OrderId(input.orderId));
+      if (input.status === 'shipped' && order!.lines.length === 0) {
+        throw new Error('Empty order');
+      }
+      if (input.status) order!.setStatus(input.status);
+      if (input.total) order!.setTotal(input.total);
+      await this.orders.save(order!);
+    });
+  }
+}
+
+class PlaceOrder extends UseCase<PlaceOrderInput, PlaceOrderCommand, void> {
+  protected handle(command: PlaceOrderCommand): Promise<void> {
+    return this.unitOfWork.run(async () => {
+      const order = Order.place(command.orderId, command.customerId, this.clock);
+      const customer = await this.customers.findById(command.customerId);
+      customer!.awardPointsFor(command.orderId);
+      await this.orders.save(order);
+      await this.customers.save(customer!);
+      await this.events.publish(order.pullDomainEvents());
+    });
+  }
+}
+```
+
+## Hallazgos principales
+
+| # | Hallazgo | Evidencia | Severidad |
+|---|---|---|---|
+| 1 | `PlaceOrder` guarda `Order` y `Customer` en la misma `unitOfWork.run`: un conflicto de versión en el cliente anula el pedido | `application/place-order/place-order.ts:31` | Crítica |
+| 2 | Reglas de envío en el caso de uso; `Order` solo tiene setters (modelo anémico) | `domain/order/order.ts:48`, `application/update-order/update-order.ts:22` | Alta |
+| 3 | `UpdateOrder` hace varias cosas según el input (enviar, cambiar total, cambiar líneas): nombre CRUD, no una acción de negocio | `application/update-order/update-order.ts` | Alta |
+| 4 | El dominio importa `OrderMapper`, un mapper escrito a mano en `infrastructure/`, y le delega la conversión a primitivos | `domain/order/order.ts:2` | Alta |
+| 5 | Estado y total como primitivos (`_status: string`, `_total: number`) en vez de value objects | `domain/order/order.ts:5-6` | Media |
+| 6 | `toCommand` devuelve el input tal cual: ningún value object se construye ni valida antes de `handle` | `application/update-order/update-order.ts:14` | Media |
+| 7 | `new Date()` en el agregado: fechas no deterministas en tests | `domain/order/order.ts:10` | Media |
+| 8 | `throw new Error(...)` en vez de una `DomainException` con código: el `HttpErrorMapper` responde 500 | `application/update-order/update-order.ts:18` | Media |
+| 9 | Los casos de uso reciben un `UnitOfWork` del proyecto y abren la transacción con `unitOfWork.run`: la transacción y todo lo de persistencia son del adaptador del repositorio, que hace atómico cada `save` | `application/update-order/update-order.ts:17`, `application/place-order/place-order.ts:27` | Media |
+
+Los hallazgos 2, 3 y 6 se cruzan además con `ddd-skills/archi-code-ddd/what-not-to-do.md` (casos de uso CRUD, value objects fuera de `toCommand`, reglas de negocio fuera del agregado).
+
+## Código propuesto (después)
+
+El pedido pasa a ser el `Order` de `ddd-skills/ddd-agregados/references/implementacion-ts.md`, con sus value objects y eventos; no se redefine aquí. El estado es un value object con comportamiento (`OrderStatus`), el total deja de guardarse porque sale de las líneas, y las líneas son `OrderLines`, un `Composite` de `OrderLine` (con `Money`) cuya regla `hasLines` impide crear un pedido sin líneas. Lo que usan los casos de uso de este ejemplo:
+
+```ts
+static place(
+  id: OrderId,
+  customerId: CustomerId,
+  lines: OrderLines,
+  address: ShippingAddress,
+  clock: { now(): Date },
+): Order;
+addLine(line: OrderLine, clock: { now(): Date }): void;
+```
+
+Enviar no es trabajo del pedido de Ventas: lo hace `Shipment` en Almacén, que publica `ShipmentDispatched` (`ddd-skills/ddd-agregados/references/ejemplo-ecommerce.md`), así que `status: 'shipped'` y su errata desaparecen de Ventas. `UpdateOrder` se parte en un caso de uso por acción de negocio (`AddOrderLine` aquí; el envío, en Almacén); cada uno construye sus value objects en `toCommand` y guarda un solo agregado:
+
+```ts
+import { ValueObjects } from '@archi-code/ddd/domain';
+import type { AggregateFinder, AggregateSaver } from '@archi-code/ddd/domain';
+import { AggregateNotFoundException } from '@archi-code/ddd/exceptions';
+import { UseCase } from '@archi-code/ddd/application';
+import type { Clock, EventBus } from '@archi-code/ddd/application';
+
+interface AddOrderLineInput {
+  orderId: string;
+  sku: string;
+  quantity: number;
+  unitPrice: { amount: number; currency: string };
+}
+
+interface AddOrderLineCommand {
+  orderId: OrderId;
+  line: OrderLine;
+}
+
+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> {
+    const order = await this.orders.findById(command.orderId);
+    if (order === null) {
+      throw new AggregateNotFoundException('Order', command.orderId.value);
+    }
+    order.addLine(command.line, this.clock);
+    await this.orders.save(order);
+    await this.events.publish(order.pullDomainEvents());
+  }
+}
+```
+
+`PlaceOrder` guarda solo el pedido; los puntos del cliente se conceden después, en su propia escritura atómica, cuando llega `OrderPlaced` (consistencia eventual fuera del límite del agregado [IDDD cap. 10]). El caso de uso que corre el listener no rechaza el hecho: si el cliente no existe, vuelve; y `Customer.awardPointsFor(orderId)` (un método de negocio del agregado `Customer`) ignora un pedido ya premiado, porque el canal entrega al menos una vez:
+
+```ts
+import { EventListener, ListensTo } from '@archi-code/ddd/application';
+
+interface PlaceOrderInput {
+  orderId: string;
+  customerId: string;
+  lines: { sku: string; quantity: number; unitPrice: { amount: number; currency: string } }[];
+  shippingAddress: { street: string; city: string; country: string };
+}
+
+interface PlaceOrderCommand {
+  orderId: OrderId;
+  customerId: CustomerId;
+  lines: OrderLines;
+  shippingAddress: ShippingAddress;
+}
+
+interface AwardLoyaltyPointsInput {
+  customerId: string;
+  orderId: string;
+}
+
+interface AwardLoyaltyPointsCommand {
+  customerId: CustomerId;
+  orderId: OrderId;
+}
+
+class PlaceOrder extends UseCase<PlaceOrderInput, PlaceOrderCommand, void> {
+  constructor(
+    private readonly orders: AggregateSaver<Order>,
+    private readonly events: EventBus<OrderEvent>,
+    private readonly clock: Clock,
+  ) {
+    super();
+  }
+
+  protected toCommand(input: PlaceOrderInput): PlaceOrderCommand {
+    return ValueObjects.build({
+      orderId: () => new OrderId(input.orderId),
+      customerId: () => new CustomerId(input.customerId),
+      lines: () => OrderLines.fromPrimitives({ items: input.lines }),
+      shippingAddress: () => ShippingAddress.fromPrimitives(input.shippingAddress),
+    });
+  }
+
+  protected async handle(command: PlaceOrderCommand): Promise<void> {
+    const order = Order.place(
+      command.orderId,
+      command.customerId,
+      command.lines,
+      command.shippingAddress,
+      this.clock,
+    );
+    await this.orders.save(order);
+    await this.events.publish(order.pullDomainEvents());
+  }
+}
+
+class AwardLoyaltyPoints extends UseCase<AwardLoyaltyPointsInput, AwardLoyaltyPointsCommand, void> {
+  constructor(private readonly customers: AggregateFinder<Customer> & AggregateSaver<Customer>) {
+    super();
+  }
+
+  protected toCommand(input: AwardLoyaltyPointsInput): AwardLoyaltyPointsCommand {
+    return ValueObjects.build({
+      customerId: () => new CustomerId(input.customerId),
+      orderId: () => new OrderId(input.orderId),
+    });
+  }
+
+  protected async handle(command: AwardLoyaltyPointsCommand): Promise<void> {
+    const customer = await this.customers.findById(command.customerId);
+    if (customer === null) {
+      return;
+    }
+    customer.awardPointsFor(command.orderId);
+    await this.customers.save(customer);
+  }
+}
+
+@ListensTo(OrderPlaced, { consumer: 'award-loyalty-points-on-order-placed' })
+class AwardLoyaltyPointsOnOrderPlaced extends EventListener<OrderPlaced> {
+  constructor(private readonly awardLoyaltyPoints: AwardLoyaltyPoints) {
+    super();
+  }
+
+  async handle(event: OrderPlaced): Promise<void> {
+    await this.awardLoyaltyPoints.execute({
+      customerId: event.customerId,
+      orderId: event.aggregateId,
+    });
+  }
+}
+```
+
+Test de la corrección, con los repositorios en memoria del proyecto (`InMemoryOrderRepository` e `InMemoryCustomerRepository`, dobles de test en `test/support/` escritos como en `ddd-skills/ddd-repositorios-persistencia/references/tests-repositorios.md`) y los adaptadores en memoria del paquete (`OrderLineData` y `MoneyData` son los tipos del payload de los eventos, en el mismo fichero que `Order`):
+
+```ts
+import { expect } from 'vitest';
+import {
+  DomainEventBus,
+  EventRegistry,
+  FixedClock,
+  InMemoryEventChannel,
+} from '@archi-code/ddd/infrastructure';
+import { ValidationException } from '@archi-code/ddd/exceptions';
+import { InMemoryCustomerRepository } from '../support/in-memory-customer-repository';
+import { InMemoryOrderRepository } from '../support/in-memory-order-repository';
+
+const orders = new InMemoryOrderRepository();
+const customers = new InMemoryCustomerRepository();
+const registry = new EventRegistry<OrderEvent>().register(
+  OrderPlaced,
+  (json) =>
+    new OrderPlaced(
+      json.aggregateId,
+      json.customerId as string,
+      json.lines as OrderLineData[],
+      json.total as MoneyData,
+      json,
+    ),
+);
+const channel = new InMemoryEventChannel();
+const bus = new DomainEventBus<OrderEvent>(channel, registry);
+await bus.subscribe(new AwardLoyaltyPointsOnOrderPlaced(new AwardLoyaltyPoints(customers)));
+const clock = new FixedClock('2026-03-01T09:30:00Z');
+const orderId = '9b2f6c1e-4d3a-4f8b-a1c2-3e4d5f6a7b8c';
+const customerId = '3c1d2e4f-5a6b-4c7d-8e9f-0a1b2c3d4e5f';
+const shippingAddress = { street: 'Calle Mayor 1', city: 'Huelva', country: 'ES' };
+const placeOrder = new PlaceOrder(orders, bus, clock);
+
+await placeOrder.execute({
+  orderId,
+  customerId,
+  lines: [{ sku: 'TORCH-01', quantity: 2, unitPrice: { amount: 850, currency: 'EUR' } }],
+  shippingAddress,
+});
+await expect(
+  placeOrder.execute({
+    orderId: '5d4c3b2a-1f0e-4d9c-8b7a-6f5e4d3c2b1a',
+    customerId,
+    lines: [],
+    shippingAddress,
+  }),
+).rejects.toThrow(ValidationException);
+```
+
+## Plan
+
+* **Fase 0:** tests de caracterización de alta, envío y puntos de fidelidad sobre `InMemoryOrderRepository` e `InMemoryCustomerRepository` (dobles de test del proyecto en `test/support/`), `InMemoryEventChannel` y `FixedClock`.
+* **Fase 1:** borrar `OrderMapper`: la conversión pasa al agregado (`toPrimitives()` y `static fromPrimitives()`, con un test de ida y vuelta) y `MongoOrderRepository` la llama directamente (su constructor recibe solo la `collection`), sustituir `new Date()` por el `Clock` inyectado y `Error` por `DomainException` con código; `HttpErrorMapper` responde 422 a las reglas de negocio. Quitar el `UnitOfWork` de los casos de uso: `MongoOrderRepository` hace atómico cada `save` (una escritura de un documento con condición de versión) y los casos de uso solo reciben roles de repositorio, `EventBus` y `Clock`.
+* **Fase 2:** `OrderStatus`, `OrderLines` (con `OrderLine` y `Money`) como value objects; `addLine` sustituye a los setters; `UpdateOrder` se parte en `AddOrderLine` y el envío pasa a `Shipment` en Almacén.
+* **Fase 3:** `PlaceOrder` guarda solo el pedido; `AwardLoyaltyPointsOnOrderPlaced` ejecuta `AwardLoyaltyPoints` por evento. Para que `OrderPlaced` no se pierda si el proceso cae entre `save` y `publish`, `MongoOrderRepository` escribe el pedido y sus eventos pendientes en el mismo documento (outbox) y un relay los entrega después por el `EventChannel`; los casos de uso no cambian.

package/ddd-skills/ddd-auditoria-refactorizacion/references/lista-comprobacion.md

@@ -0,0 +1,54 @@
+# Lista de comprobación DDD
+
+La columna "Script" indica si `scan_ddd_smells.py` lo detecta (sí / parcial / no). Lo que dice "no" se revisa leyendo el código. En código hecho con `@archi-code/ddd`, cada comprobación nombra la pieza del paquete que la resuelve; recorre además `ddd-skills/archi-code-ddd/what-not-to-do.md`.
+
+## Integración entre contextos
+
+| # | Comprobación | Fuente | Script | Severidad típica |
+|---|---|---|---|---|
+| E1 | ¿Hay un término con varios significados usado en el mismo código (Customer, Product, Order)? | [IDDD cap. 2; Destilado cap. 2] | no | Alta |
+| E2 | ¿Se importan clases de dominio entre contextos (`contexts/sales` importando de `contexts/billing`) fuera de un `shared-kernel/` explícito? | [IDDD cap. 13; Destilado cap. 4] | sí | Alta |
+| E3 | ¿Hay integración por base de datos compartida? | [Destilado cap. 4] | no | Alta |
+| E4 | ¿Las integraciones con sistemas externos pasan por una ACL (puerto del dominio con value objects, adaptador y traductor en `infrastructure/`)? | [Destilado cap. 4] | no | Alta |
+| E5 | ¿Hay cadenas de llamadas síncronas entre servicios dentro de una petición? | [Destilado cap. 4] | no | Alta |
+| E6 | ¿Usuarios y permisos mezclados en el modelo del núcleo? La autorización va en el caso de uso (`NotAllowedException`), no en el agregado | [IDDD cap. 2] | no | Media |
+| E7 | ¿Se envía `event.toJSON()` de un evento de dominio a otro contexto en vez de un contrato publicado y versionado? | [IDDD cap. 13] | no | Alta |
+
+## Arquitectura
+
+| # | Comprobación | Fuente | Script | Severidad |
+|---|---|---|---|---|
+| A1 | ¿El dominio importa frameworks, ORM o clientes HTTP? | [Destilado cap. 2; IDDD cap. 4] | sí | Alta |
+| A2 | ¿Decoradores del ORM en clases de dominio? | [IDDD cap. 6] | sí | Alta |
+| A3 | ¿Controladores con lógica de negocio, que importan repositorios o acceden a la base de datos? Un punto de entrada solo llama a casos de uso y traduce errores con `HttpErrorMapper` | [IDDD cap. 4] | parcial | Alta |
+| A4 | ¿Un caso de uso, servicio de aplicación o el dominio abre o maneja transacciones (`BEGIN`/`COMMIT`, `startSession`, `withTransaction`) o recibe un runner de transacciones o una unidad de trabajo? IDDD pone la transacción en la aplicación [IDDD cap. 12; IDDD cap. 14]; con el paquete se mueve al adaptador del repositorio, que hace atómico cada `save`/`remove` | `[Fuera de los libros: convención de @archi-code/ddd]` | sí | Media |
+| A5 | ¿Un caso de uso devuelve el agregado al controlador o la API expone `toPrimitives()` tal cual? | [IDDD cap. 4; Destilado cap. 4] | no | Media |
+| A6 | ¿Módulos nombrados por patrón (`entities/`, `services/`, `listeners/`)? | [PHP: Modules] | no | Baja |
+| A7 | ¿El dominio lee `process.env` o usa el logger? Solo la raíz de composición lee el entorno | `[Fuera de los libros]` | parcial (solo `process.env`) | Media |
+| A8 | ¿El dominio importa `@archi-code/ddd/application`, `/infrastructure` (por ejemplo `SystemClock`) o un adaptador de `infrastructure/` del proyecto? | `[Fuera de los libros: convención de @archi-code/ddd]` | sí | Alta |
+| A9 | ¿`new Date()` en dominio o aplicación en vez del `Clock` inyectado (`FixedClock` en tests)? | `[Fuera de los libros: convención de @archi-code/ddd]` | sí | Media |
+| A10 | ¿Errores de negocio como `Error` o `ApplicationException` genéricos en vez de `DomainException(message, ['ORD001'])`, o errores traducidos sin `{ cause }`? | `[Fuera de los libros: convención de @archi-code/ddd]` | no | Media |
+
+## Táctico
+
+| # | Comprobación | Fuente | Script | Severidad |
+|---|---|---|---|---|
+| T1 | Prueba de anemia: ¿el agregado solo tiene getters y setters? ¿la lógica está en los casos de uso? | [IDDD cap. 1] | parcial | Alta |
+| T2 | ¿Setters públicos o campos públicos mutables en el dominio? Los cambios son métodos de negocio que llaman a `record()`; los campos son `private _x` con su getter, o `readonly` | [Destilado cap. 5] | sí | Media |
+| T3 | ¿Primitivos en el estado (`private _total: number`, `private _status: string`)? Todo campo de estado es un value object: `Required(XType)` con `@Validations`, `Composite` (`Money`), `EnumType` (`OrderStatus`) o una entidad hija | [IDDD cap. 6] | parcial | Media |
+| T4 | ¿Agregados con colecciones que crecen sin límite? | [IDDD cap. 10] | no | Alta |
+| T5 | ¿Referencias a objetos de otros agregados en vez de identidades (`CustomerId extends IdType<'CustomerId'>`)? | [Destilado cap. 5] | no | Media |
+| T6 | ¿Un caso de uso guarda más de un agregado (o los junta en una misma transacción) sin una excepción de IDDD cap. 10 escrita como decisión? Una escritura atómica por agregado, garantizada por el repositorio | [Destilado cap. 5; IDDD cap. 10] | parcial | Alta |
+| T7 | ¿El repositorio usa la `version` de `AggregateRoot`: guarda con condición de versión, lanza `ConcurrencyException`, guarda `order.toPrimitives()` con `order.version + 1`, llama a `markPersisted()` y carga con `Order.fromPrimitives(row).restoreVersion(row.version)`? | [IDDD cap. 10] | no | Alta si hay concurrencia |
+| T8 | ¿Repositorios de partes internas, una interfaz `Repository` todo en uno, métodos con nombres o reglas de negocio, o lecturas que cargan agregados? Solo `AggregateFinder`/`AggregateSaver`/`AggregateRemover`, y las lecturas son consultas de aplicación | [IDDD cap. 12] | parcial | Media |
+| T9 | ¿Casos de uso con nombres CRUD o técnicos (`UpdateOrder`, `OrderService`), que hacen varias cosas según el input, que llaman a otro caso de uso, o clases `Manager`/`Helper`? | [IDDD cap. 14; Destilado cap. 5] | parcial | Media |
+| T10 | ¿Eventos con nombre en pasado y del lenguaje (`static readonly eventName = 'OrderPlaced'`)? ¿O `OrderUpdated` con todo el estado o con value objects en el payload? | [Destilado cap. 6] | no | Media |
+| T11 | ¿El caso de uso publica con `events.publish(order.pullDomainEvents())` después de `save`, y, si un evento no puede perderse, el repositorio escribe el agregado y sus eventos pendientes en la misma escritura atómica (outbox) que un relay entrega por un `EventChannel`? | [Destilado cap. 6; IDDD cap. 8] | no | Crítica si se pierden |
+| T12 | ¿Los listeners saltan un `eventId` ya procesado? ¿El caso de uso que ejecutan vuelve si el agregado no existe en vez de lanzar? | [Destilado cap. 4] | no | Alta |
+| T13 | ¿Identidad generada temprano (`OrderId.generate()` antes de crear) y pasada a `super(id)`? ¿Algún id opcional (`extends StringType` sin `Required`)? | [IDDD cap. 5] | no | Media |
+| T14 | ¿Tests de aceptación con lenguaje del negocio y datos realistas (el `InMemoryOrderRepository` del proyecto en `test/support/`, `FixedClock`, `channel.sent`)? | [Destilado cap. 2; IDDD cap. 1] | no | Media |
+| T15 | ¿Cada listener se llama `<Action>On<Event>`, tiene `@ListensTo(Event, { consumer: '…' })` con un nombre literal estable y solo traduce el evento a la entrada de un caso de uso? | `[Fuera de los libros: convención de @archi-code/ddd]` | no | Media |
+| T16 | ¿Los value objects se construyen en `toCommand` con `ValueObjects.build` (todos los campos a la vez) y no en `handle` ni en el controlador? | `[Fuera de los libros: convención de @archi-code/ddd]` | no | Media |
+| T17 | ¿Un repositorio genérico compartido por varios agregados, o un repositorio cuyo constructor recibe la clase del agregado o un mapper? Cada repositorio es de un agregado (`MongoOrderRepository` implementa los roles de `Order`), su constructor recibe solo las dependencias de su tecnología (`collection`, `pool`) y llama directamente a `toPrimitives()`/`fromPrimitives()` del agregado | `[Fuera de los libros: convención de @archi-code/ddd]` | no | Media |
+| T18 | ¿La conversión a o desde primitivos está fuera del agregado (un servicio de dominio o un mapper escrito a mano)? Es del agregado: `toPrimitives()` y `static fromPrimitives()`, que el repositorio llama directamente; un test de ida y vuelta por agregado comprueba que no se pierde ningún campo | `[Fuera de los libros: convención de @archi-code/ddd]` | no | Media |
+| T19 | ¿Un repositorio en memoria en `src/`? Es un doble de test del proyecto (`InMemoryOrderRepository`, ver `ddd-skills/ddd-repositorios-persistencia/references/tests-repositorios.md`): se mueve a `test/support/` | `[Fuera de los libros: convención de @archi-code/ddd]` | no | Baja |

package/ddd-skills/ddd-auditoria-refactorizacion/references/plan-migracion.md

@@ -0,0 +1,73 @@
+# Plan de migración incremental
+
+## Fase 0. Red de seguridad
+
+* Tests de caracterización del comportamiento actual en la zona a cambiar: fijan lo que hace hoy, aunque esté mal, para detectar cambios no deseados `[Fuera de los libros]`. Cuando el código ya usa el paquete, se escriben sobre el repositorio en memoria del proyecto (`new InMemoryOrderRepository()`, un doble de test en `test/support/`, ver `ddd-skills/ddd-repositorios-persistencia/references/tests-repositorios.md`) y `FixedClock`, y comprueban lo que transportó el canal (`InMemoryEventChannel.sent`).
+* Reglas automáticas de dependencias (`ddd-skills/ddd-arquitectura/GUIA.md`) en modo aviso, para medir sin bloquear.
+
+## Fase 1. Proteger el código nuevo
+
+* Crea un contexto nuevo y limpio para la parte que se va a tocar, con su propio lenguaje.
+* Conéctalo con el legado mediante una ACL: el modelo nuevo no habla el lenguaje del legado [Destilado cap. 4]. El dominio declara el puerto con value objects; el adaptador de `infrastructure/` lee el legado y traduce:
+
+```ts
+export interface ProductPricing {
+  priceOf(sku: Sku): Promise<Money>;
+}
+```
+
+```ts
+import { InternalErrorException } from '@archi-code/ddd/exceptions';
+
+interface LegacyArticleRow {
+  article_code: string;
+  retail_price: string;
+  currency_code: string | null;
+}
+
+interface LegacyArticles {
+  findByCode(code: string): Promise<LegacyArticleRow>;
+}
+
+export class LegacyProductPricing implements ProductPricing {
+  constructor(private readonly articles: LegacyArticles) {}
+
+  async priceOf(sku: Sku): Promise<Money> {
+    let row: LegacyArticleRow;
+    try {
+      row = await this.articles.findByCode(sku.value);
+    } catch (error) {
+      throw new InternalErrorException('reading the legacy price', { cause: error });
+    }
+    return Money.fromPrimitives({
+      amount: Math.round(Number(row.retail_price.replace(',', '.')) * 100),
+      currency: row.currency_code ?? 'EUR',
+    });
+  }
+}
+```
+
+`Money.fromPrimitives` construye el `Composite` con todas sus reglas: un dato del legado que no las cumple lanza `ValidationException` en la frontera, no dentro del modelo.
+
+La idea de Evans de un **contexto burbuja** (bubble context): un pequeño contexto nuevo, protegido por ACL, que convive con el legado y lo usa como fuente de datos `[Fuera de los libros: Evans, "Getting Started with DDD When Surrounded by Legacy Systems", 2013]`.
+
+## Fase 2. Desplazar funcionalidad
+
+* **Estrangulamiento** (strangler fig): las nuevas funcionalidades y las que se rehacen se sirven desde el contexto nuevo; un enrutador decide qué va a cada lado; el legado se va quedando sin uso `[Fuera de los libros]`.
+* **Rama por abstracción** (branch by abstraction) para sustituir piezas internas: puerto (`ProductPricing`), implementación vieja detrás (`LegacyProductPricing`), implementación nueva detrás, conmutación en la raíz de composición `[Fuera de los libros]`.
+* Si el legado debe seguir viendo los cambios, el contexto nuevo publica sus eventos con `EventBus.publish` y un `EventListener` suscrito con `@ListensTo` ejecuta un caso de uso cuyo puerto escribe en el legado.
+
+## Fase 3. Refactorizar el táctico dentro de cada contexto
+
+Orden recomendado `[Fuera de los libros, basado en dependencias entre reglas]`:
+1. Separar dominio de infraestructura: el agregado expone `static fromPrimitives(PrimitiveTypes<X>)` y `toPrimitives()`, los repositorios implementan `AggregateFinder`/`AggregateSaver`/`AggregateRemover` de un solo agregado en `infrastructure/`, que llaman directamente a `x.toPrimitives()` y a `X.fromPrimitives(row).restoreVersion(row.version)`, con un constructor que recibe solo las dependencias de su tecnología (nunca la clase del agregado ni un mapper), sin decoradores del ORM ni imports de `/infrastructure` en el dominio. Un repositorio genérico compartido por varios agregados se parte en uno por agregado; un servicio de dominio o un mapper escrito a mano que convierte a primitivos se sustituye por `toPrimitives()`/`fromPrimitives()` del agregado, con un test de ida y vuelta por agregado; un repositorio en memoria que esté en `src/` se mueve a `test/support/` `[Fuera de los libros: convención de @archi-code/ddd]`.
+2. Introducir value objects para los primitivos más usados: `Money` como `Composite({ amount: Cents, currency: Currency })`, identificadores `class OrderId extends IdType<'OrderId'>` (la marca hace que no se confundan ids de agregados distintos), estados `extends Required(StatusType)` sobre `EnumType`.
+3. Sustituir setters por métodos de negocio con nombres del lenguaje (`ship`, `addLine`) que comprueban la invariante y llaman a `record()`, moviendo la lógica desde los casos de uso; partir los casos de uso CRUD (`UpdateOrder`) en uno por acción (`ShipOrder`, `AddOrderLine`).
+4. Partir agregados grandes con el procedimiento de `ddd-skills/ddd-agregados/GUIA.md` (plazos de consistencia).
+5. Donde hoy un caso de uso guarda varios agregados: guardar uno, publicar su evento y ejecutar el resto con un listener `<Action>On<Event>`; si el evento no puede perderse, el repositorio lo escribe junto al agregado en la misma escritura atómica (outbox) y un relay lo entrega por un `EventChannel`.
+6. Donde un caso de uso o servicio de aplicación abre o maneja transacciones, o recibe un runner de transacciones o una unidad de trabajo: mover la transacción al adaptador del repositorio, que hace atómico cada `save`/`remove` (una escritura de un documento o, si el agregado ocupa varias tablas, una transacción de base de datos dentro de `save`/`remove`), y dejar el caso de uso con solo roles de repositorio, `EventBus` y `Clock` `[Fuera de los libros: convención de @archi-code/ddd]`.
+7. Separar consultas de lectura (interfaz en `application/`, implementada en `infrastructure/` sobre la base de datos) si los repositorios han crecido en métodos.
+
+## Despliegue
+
+* Cada paso debe poder desplegarse y revertirse por separado.