20. Arquitectura, SOLID, patrones de diseño y Clean Code

20.1 Qué vas a poder hacer al terminar

• Explicar qué decisiones son «arquitectura» en un proyecto Angular + NestJS + MikroORM y cuáles son detalles de implementación que puedes cambiar el martes que viene.
• Medir el acoplamiento y la cohesión de un módulo con criterios objetivos, no por intuición.
• Repartir un caso de uso entre presentación, aplicación, dominio e infraestructura, y detectar de un vistazo cuándo una capa se ha saltado a otra.
• Implementar arquitectura hexagonal real con la inyección de dependencias de Nest: puerto como interfaz, token de inyección, adaptador de MikroORM y adaptador en memoria para los tests.
• Diseñar agregados con las reglas de DDD táctico y traducirlos a entidades de MikroORM sin que el ORM se cuele en el modelo de dominio.
• Aplicar los cinco principios SOLID en este stack, reconocer el síntoma de que se está violando cada uno y argumentar cuándo aplicarlos es contraproducente.
• Identificar los patrones de diseño que ya estás usando sin saberlo (interceptores, providers con useFactory, QueryBuilder, referencias perezosas, RxJS) y aplicarlos de forma deliberada.
• Refactorizar un servicio que viola SRP y DIP con pasos pequeños y seguros, respaldado por tests.
• Escribir un ADR que justifique una decisión técnica y defenderla frente al sesgo de la novedad.
• Argumentar con datos por qué un monolito modular es casi siempre la respuesta correcta antes que los microservicios, y reconocer las señales objetivas de que ha llegado el momento de dividir.

20.2 Qué es la arquitectura de software

La definición más útil y más citada es la de Ralph Johnson, popularizada por Martin Fowler: la arquitectura son las decisiones importantes, y son importantes las decisiones que son difíciles de cambiar. La dificultad de cambio es el criterio, no el tamaño del diagrama.

20.2.1 Atributos de calidad: los requisitos que nadie escribe

Los requisitos funcionales dicen qué hace el sistema; los atributos de calidad dicen cómo de bien lo hace. La arquitectura existe fundamentalmente para satisfacerlos, porque los requisitos funcionales se pueden implementar con cualquier arquitectura, incluso con un único archivo de diez mil líneas.

Estos atributos compiten entre sí. Una capa de abstracción mejora la testabilidad y empeora la inmediatez con la que se lee el código. Una caché mejora el rendimiento y empeora la consistencia. Un diseño distribuido mejora la escalabilidad independiente y empeora la depuración. Arquitectura es elegir explícitamente qué sacrificas, y dejarlo por escrito (20.15).

20.2.2 El coste del acoplamiento

Cuando dos piezas están acopladas, un cambio en una obliga a mirar (y a menudo a tocar) la otra. El coste no crece de forma lineal, sino con el número de caminos entre piezas. Un módulo que conoce a otros tres tiene tres caminos; diez módulos que se conocen todos con todos tienen cuarenta y cinco. Por eso un sistema de tamaño medio con fronteras difusas se vuelve inmanejable de golpe, no poco a poco.

  ACOPLAMIENTO EN MALLA (n·(n-1)/2 caminos)      FRONTERAS EXPLÍCITAS (n-1 caminos)

     ┌───┐   ┌───┐   ┌───┐                          ┌───┐   ┌───┐   ┌───┐
     │ A │───│ B │───│ C │                          │ A │   │ B │   │ C │
     └─┬─┘╲ ╱└─┬─┘╲ ╱└─┬─┘                          └─┬─┘   └─┬─┘   └─┬─┘
       │   ╳    │   ╳   │                             └───────┼───────┘
     ┌─┴─┐╱ ╲┌──┴┐ ╱ ╲┌─┴─┐                              ┌────┴────┐
     │ D │───│ E │───│ F │                              │  núcleo  │
     └───┘   └───┘   └───┘                              │ (puertos)│
                                                        └──────────┘
   15 caminos: cualquier cambio se               5 caminos: el cambio se detiene
   propaga en cualquier dirección                en la frontera

20.2.3 Deuda técnica: deliberada frente a accidental

La metáfora es de Ward Cunningham: escribir código que no encaja del todo con lo que has aprendido del dominio es como pedir un préstamo. Te permite entregar antes, pero pagas intereses en forma de cambios más lentos hasta que devuelves el principal (refactorizando). Fowler amplió la idea con un cuadrante: deliberada o accidental y prudente o temeraria.

                    PRUDENTE                          TEMERARIA
              ┌──────────────────────────┬──────────────────────────┐
   DELIBERADA │ "Salimos con el repo     │ "No hay tiempo para      │
              │  acoplado al ORM y lo    │  diseñar."               │
              │  aislamos en el sprint 4"│  → negligencia, no una   │
              │  → anótalo, ponle fecha  │    decisión              │
              ├──────────────────────────┼──────────────────────────┤
   ACCIDENTAL │ "Ahora que está hecho,   │ "¿Qué es una capa?"      │
              │  sabemos cómo deberíamos │  → falta de formación;   │
              │  haberlo hecho"          │    se arregla aprendiendo│
              │  → refactorización sana  │    no con más frameworks │
              └──────────────────────────┴──────────────────────────┘

La única casilla realmente peligrosa a largo plazo es la temeraria-deliberada, porque se repite en cada entrega y nunca se registra. La deuda prudente-deliberada es una herramienta legítima de gestión: se toma a conciencia, se escribe en el backlog con una fecha y se paga.

20.3 Cohesión y acoplamiento

Son los dos conceptos que Larry Constantine formuló en los años setenta y de los que se derivan, con distinto envoltorio, casi todos los principios modernos. La regla, en una línea: alta cohesión dentro de cada módulo, bajo acoplamiento entre módulos. Cohesión es cuánto tienen que ver entre sí los elementos que viven en la misma unidad: alta cohesión significa que todo lo que hay dentro cambia por la misma razón. Acoplamiento es cuánto necesita saber una unidad sobre otra para funcionar: bajo acoplamiento significa que puedes cambiar el interior de una sin tocar la otra.

20.3.1 Tipos de acoplamiento, del peor al mejor

Cuidado con leer la tabla como un ranking a maximizar. El acoplamiento de mensaje es el más laxo, pero también el que hace más difícil seguir el flujo con el depurador y el que introduce consistencia eventual. La mayoría del código de una aplicación debería vivir cómodamente en «acoplamiento de datos»; los eventos se reservan para cruzar fronteras entre contextos (20.7).

20.3.2 Cohesión, de la peor a la mejor

• Coincidental: las cosas están juntas por casualidad. El archivo utils.ts con formatearFecha, slugify y calcularIVA es el ejemplo canónico.
• Lógica: agrupadas por categoría técnica, no por propósito. Una carpeta services/ con los treinta servicios del sistema: todos son servicios y ninguno tiene nada que ver con el resto.
• Temporal: se ejecutan en el mismo momento. Un onModuleInit que abre la conexión, precalienta la caché y registra métricas.
• Procedimental o comunicacional: comparten secuencia o comparten datos. Aceptable.
• Funcional (la mejor): todos los elementos contribuyen a una única tarea bien definida. PriceCalculator calcula precios; nada más.

20.3.3 Cómo se mide en la práctica

Las métricas clásicas de Robert C. Martin siguen siendo útiles porque se calculan solo con los import: Ca (acoplamiento aferente) es cuántos módulos dependen de este —alto significa mucha responsabilidad—; Ce (eferente) es de cuántos depende él —alto significa fragilidad—; y la inestabilidad I = Ce / (Ca + Ce) resume ambas. Un módulo de dominio debería tender a 0 (estable) y un adaptador de infraestructura a 1. El principio de dependencias estables dice que las flechas deben apuntar hacia lo más estable: si tu dominio importa el adaptador de correo, la tienes al revés. Lo importante es que esto no se queda en teoría, porque se puede verificar automáticamente:

module.exports = {
  forbidden: [
    { name: 'dominio-no-depende-de-infraestructura', severity: 'error',
      comment: 'La regla de dependencia: el dominio no conoce Nest, MikroORM ni HTTP.',
      from: { path: '^src/[^/]+/domain' },
      to:   { path: '^src/[^/]+/(infrastructure|presentation)|^@mikro-orm|^@nestjs' } },
    { name: 'sin-ciclos', severity: 'error', from: {}, to: { circular: true } },
  ],
  options: { tsConfig: { fileName: 'tsconfig.json' } },
};

Una regla así en el pipeline vale más que veinte páginas de documento de arquitectura: convierte una convención opinable en un fallo de compilación. El equivalente en ESLint es eslint-plugin-boundaries o no-restricted-imports con patrones por carpeta; en Angular con Nx, @nx/enforce-module-boundaries.

20.4 Arquitectura en capas

Es la arquitectura por defecto y la que deberías conocer mejor, porque todas las demás (hexagonal, onion, clean) son variaciones sobre la misma idea: agrupar el código por su distancia al mundo exterior y obligar a que las dependencias vayan siempre en la misma dirección.

  ┌─────────────────────────────────────────────────────────────────────┐
  │  PRESENTACIÓN        controladores HTTP, resolvers GraphQL,         │
  │                      gateways WebSocket, componentes de Angular     │
  │                      · traduce protocolo ↔ caso de uso              │
  │                      · NO contiene reglas de negocio                │
  └───────────────────────────────┬─────────────────────────────────────┘
                                  │ depende de ▼
  ┌───────────────────────────────┴─────────────────────────────────────┐
  │  APLICACIÓN          casos de uso, orquestación, transacciones,     │
  │                      autorización, publicación de eventos           │
  │                      · el "guion" de lo que pasa, sin reglas        │
  └───────────────────────────────┬─────────────────────────────────────┘
                                  │ depende de ▼
  ┌───────────────────────────────┴─────────────────────────────────────┐
  │  DOMINIO             entidades, value objects, agregados,           │
  │  (el núcleo)         servicios de dominio, invariantes, puertos     │
  │                      · NO depende de NADA: ni Nest, ni MikroORM,    │
  │                        ni HTTP, ni del reloj del sistema            │
  └─────────────────────────────────────────────────────────────────────┘
                                  ▲ implementa los puertos del dominio
  ┌───────────────────────────────┴─────────────────────────────────────┐
  │  INFRAESTRUCTURA     repositorios MikroORM, cliente de correo,      │
  │                      pasarela de pago, caché Redis, reloj, UUID     │
  └─────────────────────────────────────────────────────────────────────┘

  REGLA DE DEPENDENCIA: las flechas de código fuente apuntan hacia dentro.
  El flujo de EJECUCIÓN va hacia fuera (el caso de uso llama al repositorio),
  pero la DEPENDENCIA DE CÓDIGO no: el caso de uso conoce una interfaz que
  vive en el dominio, no la clase de infraestructura que la implementa.

20.4.1 Qué va exactamente en cada capa

src/
├── tasks/                          # módulo de Nest = frontera del contexto
│   ├── domain/                     # task.entity.ts (agregado con comportamiento), task-status.vo.ts,
│   │                               # task.errors.ts (no HttpException), task.repository.ts (PUERTO)
│   ├── application/                # complete-task.use-case.ts, list-tasks.use-case.ts, dto/
│   ├── infrastructure/             # mikro-task.repository.ts (ADAPTADOR de salida)
│   ├── presentation/               # tasks.controller.ts (ADAPTADOR de entrada), dto/ con class-validator
│   └── tasks.module.ts             # aquí se atan puertos con adaptadores
├── shared/                         # kernel compartido: Result, tipos base, utilidades puras
└── app.module.ts

20.4.2 El mismo caso de uso, mal y bien repartido

Caso de uso: completar una tarea. Reglas: no se puede completar una tarea archivada, no se puede completar dos veces, y al completarla se registra la fecha y se notifica al responsable del proyecto.

@Controller('tasks')
export class TasksController {
  constructor(private readonly em: EntityManager) {}

  @Patch(':id/complete')
  async complete(@Param('id') id: string) {
    // 1. El controlador consulta la base de datos
    const task = await this.em.findOne(Task, { id }, { populate: ['project.owner'] });
    if (!task) throw new NotFoundException();
    // 2. ...y contiene las REGLAS DE NEGOCIO
    if (task.archivedAt !== null) throw new BadRequestException('archivada');
    if (task.status === 'done') throw new BadRequestException('ya completada');
    // 3. ...y muta el estado a mano
    task.status = 'done';
    task.completedAt = new Date();
    task.project.pendingCount -= 1;
    await this.em.flush();
    // 4. ...y habla con un servicio externo
    await this.mailer.send(task.project.owner.email, 'Completada', `${task.title}...`);
    return task;   // 5. ...y devuelve la ENTIDAD, con todo dentro
  }
}

@Controller('tasks')
export class TasksController {
  constructor(private readonly completeTask: CompleteTaskUseCase) {}

  @Patch(':id/complete')
  async complete(
    @Param('id', ParseUUIDPipe) id: string,
    @CurrentUser() user: AuthUser,
  ): Promise<TaskResponseDto> {
    // La presentación solo traduce: HTTP -> caso de uso -> HTTP.
    const task = await this.completeTask.execute({ taskId: id, actorId: user.id });
    return TaskResponseDto.from(task);
  }
}
// ─────────── application/complete-task.use-case.ts ───────────
@Injectable()
export class CompleteTaskUseCase {
  constructor(
    @Inject(TASK_REPOSITORY) private readonly tasks: TaskRepository,
    private readonly uow: UnitOfWorkPort,
    private readonly events: DomainEventPublisher,
    private readonly clock: ClockPort,
  ) {}

  async execute(cmd: CompleteTaskCommand): Promise<Task> {
    return this.uow.transactional(async () => {
      const task = await this.tasks.byId(cmd.taskId);
      if (!task) throw new TaskNotFound(cmd.taskId);
      task.complete(this.clock.now());   // la REGLA vive en el dominio
      await this.tasks.save(task);
      this.events.publishAll(task.pullEvents());
      return task;
    });
  }
}

@Entity()
export class Task {
  @PrimaryKey() id!: string;
  @Property() title!: string;
  @Enum(() => TaskStatus) status: TaskStatus = TaskStatus.Pending;
  @Property({ nullable: true }) completedAt: Date | null = null;
  @Property({ nullable: true }) archivedAt: Date | null = null;
  @ManyToOne(() => Project, { ref: true }) project!: Ref<Project>;
  private events: DomainEvent[] = [];

  /** Invariante de negocio: solo una tarea viva y pendiente puede completarse. */
  complete(now: Date): void {
    if (this.archivedAt !== null) throw new TaskArchived(this.id);   // error de DOMINIO, no HTTP
    if (this.status === TaskStatus.Done) throw new TaskAlreadyCompleted(this.id);
    this.status = TaskStatus.Done;
    this.completedAt = now;                     // el tiempo entra como parámetro
    this.events.push(new TaskCompleted(this.id, this.project.id, now));
  }

  pullEvents(): DomainEvent[] {
    const pending = this.events;
    this.events = [];
    return pending;
  }
}

Fíjate en tres detalles del bloque correcto. Primero, el tiempo se inyecta: complete(now) en lugar de new Date() dentro del método, lo que permite testear el vencimiento sin manipular el reloj del sistema. Segundo, el dominio lanza errores de dominio, no BadRequestException; un filtro de excepciones en la presentación los traduce a códigos HTTP, de modo que el mismo caso de uso sirve para un endpoint REST, un comando de CLI y un consumidor de cola. Tercero, el efecto secundario (el correo) no está en el caso de uso: se emite un evento de dominio y un manejador se encarga, con lo que añadir una notificación push mañana no toca este archivo.

20.5 Arquitectura hexagonal: puertos y adaptadores

Alistair Cockburn la publicó en 2005 con un objetivo muy concreto: «permitir que una aplicación sea manejada indistintamente por usuarios, programas, tests automatizados o scripts, y que se desarrolle y pruebe de forma aislada de sus dispositivos y bases de datos». El hexágono no significa nada (dibujó seis lados para tener sitio donde poner puertos); el nombre técnico es puertos y adaptadores.

        ADAPTADORES DE ENTRADA                        ADAPTADORES DE SALIDA
        (driving / primarios)                          (driven / secundarios)

   ┌──────────────┐                                       ┌────────────────────┐
   │ Controlador  │──┐                                 ┌──│ MikroTaskRepository│
   │    HTTP      │  │                                 │  └────────────────────┘
   └──────────────┘  │    ┌───────────────────────┐    │  ┌────────────────────┐
   ┌──────────────┐  │    │                       │    ├──│ InMemoryTaskRepo   │ (tests)
   │  Consumidor  │──┼───►│    NÚCLEO             │◄───┤  └────────────────────┘
   │   de cola    │  │    │  dominio +            │    │  ┌────────────────────┐
   └──────────────┘  │    │  casos de uso         │    ├──│ SmtpMailer         │
   ┌──────────────┐  │    │                       │    │  └────────────────────┘
   │  Comando CLI │──┤    └───────────────────────┘    │  ┌────────────────────┐
   └──────────────┘  │      ▲                  ▲       └──│ SystemClock        │
   ┌──────────────┐  │      │                  │          └────────────────────┘
   │  Test e2e    │──┘   PUERTO DE          PUERTO DE
   └──────────────┘      ENTRADA            SALIDA
                         (interfaz del      (interfaz que el núcleo
                          caso de uso)       DECLARA y otro implementa)

   Lo esencial: la flecha de dependencia de código SIEMPRE entra al núcleo.
   El núcleo no sabe si al otro lado hay Postgres, un fichero o un array.

20.5.1 Puertos de entrada y de salida

• Puerto de entrada: el contrato de lo que la aplicación sabe hacer. En Nest suele ser directamente la clase del caso de uso (CompleteTaskUseCase). No siempre hace falta una interfaz aquí: la clase concreta ya es un contrato y añadir una interfaz por encima suele ser ceremonia.
• Puerto de salida: el contrato de lo que la aplicación necesita del mundo. Aquí la interfaz sí es imprescindible, porque es lo que invierte la dependencia. Y —detalle importante— lo define el núcleo con su vocabulario, no el proveedor: se llama NotificationSender, no SendGridClient.

20.5.2 Cómo se implementa con la inyección de dependencias de Nest

Aquí aparece la fricción técnica clásica: las interfaces de TypeScript no existen en tiempo de ejecución, y la inyección de Nest se basa en metadatos de tipos emitidos por el compilador. No puedes escribir constructor(private repo: TaskRepository) y esperar que Nest resuelva la interfaz: en el JavaScript generado ese tipo se ha borrado. La solución idiomática son tres piezas: interfaz + token + proveedor.

import { Task } from './task.entity';

/** Puerto de salida. Vive en el dominio y habla su lenguaje: nada de
 *  "findOne", "where" ni "populate". Uno por agregado. */
export interface TaskRepository {
  byId(id: string): Promise<Task | null>;
  pendingOfProject(projectId: string): Promise<Task[]>;
  save(task: Task): Promise<void>;
  remove(task: Task): Promise<void>;
  nextIdentity(): string;
}

/** Token de inyección: el puente entre una interfaz que se borra y el DI que no. */
export const TASK_REPOSITORY = Symbol('TaskRepository');

import { EntityManager } from '@mikro-orm/postgresql';
import { v4 as uuid } from 'uuid';

@Injectable()
export class MikroTaskRepository implements TaskRepository {
  constructor(private readonly em: EntityManager) {}

  byId(id: string): Promise<Task | null> {
    return this.em.findOne(Task, { id });
  }

  pendingOfProject(projectId: string): Promise<Task[]> {
    return this.em.find(Task,
      { project: projectId, status: TaskStatus.Pending, archivedAt: null },
      { orderBy: { dueDate: 'asc' } });
  }

  async save(task: Task): Promise<void> {
    // persist() es idempotente; el flush lo controla la
    // unidad de trabajo del caso de uso.
    this.em.persist(task);
  }

  async remove(task: Task): Promise<void> { this.em.remove(task); }

  nextIdentity(): string { return uuid(); }
}

/** Adaptador en memoria: un "fake", no un mock. Implementa el contrato
 *  de verdad, así que los tests verifican comportamiento, no llamadas. */
export class InMemoryTaskRepository implements TaskRepository {
  private readonly store = new Map<string, Task>();
  private seq = 0;

  async byId(id: string): Promise<Task | null> {
    return this.store.get(id) ?? null;
  }

  async pendingOfProject(projectId: string): Promise<Task[]> {
    return [...this.store.values()].filter(
      (t) => t.project.id === projectId
          && t.status === TaskStatus.Pending
          && t.archivedAt === null,
    );
  }

  async save(task: Task): Promise<void> { this.store.set(task.id, task); }

  async remove(task: Task): Promise<void> { this.store.delete(task.id); }

  nextIdentity(): string { return `task-${++this.seq}`; }
}

@Module({
  imports: [MikroOrmModule.forFeature([Task, Project])],
  controllers: [TasksController],
  providers: [
    CompleteTaskUseCase,
    ListTasksUseCase,
    { provide: TASK_REPOSITORY, useClass: MikroTaskRepository },
    { provide: CLOCK, useClass: SystemClock },
    { provide: NOTIFICATION_SENDER, useClass: SmtpNotificationSender },
  ],
  exports: [CompleteTaskUseCase],
})
export class TasksModule {}

describe('CompleteTaskUseCase', () => {
  const NOW = new Date('2026-03-01T10:00:00Z');
  let repo: InMemoryTaskRepository;
  let useCase: CompleteTaskUseCase;

  beforeEach(() => {
    repo = new InMemoryTaskRepository();
    useCase = new CompleteTaskUseCase(repo, new NoopUnitOfWork(),
      new RecordingEventPublisher(), { now: () => NOW });  // reloj fijo
  });

  it('completa con la fecha del reloj', async () => {
    await repo.save(TaskMother.pending({ id: 't-1' }));
    await useCase.execute({ taskId: 't-1', actorId: 'u-1' });
    const stored = await repo.byId('t-1');
    expect(stored!.status).toBe(TaskStatus.Done);
    expect(stored!.completedAt).toEqual(NOW);
  });

  it('rechaza una tarea archivada', async () => {
    await repo.save(TaskMother.archived({ id: 't-2' }));
    await expect(useCase.execute({ taskId: 't-2', actorId: 'u-1' }))
      .rejects.toBeInstanceOf(TaskArchived);
  });
});
// Sin Postgres, sin contenedor, sin TestingModule: 4 ms por test.

20.6 Clean Architecture, onion y la comparación honesta

Onion Architecture (Jeffrey Palermo, 2008) y Clean Architecture (Robert C. Martin, 2012) son reformulaciones de la misma idea de Cockburn. Las tres comparten el invariante fundamental: las dependencias de código apuntan hacia el núcleo de negocio, y todo lo que sea un detalle reemplazable (base de datos, framework, protocolo, interfaz de usuario) queda fuera.

20.7 Domain-Driven Design táctico

DDD (Eric Evans, 2003) es antes que nada una metodología de comunicación: el código y el negocio deben hablar el mismo idioma. Los patrones tácticos son las herramientas para que ese idioma quepa en clases de TypeScript.

20.7.1 Los bloques de construcción

20.7.2 Diseño de agregados: la parte que más se equivoca

   AGREGADO "Project"                        AGREGADO "Invoice"
  ┌──────────────────────────────┐          ┌────────────────────────────┐
  │  ▄▄▄ Project  (RAÍZ) ▄▄▄     │          │  ▄▄▄ Invoice (RAÍZ) ▄▄▄    │
  │      id, name, ownerId       │          │      id, customerId        │
  │      ┌────────────────────┐  │          │      ┌──────────────────┐  │
  │      │ Task (interna)     │  │          │      │ InvoiceLine      │  │
  │      │ id, title, status  │  │          │      │ concepto, precio │  │
  │      └────────────────────┘  │          │      └──────────────────┘  │
  │   invariante: no más de 500  │          │  invariante: total = Σ     │
  │   tareas activas por proyecto│          │  líneas, y no se toca si   │
  └──────────────┬───────────────┘          │  está emitida              │
                 │                          └─────────────┬──────────────┘
                 │  referencia POR IDENTIDAD (nunca por objeto)
                 └──────────────► customerId: string ◄────┘

  ┌──────────────────────────────────────────────────────────────────────┐
  │ 1 transacción = 1 agregado modificado.                               │
  │ ¿Necesitas cambiar dos? → evento de dominio + consistencia eventual. │
  └──────────────────────────────────────────────────────────────────────┘

Las reglas de diseño de agregados, en el orden en que Vaughn Vernon las formuló: (1) modela invariantes verdaderas dentro de límites de consistencia —si dos datos deben cuadrar siempre, en el mismo instante, van en el mismo agregado; si basta con que cuadren «en unos segundos», no—; (2) diseña agregados pequeños, porque un agregado grande es una unidad de bloqueo grande y dos usuarios que tocan cosas distintas chocan sin motivo; (3) referencia otros agregados por identidad (customerId: string, no customer: Customer), lo que evita cargar medio grafo sin querer y deja la frontera visible; y (4) usa consistencia eventual fuera del límite, coordinando con eventos de dominio.

20.7.3 Value object, fábrica y especificación en TypeScript

@Embeddable()
export class Money {
  @Property({ type: 'int' }) readonly cents!: number;      // enteros: nunca float para dinero
  @Property({ length: 3 })   readonly currency!: string;

  private constructor(cents: number, currency: string) {
    if (!Number.isInteger(cents)) throw new InvalidMoney('céntimos no enteros');
    this.cents = cents;
    this.currency = currency;
  }

  static fromCents(cents: number, currency = 'EUR'): Money { return new Money(cents, currency); }

  add(other: Money): Money {                                // inmutable: devuelve uno nuevo
    if (other.currency !== this.currency) throw new CurrencyMismatch();
    return new Money(this.cents + other.cents, this.currency);
  }

  equals(other: Money): boolean {                           // igualdad por VALOR
    return this.cents === other.cents && this.currency === other.currency;
  }
}

Un value object no es «una clase pequeña»: es la diferencia entre que calcularTotal(precio: number, iva: number) se pueda invocar con los argumentos intercambiados sin que el compilador diga nada, y que calcularTotal(precio: Money, iva: TaxRate) falle en compilación. Es el remedio del primitive obsession.

export class Task {
  // Constructor privado: no se puede crear una Task inválida desde fuera.
  private constructor(id: string, title: string, project: Ref<Project>) {
    this.id = id;
    this.title = title;
    this.project = project;
  }

  /** Fábrica: nombre del negocio + invariantes de creación. */
  static schedule(input: {
    id: string; title: string; project: Ref<Project>; dueDate: Date; now: Date;
  }): Task {
    if (input.title.trim().length < 3) throw new InvalidTaskTitle(input.title);
    if (input.dueDate < input.now) throw new DueDateInThePast(input.dueDate);
    const task = new Task(input.id, input.title.trim(), input.project);
    task.dueDate = input.dueDate;
    task.events.push(new TaskScheduled(task.id, input.dueDate));
    return task;
  }
}

export interface Specification<T> {
  toQuery(): FilterQuery<T>;
  isSatisfiedBy(candidate: T): boolean;
}

export class OverdueTasks implements Specification<Task> {
  constructor(private readonly now: Date) {}
  toQuery(): FilterQuery<Task> {
    return { dueDate: { $lt: this.now }, status: TaskStatus.Pending };
  }
  isSatisfiedBy(t: Task): boolean {
    return t.dueDate !== null && t.dueDate < this.now && t.status === TaskStatus.Pending;
  }
}

export function and<T>(...specs: Specification<T>[]): Specification<T> {
  return {
    toQuery: () => ({ $and: specs.map((s) => s.toQuery()) }) as FilterQuery<T>,
    isSatisfiedBy: (c) => specs.every((s) => s.isSatisfiedBy(c)),
  };
}
// Uso: this.tasks.matching(and(new OfProject(id), new OverdueTasks(now)))

La ventaja de la especificación es que la misma regla sirve para consultar y para validar en memoria: el filtro de la consulta SQL y la comprobación sobre un objeto ya cargado no pueden divergir porque están escritos una sola vez. Su coste es que filtra la sintaxis de MikroORM hacia el dominio con FilterQuery; si eso te molesta, define tu propio árbol de criterios y tradúcelo en el adaptador, a cambio de bastante más código.

20.7.4 Eventos de dominio en Nest

@Injectable()
export class DomainEventPublisher {
  constructor(private readonly emitter: EventEmitter2) {}
  /** Se llama DESPUÉS del commit: si la transacción falla, nadie recibe nada. */
  publishAll(events: readonly DomainEvent[]): void {
    for (const event of events) this.emitter.emit(event.name, event);
  }
}

@Injectable()
export class NotifyOwnerOnTaskCompleted {
  constructor(@Inject(NOTIFICATION_SENDER) private readonly sender: NotificationSender) {}
  @OnEvent('task.completed', { async: true })
  async handle(event: TaskCompleted): Promise<void> {
    await this.sender.send({ to: event.ownerEmail, template: 'task-completed', data: event });
  }
}

20.7.5 DDD estratégico en tres párrafos

• Lenguaje ubicuo: un único vocabulario compartido por negocio y código. Si el equipo comercial dice «presupuesto», la clase se llama Presupuesto o Quote, pero nunca OrderDraftDataV2. Cuando el código y las reuniones usan palabras distintas, cada traducción es una oportunidad de malentendido.
• Contexto delimitado (bounded context): la frontera dentro de la cual una palabra significa exactamente una cosa. «Cliente» en Ventas (con historial de compras y descuentos) y «Cliente» en Soporte (con tickets y SLA) son dos modelos distintos que casualmente comparten nombre. Intentar unificarlos en una clase Customer con cuarenta campos es el origen del big ball of mud. En Nest, un contexto delimitado se corresponde con un módulo de primer nivel.
• Mapa de contextos: cómo se relacionan. Los patrones útiles son shared kernel (código común acordado, úsalo poco), customer/supplier (uno se adapta al otro por acuerdo), conformist (te tragas el modelo ajeno tal cual) y sobre todo la capa anticorrupción: un traductor en tu frontera que convierte el modelo ajeno al tuyo para que su desorden no contamine tu dominio. La capa anticorrupción es, técnicamente, un adaptador (sección 20.9).

20.8 Los cinco principios SOLID

El acrónimo lo popularizó Michael Feathers a partir de los principios que Robert C. Martin publicó desde finales de los noventa. No son leyes: son heurísticas para reducir el coste del cambio. Aplicados con criterio, quitan trabajo; aplicados por dogma, lo multiplican. Cada apartado incluye deliberadamente el matiz de cuándo no vale la pena.

20.8.1 SRP · Principio de responsabilidad única

Definición. «Una clase debe tener una sola razón para cambiar». La formulación que el propio Martin acabó dando es mejor: un módulo debe ser responsable ante un único actor. No se trata de que haga «una sola cosa», sino de que solo un grupo de interesados pueda pedir que cambie. Síntoma: el archivo aparece en pull requests de temas que no tienen nada que ver entre sí; su test necesita mocks de cinco cosas distintas; su nombre contiene «y» o es tan genérico (TaskManager) que no compromete a nada.

@Injectable()
export class TasksService {
  constructor(private em: EntityManager, private mailer: MailerService,
              private stripe: StripeService, private pdf: PdfService) {}

  async complete(id: string, dto: CompleteDto) {
    // (1) validación de formato
    if (!dto.comment || dto.comment.length > 500) throw new BadRequestException('inválido');
    const task = await this.em.findOne(Task, { id });
    // (2) regla de negocio
    if (task!.status === 'done') throw new ConflictException();
    task!.status = 'done';
    await this.em.flush();                                     // (3) persistencia
    await this.mailer.send(task!.owner.email, 'Hecho', '...'); // (4) notificación
    // (5) facturación y (6) generación de documentos
    const invoice = await this.stripe.charge(task!.owner.customerId, 900);
    const buffer = await this.pdf.render('invoice', invoice);
    await this.mailer.sendWithAttachment(task!.owner.email, buffer);
  }
}
// Cambia el formato del PDF    -> se toca este archivo.
// Cambia la pasarela de pago   -> se toca este archivo.
// Cambia una regla de tareas   -> se toca este archivo.
// Tres actores, un solo archivo: conflictos de merge garantizados.

// La validación de formato vive en el DTO de presentación (class-validator).
// La regla de negocio, en la entidad. La facturación y el PDF, en su módulo,
// activados por un evento. Este caso de uso solo orquesta.
@Injectable()
export class CompleteTaskUseCase {
  constructor(
    @Inject(TASK_REPOSITORY) private readonly tasks: TaskRepository,
    private readonly uow: UnitOfWorkPort,
    private readonly events: DomainEventPublisher,
    private readonly clock: ClockPort,
  ) {}

  async execute(cmd: CompleteTaskCommand): Promise<void> {
    const task = await this.uow.transactional(async () => {
      const t = await this.tasks.byId(cmd.taskId);
      if (!t) throw new TaskNotFound(cmd.taskId);
      t.complete(this.clock.now());
      await this.tasks.save(t);
      return t;
    });
    this.events.publishAll(task.pullEvents());
  }
}
// billing/on-task-completed.handler.ts       -> cobra
// notifications/on-task-completed.handler.ts -> avisa
// Cada actor tiene su archivo; los cambios no se pisan.

20.8.2 OCP · Principio de abierto/cerrado

Definición. Bertrand Meyer, 1988: un módulo debe estar abierto a la extensión y cerrado a la modificación. En la práctica moderna: debería poder añadir un comportamiento nuevo añadiendo código, no editando código que ya funciona y está probado. Síntoma: un switch o una cadena de if/else if sobre un tipo, que crece cada vez que aparece un caso nuevo. Peor aún: el mismo switch repetido en tres archivos.

@Injectable()
export class NotificationsService {
  async send(kind: NotificationKind, to: string, payload: unknown) {
    switch (kind) {
      case 'email': return this.mailer.send(to, payload);
      case 'sms':   return this.twilio.messages.create({ to, body: String(payload) });
      case 'push':  return this.fcm.send({ token: to, data: payload as any });
      // Cada canal nuevo (Slack, WhatsApp, webhook...) obliga a editar esta clase
      // (que ya funcionaba), inyectar otra dependencia y re-testear lo anterior.
      default: throw new Error(`canal no soportado: ${kind}`);
    }
  }
}

export interface NotificationChannel {
  readonly kind: NotificationKind;
  send(to: string, payload: NotificationPayload): Promise<void>;
}
export const NOTIFICATION_CHANNELS = Symbol('NotificationChannels');

@Injectable()
export class EmailChannel implements NotificationChannel {
  readonly kind = 'email' as const;
  constructor(private readonly mailer: MailerPort) {}
  async send(to: string, p: NotificationPayload) { await this.mailer.send(to, p); }
}

@Injectable()
export class NotificationsService {
  private readonly byKind: ReadonlyMap<NotificationKind, NotificationChannel>;
  constructor(@Inject(NOTIFICATION_CHANNELS) channels: NotificationChannel[]) {
    this.byKind = new Map(channels.map((c) => [c.kind, c]));
  }
  async send(kind: NotificationKind, to: string, p: NotificationPayload) {
    const channel = this.byKind.get(kind);
    if (!channel) throw new UnsupportedChannel(kind);
    return channel.send(to, p);
  }
}
// notifications.module.ts — añadir un canal es AÑADIR, no editar:
// { provide: NOTIFICATION_CHANNELS, useFactory: (...c: NotificationChannel[]) => c,
//   inject: [EmailChannel, SmsChannel, PushChannel, SlackChannel] }

20.8.3 LSP · Principio de sustitución de Liskov

Definición. Barbara Liskov, 1987: si S es subtipo de T, los objetos de tipo T deben poder sustituirse por objetos de tipo S sin alterar la corrección del programa. En cristiano: una subclase no puede exigir más ni prometer menos que su base. Síntoma: un método heredado que lanza NotImplementedError; un if (x instanceof Y) en el cliente para tratar «el caso raro»; documentación que dice «esta implementación no soporta...».

export class BaseTaskRepository {
  async byId(id: string): Promise<Task | null> { /* ... */ }
  async save(task: Task): Promise<void> { /* ... */ }
  async remove(task: Task): Promise<void> { /* ... */ }
}

/** Repositorio contra una réplica de solo lectura. */
export class ReplicaTaskRepository extends BaseTaskRepository {
  override async save(): Promise<void> {
    throw new Error('la réplica es de solo lectura');   // ROMPE LSP
  }
  override async remove(): Promise<void> {
    throw new Error('la réplica es de solo lectura');
  }
}
// Cualquier caso de uso que reciba un BaseTaskRepository puede explotar en
// runtime según qué instancia le haya inyectado el módulo: el tipo miente.

// Separar el contrato de lectura del de escritura: cada consumidor pide
// exactamente la capacidad que necesita y el compilador impide el error.
export interface TaskReader {
  byId(id: string): Promise<Task | null>;
  matching(spec: Specification<Task>): Promise<Task[]>;
}
export interface TaskWriter {
  save(task: Task): Promise<void>;
  remove(task: Task): Promise<void>;
}
export type TaskRepository = TaskReader & TaskWriter;
export const TASK_READER = Symbol('TaskReader');
export const TASK_REPOSITORY = Symbol('TaskRepository');

// La réplica implementa SOLO TaskReader: no promete lo que no cumple.
export class ReplicaTaskReader implements TaskReader { /* ... */ }

// El caso de uso de listado pide TaskReader; el de completar, TaskRepository.
// No hay ninguna instancia que lance por un método que "no soporta".

20.8.4 ISP · Principio de segregación de interfaces

Definición. Ningún cliente debe verse obligado a depender de métodos que no usa. Una interfaz gorda acopla a todos sus consumidores entre sí: cambiar un método por uno de ellos recompila y re-testea a todos. Síntoma: interfaces llamadas IAlgoService con veinte métodos; mocks de test en los que rellenas quince funciones vacías para probar una.

export interface IUserService {
  findById(id: string): Promise<User | null>;
  findByEmail(email: string): Promise<User | null>;
  create(dto: CreateUserDto): Promise<User>;
  update(id: string, dto: UpdateUserDto): Promise<User>;
  delete(id: string): Promise<void>;
  changePassword(id: string, old: string, next: string): Promise<void>;
  resetPassword(email: string): Promise<void>;
  verifyEmail(token: string): Promise<void>;
  enableTwoFactor(id: string): Promise<string>;
  assignRole(id: string, role: Role): Promise<void>;
  listPermissions(id: string): Promise<Permission[]>;
  exportGdprData(id: string): Promise<Buffer>;
  anonymize(id: string): Promise<void>;
  /* ...y siete más */
}
// Para testear un componente que solo necesita findById,
// hay que construir un doble con VEINTE métodos.

// Interfaces definidas POR EL CONSUMIDOR, con lo que ese consumidor usa.
export interface UserFinder { byId(id: string): Promise<User | null>; }
export interface PasswordChanger {
  change(userId: string, current: string, next: string): Promise<void>;
}
export interface GdprExporter { export(userId: string): Promise<Buffer>; }
export const USER_FINDER = Symbol('UserFinder');

// Una única clase puede implementar varias: la segregación es
// del CONTRATO, no necesariamente de la implementación.
@Injectable()
export class UsersService implements UserFinder, PasswordChanger { /* ... */ }

// Y el test se vuelve trivial:
const finder: UserFinder = { byId: async () => UserMother.active() };

20.8.5 DIP · Principio de inversión de dependencias

Definición. Los módulos de alto nivel no deben depender de los de bajo nivel; ambos deben depender de abstracciones. Y las abstracciones no dependen de los detalles: la interfaz pertenece a quien la usa, no a quien la implementa. Ese matiz es lo que convierte DIP en algo más que «usa interfaces». Síntoma: un archivo de domain/ con import ... from '@mikro-orm/core' o from 'axios'; un test de negocio que necesita base de datos.

import { EntityManager } from '@mikro-orm/postgresql';
import axios from 'axios';

@Injectable()
export class PricingService {
  constructor(private readonly em: EntityManager) {}

  async priceFor(projectId: string): Promise<number> {
    // El servicio de DOMINIO conoce el ORM...
    const project = await this.em.findOne(Project, { id: projectId }, { populate: ['tasks'] });
    // ...hace una llamada HTTP directa...
    const { data } = await axios.get('https://api.fx.example/eur-usd');
    // ...y lee el reloj del sistema.
    const isWeekend = [0, 6].includes(new Date().getDay());
    const base = project!.tasks.count() * 100;
    return base * data.rate * (isWeekend ? 1.2 : 1);
  }
}
// Testear esto exige: base de datos, red y viajar en el tiempo.

// Puertos declarados por el DOMINIO, con su vocabulario:
export interface ExchangeRates { rate(from: Currency, to: Currency): Promise<number>; }
export interface ClockPort { now(): Date; }
export const EXCHANGE_RATES = Symbol('ExchangeRates');
export const CLOCK = Symbol('Clock');

/** Servicio de dominio puro: sin decoradores, sin E/S, sin reloj global. */
export class PricingService {
  constructor(private readonly rates: ExchangeRates, private readonly clock: ClockPort) {}

  async priceFor(project: Project, to: Currency): Promise<Money> {
    const rate = await this.rates.rate('EUR', to);
    const surcharge = isWeekend(this.clock.now()) ? 1.2 : 1;
    const base = project.activeTaskCount() * 100;
    return Money.fromCents(Math.round(base * rate * surcharge), to);
  }
}
// El módulo de Nest ata los cables (infraestructura -> puertos):
// { provide: EXCHANGE_RATES, useClass: HttpExchangeRates },
// { provide: PricingService, useFactory: (r, c) => new PricingService(r, c),
//   inject: [EXCHANGE_RATES, CLOCK] }

20.9 Patrones de diseño aplicados al stack

Los veintitrés patrones del libro de la «banda de los cuatro» (Gamma, Helm, Johnson y Vlissides, 1994) no son inventos: son nombres para soluciones que ya existían. Su valor hoy es sobre todo de vocabulario: decir «esto es una estrategia registrada por token» ahorra un párrafo de explicación. Y conviene interiorizar algo: ya estás usando la mitad de ellos, porque Angular, Nest y MikroORM están construidos con patrones. Reconocerlos es más rentable que implementarlos desde cero.

20.9.1 Creacionales

• Factory Method / Abstract Factory. En Nest, useFactory es literalmente el patrón: una función que decide qué instancia crear según la configuración. Abstract Factory aparece cuando devuelve una familia coherente de objetos (por ejemplo, el par repositorio + unidad de trabajo del mismo motor).
• Builder. El QueryBuilder de MikroORM es un builder de manual: métodos encadenados que acumulan estado y un método terminal (getResult()) que construye el objeto final. Úsalo también para objetos de test complejos (object mother y test data builder).
• Singleton. No lo implementes a mano. En Nest los providers son singleton por defecto dentro de su ámbito; en Angular, providedIn: 'root' hace lo mismo. Un singleton manual (variable de módulo con getInstance()) es un antipatrón con DI: no se puede sustituir en los tests, oculta la dependencia, crea estado global mutable y en Node persiste entre peticiones, con el riesgo de filtrar datos de un usuario a otro.

export interface FileStorage { put(key: string, data: Buffer): Promise<string>; get(key: string): Promise<Buffer>; }
export const FILE_STORAGE = Symbol('FileStorage');

@Module({
  providers: [{
    provide: FILE_STORAGE,
    inject: [ConfigService],
    useFactory: (config: ConfigService): FileStorage => {
      // Una sola decisión, en un solo sitio: el resto de la aplicación
      // solo conoce la interfaz FileStorage.
      switch (config.get('STORAGE_DRIVER')) {
        case 's3':    return new S3Storage(config.get('S3_BUCKET')!);
        case 'local': return new LocalDiskStorage(config.get('UPLOAD_DIR')!);
        default:      return new InMemoryStorage();   // desarrollo y tests
      }
    },
  }],
  exports: [FILE_STORAGE],
})
export class StorageModule {}

20.9.2 Estructurales y de comportamiento

@Injectable({ providedIn: 'root' })
export class DashboardFacade {
  private readonly tasks = inject(TasksApi);
  private readonly projects = inject(ProjectsApi);
  private readonly state = signal<DashboardState>({ loading: true, tasks: [], projects: [] });
  /** El componente solo ve esto: un estado de solo lectura y dos acciones. */
  readonly vm = this.state.asReadonly();
  readonly overdueCount = computed(() => this.vm().tasks.filter((t) => t.overdue).length);

  async load(projectId: string): Promise<void> {
    this.state.update((s) => ({ ...s, loading: true }));
    const [tasks, projects] = await Promise.all([
      firstValueFrom(this.tasks.pending(projectId)),
      firstValueFrom(this.projects.all()),
    ]);
    this.state.set({ loading: false, tasks, projects });
  }
}

La fachada hace que el componente sea tonto y, por tanto, testeable y reutilizable: no sabe cuántas peticiones hacen falta ni en qué orden. El riesgo es que se convierta en el «servicio dios» de la sección 20.11; se evita teniendo una fachada por pantalla o por flujo, no una por aplicación.

En cuanto a los patrones de comportamiento: Strategy ya lo has visto en OCP (precios por tipo de cliente, políticas de envío, políticas de reintento). Observer es RxJS entero, más EventEmitter2 en el backend. Chain of Responsibility es el pipeline de Nest: middleware, guards, interceptores, pipes y filtros, donde cada eslabón decide si sigue o corta. Template Method fija un esqueleto y deja huecos (importadores de ficheros, procesadores de cola), aunque hoy suele ser mejor Strategy por composición, porque Template Method ata a la herencia. Command es la base de CQRS: cada intención es un objeto con su manejador, lo que permite encolar, registrar, reintentar y auditar de forma uniforme. Mediator es el CommandBus de @nestjs/cqrs. Y State es la respuesta a un status: string con if repartidos por seis archivos:

type Transition = Readonly<Record<TaskStatus, readonly TaskStatus[]>>;

/** Una sola tabla de verdad, en lugar de ifs repartidos por seis archivos. */
const ALLOWED: Transition = {
  [TaskStatus.Pending]:    [TaskStatus.InProgress, TaskStatus.Cancelled],
  [TaskStatus.InProgress]: [TaskStatus.Done, TaskStatus.Pending, TaskStatus.Cancelled],
  [TaskStatus.Done]:       [],
  [TaskStatus.Cancelled]:  [TaskStatus.Pending],
};

export function assertTransition(from: TaskStatus, to: TaskStatus): void {
  if (!ALLOWED[from].includes(to)) throw new IllegalTaskTransition(from, to);
}

20.9.3 Tabla resumen

20.10 Patrones de arquitectura de datos

20.10.1 CQRS con y sin bases de datos separadas

CQRS solo dice esto: el modelo con el que escribes no tiene por qué ser el modelo con el que lees. La versión ligera —la que deberías usar— vive en la misma base de datos y en el mismo módulo: para escribir cargas el agregado y ejecutas sus métodos; para leer haces una consulta que devuelve exactamente el DTO que necesita la pantalla, sin hidratar entidades.

@Injectable()
export class TaskBoardQuery {
  constructor(private readonly em: EntityManager) {}
  /** Sin entidades, sin agregados: la forma exacta que pinta la pantalla. */
  async execute(projectId: string): Promise<TaskBoardRow[]> {
    return this.em.getConnection().execute<TaskBoardRow[]>(
      `SELECT t.id, t.title, t.status, u.name AS assignee, COUNT(c.id) AS comments
         FROM task t
         LEFT JOIN "user" u ON u.id = t.assignee_id
         LEFT JOIN comment c ON c.task_id = t.id
        WHERE t.project_id = ? AND t.archived_at IS NULL
        GROUP BY t.id, u.name
        ORDER BY t.due_date ASC NULLS LAST`, [projectId]);
  }
}

La versión pesada (base de datos de lectura separada, alimentada por eventos) multiplica la complejidad operativa e introduce consistencia eventual visible para el usuario: «he guardado y no aparece». Solo se justifica con volúmenes de lectura que no caben en la base de escritura, y llega mucho después de haber agotado índices, caché y réplicas de solo lectura.

20.10.2 Outbox transaccional

  ┌──────────────────── UNA SOLA TRANSACCIÓN ────────────────────┐
  │  UPDATE task SET status='done' ...                           │
  │  INSERT INTO outbox (id, type, payload, published_at) ...    │
  └───────────────────────────┬──────────────────────────────────┘
                              │ commit atómico: o las dos, o ninguna
                              ▼
        ┌───────────────────────────────────────────┐
        │  Trabajador (cron / BullMQ) cada N ms:    │
        │  SELECT ... WHERE published_at IS NULL    │
        │  FOR UPDATE SKIP LOCKED  LIMIT 100        │──► broker / correo / webhook
        │  → publica → UPDATE published_at = now()  │
        └───────────────────────────────────────────┘
   Garantía: "al menos una vez". El consumidor DEBE ser idempotente.

El problema que resuelve es el de la doble escritura: no existe forma de escribir en la base de datos y publicar en un broker de forma atómica. Si publicas antes del commit, puedes anunciar algo que no ocurrió; si publicas después, un fallo del proceso pierde el mensaje. El Outbox convierte las dos escrituras en una sola transacción local y delega la entrega en un proceso aparte.

20.11 Antipatrones

Un antipatrón no es simplemente «código malo»: es una solución que parece razonable, se repite mucho y empeora las cosas. Reconocerlos por su nombre ayuda a discutirlos sin que la conversación suene a ataque personal.

// La entidad es una bolsa de datos...
@Entity()
export class Task {
  @PrimaryKey() id!: string;
  @Property() status!: TaskStatus;
  @Property({ nullable: true }) dueDate: Date | null = null;
}

// ...y esta regla aparece, con variaciones, en cuatro archivos:
@Injectable()
export class TasksService {
  isOverdue(task: Task): boolean {
    return task.status !== TaskStatus.Done
        && task.dueDate !== null
        && task.dueDate < new Date();
  }
}
// reports.service.ts:    t.dueDate && t.dueDate < new Date()   (olvida el estado)
// tasks.controller.ts:   t.dueDate! < today                     (olvida el nulo)
// task-row.component.ts: task.dueDate < Date.now()              (compara mal los tipos)

@Entity()
export class Task {
  @PrimaryKey() id!: string;
  @Enum(() => TaskStatus) private _status: TaskStatus = TaskStatus.Pending;
  @Property({ nullable: true }) private _dueDate: Date | null = null;

  get status(): TaskStatus { return this._status; }
  get dueDate(): Date | null { return this._dueDate; }

  /** La regla vive donde viven los datos. Una vez. */
  isOverdue(now: Date): boolean {
    return this._status !== TaskStatus.Done
        && this._dueDate !== null
        && this._dueDate < now;
  }

  reschedule(newDate: Date, now: Date): void {
    if (this._status === TaskStatus.Done) throw new TaskAlreadyCompleted(this.id);
    if (newDate < now) throw new DueDateInThePast(newDate);
    this._dueDate = newDate;
  }
}
// El servicio, el informe y el componente llaman a task.isOverdue(now).
// Cambiar la definición de "vencida" es cambiar UNA línea.

20.12 Clean Code aplicado

Clean Code (Robert C. Martin, 2008) tiene partes discutibles —el fanatismo por las funciones de tres líneas o la prohibición casi total de comentarios— pero su tesis central es incontestable: el código se lee muchas más veces de las que se escribe, y optimizarlo para la lectura es la mejor inversión disponible.

20.12.1 Nombres y funciones

• Los nombres revelan intención. const d = new Date() no dice nada; const completedAt lo dice todo. Si necesitas un comentario para explicar el nombre, el nombre es malo. La longitud debe ser proporcional al ámbito: una i en un bucle de tres líneas está bien; una propiedad de clase, no.
• Nada de abreviaturas ni de notación húngara. usrRepo, strName o arrTasks añaden ruido: el tipo ya lo dice TypeScript. La I de IUserService es herencia de C# y aquí sobra, entre otras cosas porque una interfaz y una clase son intercambiables estructuralmente.
• Booleanos en forma de afirmación (isArchived, hasPermission, canBeCompleted) y sin negaciones en el nombre: if (!isNotValid) es un acertijo. Funciones con verbo y clases con sustantivo: calculateOverdueFee(), no data(). Un concepto, una palabra: si es fetch, que sea siempre fetch, y no get, retrieve y load.
• Un solo nivel de abstracción por función. El defecto más frecuente es mezclar el «qué» con el «cómo»: tres líneas de orquestación seguidas de veinte de manipulación de cadenas.
• Pocos parámetros. Con más de tres, agrúpalos en un objeto con nombre (execute(cmd: CompleteTaskCommand)): se lee mejor, elimina los errores por orden de argumentos y añadir un campo no rompe a los llamantes. Y nada de banderas booleanas: save(task, true) es ilegible en el punto de llamada y significa que la función hace dos cosas.
• CQS (separación comando-consulta). Una función o cambia el estado y no devuelve nada, o devuelve algo y no cambia nada. Un getUser() que además crea el usuario si no existe es una bomba de relojería. Y usa cláusulas de guarda antes que anidamiento: salir pronto de los casos raros deja el camino feliz en el margen.

20.12.2 Comentarios

20.12.3 Manejo de errores, principios y formato

• Excepciones frente a códigos de error. En TypeScript las excepciones son idiomáticas y no ensucian la firma; su problema es que son invisibles para el compilador. Los tipos de resultado (Result<T, E>) obligan a tratar el error, pero contagian su envoltorio a todo. Recomendación equilibrada: excepciones para lo excepcional (fallo de red, error de programación) y Result en los pocos flujos donde el error es parte normal del caso de uso.
• Errores de dominio, no de HTTP, en el dominio (TaskArchived, no BadRequestException): un ExceptionFilter traduce en la frontera. No te tragues los errores: un catch {} vacío convierte un fallo reproducible en un misterio de tres días. Y conserva la causa: throw new PaymentFailed('...', { cause: err }) mantiene la traza original.
• Ley de Demeter («no hables con extraños»). Un método solo debería llamar a métodos de: sí mismo, sus parámetros, los objetos que crea y sus propios campos. task.project.owner.address.city acopla a cuatro clases y se rompe con cualquier cambio. Excepción sensata: las interfaces fluidas (QueryBuilder, RxJS) devuelven siempre el mismo objeto y no violan nada.
• Principio de mínima sorpresa. Un método llamado findUser no debe crear usuarios; un getter no debe lanzar peticiones HTTP. Cada sorpresa es una futura sesión de depuración. YAGNI: no implementes hoy lo que crees que necesitarás mañana. KISS: entre dos soluciones que funcionan, gana la que se entiende sin explicación.
• DRY, con matices. El principio original de Hunt y Thomas habla de conocimiento, no de texto. Deduplicar dos fragmentos que casualmente se parecen crea acoplamiento accidental: el día que uno cambia aparece un parámetro booleano en la función común, luego otro, y acabas con un if por llamante. Sandi Metz lo resumió mejor que nadie: «la duplicación es mucho más barata que la abstracción equivocada».
• Formato y estructura. Delega el estilo en Prettier y ESLint con --max-warnings 0 en CI. Un archivo, un concepto, en kebab-case con sufijo de rol (complete-task.use-case.ts). Dentro de la clase: campos estáticos, campos de instancia, constructor, métodos públicos, métodos privados; y la step-down rule, lo que llama antes que lo llamado, para que el archivo se lea de arriba abajo.

@Injectable()
export class ReportsService {
  async generate(projectId: string, type: string, send: boolean, format: number) {
    let r: any = {};
    const p = await this.em.findOne(Project, { id: projectId }, { populate: ['tasks', 'owner'] });
    if (p) {
      if (type == 'monthly') {
        let s = 0;
        for (let i = 0; i < p.tasks.length; i++) {
          if (p.tasks[i].status == 'done'
              && p.tasks[i].completedAt!.getMonth() == new Date().getMonth()) {
            s = s + p.tasks[i].hours * 45;   // 45 = tarifa (¿de dónde sale?)
          }
        }
        r.total = s;
        r.title = 'Informe mensual de ' + p.name;
      } else if (type == 'yearly') { /* casi lo mismo copiado */ }
      if (format == 1) r.body = JSON.stringify(r);
      else if (format == 2) r.body = await this.pdf.render('report', r);
      if (send) await this.mailer.send(p.owner.email, r.title, r.body);
    }
    return r;
  }
}

/** Un nivel de abstracción: se lee como el enunciado del caso de uso. */
@Injectable()
export class GenerateReportUseCase {
  constructor(
    @Inject(PROJECT_REPOSITORY) private readonly projects: ProjectRepository,
    @Inject(REPORT_PERIODS) private readonly periods: Map<ReportPeriod, PeriodPolicy>,
    @Inject(REPORT_RENDERERS) private readonly renderers: Map<ReportFormat, ReportRenderer>,
    private readonly clock: ClockPort,
  ) {}

  async execute(cmd: GenerateReportCommand): Promise<RenderedReport> {
    const project = await this.projects.byId(cmd.projectId);
    if (!project) throw new ProjectNotFound(cmd.projectId);       // guarda temprana

    const policy = this.periods.get(cmd.period) ?? raise(new UnknownPeriod(cmd.period));
    const report = project.billableReport(policy.rangeAt(this.clock.now()));
    return this.renderers.get(cmd.format)!.render(report);        // Strategy por formato
  }
}
// El envío por correo ya no está aquí: lo dispara un evento ReportGenerated.
// La tarifa es un value object del proyecto, no un 45 suelto.
// Las banderas booleanas y el "format: number" han desaparecido del contrato.

20.13 Refactorización

Refactorizar es cambiar la estructura interna del código sin alterar su comportamiento observable (Fowler, 1999). Lo que no es: reescribir desde cero, «limpiar mientras arreglo un bug», ni cambiar la funcionalidad «de paso». Si el comportamiento cambia, no estás refactorizando: estás desarrollando, y el riesgo es otro. Mantenerlos separados —en commits distintos— es lo que permite revisar y revertir con seguridad. La regla del campamento resume el cuándo: deja el código un poco mejor de como lo encontraste; no una reforma integral, sino un nombre mejor, una función extraída, un test que faltaba. El mejor momento es justo antes de añadir una funcionalidad al código que la va a recibir, y justo después de hacerla funcionar. El peor: a dos días de una entrega, en código que va a ser eliminado, o sin tests que respalden el comportamiento actual.

20.14 La testabilidad como criterio de diseño

Hay una heurística que vale por medio capítulo: si cuesta escribir el test, el diseño está mal. El test es el primer cliente del código y, por tanto, el primer indicador honesto de su acoplamiento.

De ahí las tres palancas de diseño que más testabilidad aportan: inyección de dependencias (nada de new de colaboradores dentro de la clase ni de importaciones de singletons), funciones puras para el cálculo (misma entrada, misma salida, sin efectos: se testean con una línea) y límites explícitos con puertos en todo lo que sea E/S. Y el corolario incómodo: el exceso de mocks es un olor de diseño, no una técnica avanzada. Un test lleno de jest.fn() queda verde aunque el sistema real no funcione, porque solo verifica que tu código llama a tus suposiciones. Prefiere fakes con comportamiento real (el repositorio en memoria de 20.5) y reserva los mocks para las fronteras que de verdad no puedes ejecutar.

20.15 Documentar decisiones: los ADR

Un Architecture Decision Record (Michael Nygard, 2011) es un documento corto, numerado e inmutable que registra una decisión, su contexto y sus consecuencias. Se guarda en el repositorio (docs/adr/0007-orm.md) y se revisa como código. Su valor no es burocrático: evita que dentro de dos años alguien deshaga una decisión sin conocer el motivo, y evita la discusión circular en cada incorporación al equipo. Una decisión no se edita: si cambia, se escribe otro ADR que la sustituye.

# ADR 0007 · Usar MikroORM como capa de persistencia

## Estado
Aceptada (2026-02-14). Sustituye a la ADR 0003.

## Contexto
- Dominio con invariantes que queremos expresar en entidades ricas.
- Necesitamos transacciones explícitas y control fino del SQL en los informes.
- Equipo de 6 personas, tres con experiencia previa en Doctrine/Hibernate.
- PostgreSQL 16 ya decidido (ADR 0004).

## Decisión
Adoptamos MikroORM 6 con el patrón Data Mapper y su Unit of Work.

## Alternativas consideradas
- **Prisma**: excelente experiencia de desarrollo y tipado del cliente, pero su modelo es
  Active-Record-like sobre objetos planos: no hay entidades con comportamiento ni Identity Map,
  y el esquema vive en un DSL propio fuera de TypeScript.
- **TypeORM**: adopción amplia, pero Data Mapper y Active Record mezclados e historial de
  inconsistencias en el motor de migraciones.
- **SQL a mano (Kysely)**: máximo control, pero perdemos Unit of Work e Identity Map, que son
  justo lo que sostiene el diseño por agregados.

## Consecuencias
+ Entidades ricas, cambio detectado automáticamente, una transacción por caso de uso.
+ Los tests de dominio no necesitan base de datos (repositorio en memoria).
- Curva de aprendizaje: hay que entender el Identity Map y cuándo hace flush.
- Menos ejemplos en la comunidad que Prisma; documentaremos los patrones internos.
- Riesgo asumido: si el proyecto derivase a lecturas masivas, lo revisaríamos con una ADR nueva.

Los criterios de elección tecnológica, en este orden: encaje con el problema real, madurez y mantenimiento activo, conocimiento del equipo, coste de salida si te equivocas, calidad de la documentación y tamaño de la comunidad. El rendimiento bruto suele estar más abajo de lo que la gente cree, porque casi nunca es el cuello de botella. Y ojo al sesgo de la novedad: la tecnología recién salida tiene un atractivo desproporcionado porque los artículos hablan de sus ventajas y todavía nadie ha escrito sobre sus problemas a los dos años. El antídoto es exigir que el ADR incluya al menos tres inconvenientes concretos de la opción elegida y una vía de salida; si nadie sabe enumerar sus desventajas, es que aún no la conocéis lo suficiente para adoptarla.

20.16 Monolito modular frente a microservicios

Es la decisión más cara de revertir de todo el capítulo y, por tanto, la más arquitectónica. La ley de Conway lo explica: una organización que diseña un sistema producirá un diseño que copia su estructura de comunicación. Si tienes un equipo de ocho personas, tendrás un sistema con las fronteras de un equipo de ocho personas, aunque lo despliegues en veinte contenedores. La «maniobra de Conway inversa» consiste en organizar los equipos como quieres que sea el sistema, no al revés.

  MONOLITO MODULAR                          MICROSERVICIOS
  ┌────────────────────────────────┐        ┌─────────┐  ┌─────────┐  ┌─────────┐
  │ ┌────────┐ ┌────────┐ ┌──────┐ │        │ tasks   │  │ billing │  │ notify  │
  │ │ tasks  │ │billing │ │notify│ │        │ +  DB   │  │ +  DB   │  │ +  DB   │
  │ └────────┘ └────────┘ └──────┘ │        └────┬────┘  └────┬────┘  └────┬────┘
  │   llamadas en proceso, tipadas │             └───red──────┴────red─────┘
  │   1 transacción, 1 despliegue  │        contratos versionados, reintentos,
  │   1 base de datos              │        idempotencia, sagas, trazas
  └────────────────────────────────┘
  Refactor entre módulos: minutos          Refactor entre servicios: semanas
  Depuración: un stack trace               Depuración: correlación entre 5 logs

Señales objetivas de que ha llegado el momento de dividir (hacen falta varias, no una): un módulo tiene necesidades de escalado radicalmente distintas al resto (procesado de vídeo frente a un CRUD); dos equipos se bloquean sistemáticamente en el mismo despliegue; una parte del sistema exige un ciclo de publicación o un cumplimiento normativo diferente; el tiempo de arranque o de CI se ha vuelto insoportable y ya has agotado las opciones sencillas. Y una señal que no lo es: «el monolito está hecho un lío». Un lío repartido en la red sigue siendo un lío, pero ahora con latencia.

20.17 Errores comunes y cómo solucionarlos

20.18 Buenas y malas prácticas

20.19 Preguntas frecuentes

20.20 Ejercicios

@Injectable()
export class SubscriptionsService {
  constructor(private em: EntityManager, private mailer: MailerService, private stripe: StripeService) {}
  async cancel(id: string, reason: string) {
    if (!reason || reason.length < 5) throw new BadRequestException('motivo requerido');
    const sub = await this.em.findOne(Subscription, { id }, { populate: ['user'] });
    if (!sub) throw new NotFoundException();
    if (sub.status === 'cancelled') throw new ConflictException('ya cancelada');
    if (sub.currentPeriodEnd < new Date()) sub.status = 'expired';
    else sub.status = 'cancelled';
    sub.cancelledAt = new Date();
    sub.cancelReason = reason;
    await this.em.flush();
    await this.stripe.subscriptions.del(sub.externalId);
    await this.mailer.send(sub.user.email, 'Suscripción cancelada', reason);
    return sub;
  }
}

// 1. presentation/dto/cancel-subscription.dto.ts — la validación de FORMATO sale del servicio
export class CancelSubscriptionDto { @IsString() @MinLength(5) reason!: string; }

// 2. domain/subscription.entity.ts — la REGLA vive en el agregado
cancel(reason: CancellationReason, now: Date): void {
  if (this.status === SubscriptionStatus.Cancelled) throw new AlreadyCancelled(this.id);
  this.status = this.currentPeriodEnd < now ? SubscriptionStatus.Expired : SubscriptionStatus.Cancelled;
  this.cancelledAt = now;
  this.cancelReason = reason;
  this.events.push(new SubscriptionCancelled(this.id, this.userId, reason, now));
}

// 3. domain/ports.ts — puertos declarados por el dominio (DIP)
export interface SubscriptionRepository {
  byId(id: string): Promise<Subscription | null>; save(s: Subscription): Promise<void>;
}
export interface BillingGateway { cancelSubscription(externalId: string): Promise<void>; }

// 4. application/cancel-subscription.use-case.ts — solo orquesta
@Injectable()
export class CancelSubscriptionUseCase {
  constructor(
    @Inject(SUBSCRIPTION_REPOSITORY) private readonly subs: SubscriptionRepository,
    private readonly uow: UnitOfWorkPort,
    private readonly events: DomainEventPublisher,
    private readonly clock: ClockPort,
  ) {}
  async execute(cmd: CancelSubscriptionCommand): Promise<void> {
    const sub = await this.uow.transactional(async () => {
      const s = await this.subs.byId(cmd.subscriptionId);
      if (!s) throw new SubscriptionNotFound(cmd.subscriptionId);
      s.cancel(CancellationReason.of(cmd.reason), this.clock.now());
      await this.subs.save(s);
      return s;
    });
    this.events.publishAll(sub.pullEvents());   // billing y notificaciones escuchan
  }
}

20.21 Resumen del capítulo

20.22 Recursos adicionales

• Robert C. Martin, Clean Code (2008) — el catálogo de referencia sobre nombres, funciones y olores de código. Léelo con criterio: sus ejemplos en Java envejecen, sus principios no.
• Robert C. Martin, Clean Architecture (2017) — la regla de dependencia explicada con paciencia y una defensa clara de por qué el framework es un detalle.
• Martin Fowler, Patterns of Enterprise Application Architecture (2002) — de aquí salen Data Mapper, Unit of Work, Repository, Active Record e Identity Map, que son literalmente el diseño interno de MikroORM.
• Eric Evans, Domain-Driven Design (2003) — el libro azul, el original. Denso; empieza por las partes II y III.
• Vaughn Vernon, Implementing Domain-Driven Design (2013) — el libro rojo, mucho más práctico, con las reglas de diseño de agregados de la sección 20.7.
• Martin Fowler, Refactoring (2.ª ed., 2018, con ejemplos en JavaScript) — el catálogo de refactorizaciones paso a paso; encaja perfectamente con este stack.
• Michael Feathers, Working Effectively with Legacy Code (2004) — costuras y tests de caracterización: el manual para el código que ya está en producción.
• martinfowler.com · Arquitectura — artículos de referencia sobre monolito modular, microservicios, CQRS y deuda técnica.
• Alistair Cockburn · Hexagonal Architecture — el artículo original de puertos y adaptadores, en palabras de su autor.
• adr.github.io — plantillas y herramientas para Architecture Decision Records.
• Refactoring Guru (en español) — catálogo visual de los patrones GoF con ejemplos en TypeScript.
• NestJS · Custom providers — documentación oficial de tokens, useFactory y useClass: la base técnica de los puertos y adaptadores de este capítulo.