9. NestJS: arquitectura, módulos e inyección de dependencias

// 1) Aplicación HTTP con Express (adaptador por defecto)
const app = await NestFactory.create<NestExpressApplication>(AppModule, {
  logger: ['error', 'warn', 'log'],   // o una instancia de LoggerService, o false
  bufferLogs: true,                   // guarda los logs hasta tener el logger definitivo
  abortOnError: false,                // propaga el error en vez de process.exit(1)
  bodyParser: true,                   // false si quieres montarlo tú con límites propios
  rawBody: true,                      // conserva req.rawBody: firmas de webhooks
  snapshot: process.env.NODE_ENV !== 'production',   // grafo para las Nest DevTools
});

// 2) La misma aplicación sobre Fastify: cambia UNA línea, no los controladores
const fast = await NestFactory.create<NestFastifyApplication>(
  AppModule, new FastifyAdapter({ logger: false, trustProxy: true }));
// 3) Microservicio: sin servidor HTTP, mismo grafo de módulos
const micro = await NestFactory.createMicroservice(AppModule, {
  transport: Transport.TCP, options: { host: '0.0.0.0', port: 3001 } });
// 4) Contexto de aplicación: SOLO el contenedor de DI. Ideal para un comando o un cron,
//    porque obtienes tus servicios ya cableados sin abrir ningún puerto.
const ctx = await NestFactory.createApplicationContext(AppModule, { logger: false });
await ctx.get(InformesService).generarCierreMensual();
await ctx.close();                    // dispara los hooks de destrucción

npm i -g @nestjs/cli          # o sin instalar: npx @nestjs/cli@latest new api
nest --version                # 11.x.x

nest new api-tareas
#  ? Which package manager would you like to use? › npm / yarn / pnpm
#  CREATE api-tareas/src/{main.ts,app.module.ts,app.controller.ts,app.service.ts}
#  CREATE api-tareas/test/app.e2e-spec.ts
#  CREATE api-tareas/{nest-cli.json,tsconfig.json,tsconfig.build.json,eslint.config.mjs}

nest new api --strict                     # tsconfig con strict: true (¡hazlo siempre!)
nest new api --package-manager pnpm       # evita la pregunta interactiva
nest new api --skip-git --skip-install    # plantillas propias o monorepo existente
nest info                                 # versiones de Node y de los paquetes de Nest

nest g resource tareas
#  ? What transport layer do you use? › REST API
#  ? Would you like to generate CRUD entry points? › Yes
#  CREATE src/tareas/tareas.{module,controller,service}.ts + specs
#  CREATE src/tareas/dto/{create,update}-tarea.dto.ts
#  CREATE src/tareas/entities/tarea.entity.ts
#  UPDATE src/app.module.ts            ← el CLI cablea el módulo por ti

nest g s tareas --dry-run       # -d: enseña qué haría, sin escribir nada
nest g co tareas --no-spec      # sin fichero de test
nest g s common/clock --flat    # sin crear subcarpeta con el nombre
nest g mo tareas --skip-import  # NO lo importa en el módulo padre
nest g s tareas -p admin        # --project: en un monorepo, en qué app
nest g s modules/facturacion/impuestos   # la ruta es el ámbito; el último, el nombre

nest start --watch              # -w. Equivale a 'npm run start:dev'
nest start --debug --watch      # inspector en 9229 para depurar con VS Code
nest build                      # tsc por defecto → dist/
nest build -b swc               # --builder swc: ~20x más rápido, SIN chequeo de tipos
nest add @nestjs/swagger        # instala y ejecuta el schematic del paquete
nest g app admin                # 1ª vez: mueve el proyecto a apps/ y activa monorepo
nest g lib shared               # libs/shared con alias "@app/shared" en tsconfig
nest start admin -w             # arranca una app concreta del monorepo

async function bootstrap(): Promise<void> {
  const app = await NestFactory.create(AppModule, { bufferLogs: true });
  // La configuración ya está validada (9.12): si faltaba una variable, no llegamos aquí.
  const config = app.get(ConfigService);

  // 1) Prefijo global. 'exclude' deja fuera lo que no debe llevarlo.
  app.setGlobalPrefix('api', { exclude: ['health', 'metrics'] });
  // 2) Versionado por URI: /api/v1/tareas (ver 9.10.4)
  app.enableVersioning({ type: VersioningType.URI, defaultVersion: '1', prefix: 'v' });
  // 3) Cabeceras de seguridad y compresión. Con Fastify: app.register(fastifyHelmet).
  app.use(helmet());
  app.use(compression());       // con proxy inverso delante, mejor comprimir allí
  // 4) CORS explícito: nunca 'origin: true' en producción (capítulo 12)
  app.enableCors({ origin: config.getOrThrow<string[]>('app.corsOrigins'),
                   credentials: true, maxAge: 86_400 });

  // 5) Validación global de TODA entrada: la mejor relación seguridad/esfuerzo
  app.useGlobalPipes(new ValidationPipe({
    whitelist: true,              // elimina propiedades no declaradas en el DTO
    forbidNonWhitelisted: true,   // y responde 400 si llegan
    transform: true,              // convierte el payload en instancia del DTO
    transformOptions: { enableImplicitConversion: true },  // '3' → 3 en params/query
    disableErrorMessages: config.get('app.env') === 'production',
  }));

  // 6) Filtro global: respuestas de error homogéneas (capítulo 10)
  app.useGlobalFilters(new AllExceptionsFilter(app.get(HttpAdapterHost)));

  // 7) OpenAPI con fábrica PEREZOSA: el documento se construye al pedir /docs
  if (config.get('app.env') !== 'production') {
    const cfg = new DocumentBuilder().setTitle('API de Tareas')
      .setVersion('1.0').addBearerAuth().build();
    SwaggerModule.setup('docs', app, () => SwaggerModule.createDocument(app, cfg),
      { jsonDocumentUrl: 'docs/json' });
  }

  // 8) Sin esto, onModuleDestroy y compañía NO se ejecutan con SIGTERM (9.13)
  app.enableShutdownHooks();
  // 9) 0.0.0.0 porque dentro de un contenedor 'localhost' no es accesible desde fuera
  await app.listen(config.getOrThrow<number>('app.port'), '0.0.0.0');
}
// Sin este catch, un fallo de arranque deja una promesa rechazada y un código de salida engañoso
bootstrap().catch((error) => { console.error(error); process.exit(1); });

@Module({
  imports: [
    // La configuración va PRIMERO: el resto la necesita en su propia inicialización.
    ConfigModule.forRoot({ isGlobal: true, cache: true,
      envFilePath: [`.env.${process.env.NODE_ENV ?? 'development'}`, '.env'],
      load: [appConfig, databaseConfig], validate: validateEnv }),
    DatabaseModule,                             // infraestructura
    AuthModule, UsuariosModule, TareasModule,   // features
  ],
  // Ni controladores ni lógica: el módulo raíz es un ÍNDICE, no un cajón de sastre. El
  // interceptor global va como provider para que SÍ pueda inyectar dependencias y SÍ se
  // aplique en los tests de integración.
  providers: [{ provide: APP_INTERCEPTOR, useClass: LoggingInterceptor }],
})
export class AppModule {}

@Module({
  // 1) imports: OTROS MÓDULOS (o módulos dinámicos) cuyos exports quiero usar.
  //    Nunca providers ni controladores: es el error de novato número uno.
  imports: [UsuariosModule, DatabaseModule],
  // 2) controllers: los que Nest debe instanciar y ENRUTAR. Nunca se exportan.
  controllers: [TareasController],
  // 3) providers: todo lo instanciable por el contenedor DENTRO de este módulo.
  providers: [TareasService, TareasPolicy, TareasMapper],
  // 4) exports: el subconjunto que podrán inyectar los módulos que me importen.
  //    Lo que no está aquí es PRIVADO del módulo.
  exports: [TareasService],
})
export class TareasModule {}

// --- notifications.types.ts ---
export const NOTIF_OPTS = Symbol('NOTIF_OPTS');       // token propio: sin colisiones
export interface NotifOptions {
  proveedor: 'email' | 'sms'; remitente: string; apiKey: string; reintentos?: number;
}
export interface NotifAsyncOptions {
  imports?: ModuleMetadata['imports'];      // para que la factoría pueda inyectar
  inject?: any[]; isGlobal?: boolean;
  useFactory: (...a: any[]) => Promise<NotifOptions> | NotifOptions;
}

// --- notifications.module.ts ---
@Module({})                          // vacío: los metadatos los devuelven los estáticos
export class NotificationsModule {
  static forRoot(o: NotifOptions): DynamicModule {
    return this.armar([{ provide: NOTIF_OPTS, useValue: o }]);
  }
  static forRootAsync(a: NotifAsyncOptions): DynamicModule {
    return this.armar(
      [{ provide: NOTIF_OPTS, useFactory: a.useFactory, inject: a.inject ?? [] }],
      a.imports, a.isGlobal);
  }
  /** Registro de un canal concreto: el equivalente a forFeature. */
  static forFeature(canal: string): DynamicModule {
    const token = `CANAL_${canal.toUpperCase()}`;
    return { module: NotificationsModule, exports: [token],
             providers: [{ provide: token, inject: [NotificationsService],
                           useFactory: (s: NotificationsService) => s.canal(canal) }] };
  }
  // Punto ÚNICO donde se declara la estructura: si mañana añades un provider, las dos
  // variantes lo heredan. Evitar esa duplicación es la mitad del valor del patrón.
  private static armar(opciones: Provider[], imports: ModuleMetadata['imports'] = [],
                       global = false): DynamicModule {
    return {
      module: NotificationsModule,     // OBLIGATORIO: la clase anfitriona
      global, imports,                 // 'global' se decide aquí, en tiempo de ejecución
      // El sender concreto se elige en el CABLEADO; el servicio solo conoce el token, y
      // declarar 'inject' hace que el contenedor garantice el orden de creación.
      providers: [...opciones, NotificationsService,
        { provide: 'SENDER', inject: [NOTIF_OPTS],
          useFactory: (o: NotifOptions) =>
            o.proveedor === 'email' ? new EmailSender(o) : new SmsSender(o) }],
      exports: [NotificationsService],
    };
  }
}

// --- notifications.service.ts: las opciones se inyectan como cualquier provider ---
@Injectable()
export class NotificationsService {
  constructor(@Inject(NOTIF_OPTS) private readonly opts: NotifOptions,
              @Inject('SENDER') private readonly sender: Sender) {}
}

// --- app.module.ts: las tres formas de consumirlo ---
@Module({ imports: [
  // (a) Síncrono: valores conocidos en tiempo de compilación.
  NotificationsModule.forRoot({ proveedor: 'email', remitente: 'no-reply@ejemplo.es',
                                apiKey: 'clave-dev', reintentos: 3 }),
  // (b) Asíncrono con inyección: lo habitual en producción, porque la apiKey viene de la
  //     configuración VALIDADA y no de un literal en el código.
  NotificationsModule.forRootAsync({ inject: [ConfigService],
    useFactory: (c: ConfigService) => ({
      proveedor: c.getOrThrow<'email' | 'sms'>('notif.proveedor'),
      remitente: c.getOrThrow<string>('notif.remitente'),
      apiKey: c.getOrThrow<string>('notif.apiKey') }) }),
] })
export class AppModule {}
// (c) En un módulo de feature: NotificationsModule.forFeature('facturacion')

// ---------- (1) PARCHE: forwardRef en los DOS lados ----------
@Module({ imports: [forwardRef(() => UsuariosModule)],
          providers: [TareasService], exports: [TareasService] })
export class TareasModule {}

@Injectable()
export class TareasService {                    // ciclo entre providers, no entre módulos
  constructor(@Inject(forwardRef(() => UsuariosService))
              private readonly usuarios: UsuariosService) {}
}

// ---------- (2) APLAZAR LA RESOLUCIÓN: ModuleRef ----------
@Injectable()
export class TareasService {
  private usuarios!: UsuariosService;
  constructor(private readonly moduleRef: ModuleRef) {}
  onModuleInit(): void {   // en el constructor no se pide nada: no hay ciclo que resolver
    this.usuarios = this.moduleRef.get(UsuariosService, { strict: false });
  }
}

// ---------- (3) SOLUCIÓN REAL: extraer un tercer módulo ----------
// Casi siempre el ciclo revela una TERCERA responsabilidad escondida. "Cuando se completa
// una tarea, notificar al usuario" no pertenece a Tareas ni a Usuarios: pertenece a
// Notificaciones, que depende de los dos. Alternativa igual de válida: que uno publique
// un evento de dominio en lugar de llamar directamente al otro.
@Module({ imports: [TareasModule, UsuariosModule], providers: [NotificacionesService] })
export class NotificacionesModule {}
// Tareas y Usuarios dejan de conocerse y el grafo vuelve a ser acíclico.

// ---------- Lo que escribes ----------
@Injectable()
export class TareasService {
  constructor(
    private readonly usuarios: UsuariosService,
    @Inject(TAREAS_REPO) private readonly repo: TareasRepository,
    @Optional() @Inject('METRICAS') private readonly metricas?: Metricas,
  ) {}
}

// ---------- Lo que el compilador emite (simplificado) ----------
TareasService = __decorate([Injectable(), __param(1, Inject(TAREAS_REPO)),
  __param(2, Optional()), __param(2, Inject('METRICAS')),
  __metadata('design:paramtypes', [UsuariosService, Object, Object]),   // ← la clave
], TareasService);

// ---------- Cómo lo lee el Injector ----------
Reflect.getMetadata('design:paramtypes', TareasService);  // [UsuariosService, Object, Object]
// Regla: para cada posición, si hay @Inject se usa ese token; si no, la CLASE del tipo. Las
// posiciones 1 y 2 son 'Object' porque una interfaz o un tipo no-clase se borra a 'Object':
// sin @Inject serían IRRESOLUBLES.

export const PASARELA_PAGO = Symbol('PASARELA_PAGO');   // Symbol para lo propio
export const REDIS = 'REDIS_CLIENT';                    // string si quieres nombre legible

const providers: Provider[] = [
  TareasService,                                                      // clase estándar
  { provide: PASARELA_PAGO,                                 // useClass: según el entorno
    useClass: process.env.NODE_ENV === 'production' ? StripeGateway : PasarelaFalsa },
  { provide: 'RELOJ', useValue: { ahora: () => new Date() } },             // useValue
  { provide: 'TARIFAS',                                       // useFactory con inject
    useFactory: (c: ConfigService, r: TarifasRepository) =>
      new CalculadoraTarifas(c.getOrThrow('iva'), r),
    inject: [ConfigService, TarifasRepository] },              // ← MISMO ORDEN, siempre
  { provide: REDIS,                                             // provider ASÍNCRONO:
    // Nest ESPERA a que la promesa resuelva antes de dar la app por iniciada, así que
    // la conexión existe con seguridad antes de la primera petición.
    useFactory: async (c: ConfigService) => {
      const cliente = createClient({ url: c.getOrThrow<string>('redis.url') });
      await cliente.connect();
      return cliente;
    }, inject: [ConfigService] },
  { provide: 'LoggerAntiguo', useExisting: Logger },           // ALIAS del mismo objeto
];

@Injectable()                                     // DEFAULT implícito: singleton
export class TarifasService {}

@Injectable({ scope: Scope.TRANSIENT })           // una instancia por consumidor
export class ContextoLogger { private prefijo = ''; }
@Injectable({ scope: Scope.REQUEST })             // una instancia por petición
export class ContextoPeticion {
  readonly tenantId: string;
  constructor(@Inject(REQUEST) req: Request) {    // REQUEST viene de @nestjs/core
    this.tenantId = String(req.headers['x-tenant-id'] ?? 'publico');
  }
}

@Controller({ path: 'tareas', scope: Scope.REQUEST })   // los controladores también
export class TareasController {}
// Providers DURABLES: multi-tenencia sin pagar el coste por petición. Con una
// ContextIdStrategy propia, Nest reutiliza el subárbol de cada tenant en vez de recrearlo.
@Injectable({ scope: Scope.REQUEST, durable: true })
export class ConexionTenant {}

// EL «BUBBLING»: el scope REQUEST SUBE por la cadena de inyección. Si AuditoriaService es
// REQUEST, TareasService y TareasController pasan a serlo también: con 1.000 peticiones por
// segundo, 3.000 objetos nuevos por segundo en lugar de 3 en total, más presión del
// recolector y más latencia. TRANSIENT, en cambio, no contagia hacia arriba.

@Injectable()
export class ExportadorService {
  constructor(private readonly moduleRef: ModuleRef) {}
  // (1) get: selección dinámica de estrategia. Alternativa al 'switch' con 'new', porque
  //     el objeto viene del contenedor con sus propias dependencias ya resueltas.
  async exportar(formato: 'csv' | 'xlsx' | 'pdf', datos: Tarea[]) {
    const tokens = { csv: CsvExporter, xlsx: XlsxExporter, pdf: PdfExporter };
    return this.moduleRef.get(tokens[formato], { strict: false }).generar(datos);
  }
  // (2) resolve: un provider con scope fuera de una petición HTTP (consumidor de cola).
  async procesarTrabajo(tenantId: string) {
    const contextId = ContextIdFactory.create();
    // 'request' sintético para que los providers que inyectan REQUEST encuentren algo:
    this.moduleRef.registerRequestByContextId({ tenantId }, contextId);
    const a = await this.moduleRef.resolve(ConexionTenant, contextId);
    const b = await this.moduleRef.resolve(ConexionTenant, contextId);
    return a === b;                     // true: mismo contextId → misma instancia
  }
  // (3) create: instanciar una clase que NO es provider, con DI completa.
  async ejecutarComando(nombre: string) {
    const Clase = this.registro.buscar(nombre);            // Type<Comando>
    return (await this.moduleRef.create(Clase)).ejecutar();
  }
}

@Controller('tareas')                    // → /api/v1/tareas con prefijo y versión globales
export class TareasController {
  @Get()                  listar() {}              // GET     /tareas
  @Get('vencidas')        vencidas() {}            // GET     /tareas/vencidas
  @Get(':id')             detalle() {}             // GET     /tareas/42
  @Get(':id/comentarios') comentarios() {}         // GET     /tareas/42/comentarios
  @Post()                 crear() {}               // POST    /tareas → 201 por defecto
  @Put(':id')             reemplazar() {}          // PUT     /tareas/42
  @Patch(':id')           actualizar() {}          // PATCH   /tareas/42
  @Delete(':id')          eliminar() {}            // DELETE  /tareas/42
  @Head(':id')            cabecera() {}            // HEAD    /tareas/42
  @Options()              opciones() {}            // OPTIONS /tareas
  @All('proxy/*splat')    todo() {}                // cualquier verbo
}

@Controller({                    // forma con objeto: todas las opciones a la vez
  path: 'tareas', version: '2',  // 'version' sobrescribe la versión por defecto
  host: ':cuenta.ejemplo.es',    // enrutado por SUBDOMINIO (soporte según adaptador)
  scope: Scope.DEFAULT,          // rara vez conviene cambiarlo
})
export class TareasV2Controller {
  @Get() listar(@HostParam('cuenta') cuenta: string) { return this.svc.de(cuenta); }
}

@Controller(['tareas', 'todos'])   // varios prefijos: útil en migraciones de rutas
export class TareasCompatController {}

@Delete(':id')
@HttpCode(HttpStatus.NO_CONTENT)                  // DELETE sin cuerpo → 204 explícito
async eliminar(@Param('id') id: string): Promise<void> { await this.svc.eliminar(id); }

@Get('legacy') @Redirect('/api/v1/tareas', 301)   // redirección estática
legacy() {}

@Get('ir')                                        // devolver { url, statusCode }
redirigir(@Query('a') a: string) {                // SOBRESCRIBE @Redirect en runtime
  return { url: `/api/v1/tareas/${a}`, statusCode: 302 };
}

// Nest resuelve promesas Y observables. En una respuesta HTTP normal, de un observable
// con varios valores solo se emite el ÚLTIMO; para varios valores hace falta SSE.
@Get('promesa')    conPromesa(): Promise<Tarea[]> { return this.svc.listar(); }
@Get('observable') conObservable(): Observable<Tarea[]> { return from(this.svc.listar()); }
@Sse('eventos')    eventos(): Observable<MessageEvent> {
  return interval(1000).pipe(map((n) => ({ data: { tick: n } })));
}

// main.ts — elige UNA estrategia para toda la aplicación
app.enableVersioning({ type: VersioningType.URI, defaultVersion: '1' });
// HEADER:     { type: VersioningType.HEADER, header: 'X-API-Version' }
// MEDIA_TYPE: { type: VersioningType.MEDIA_TYPE, key: 'v=' }
// CUSTOM:     { type: VersioningType.CUSTOM, extractor: (req) => ... }

@Controller({ path: 'tareas', version: '2' })     // versión por controlador
export class TareasV2Controller {}

@Controller('tareas')
export class TareasController {
  @Get(':id') @Version(['1', '2']) detalle() {}    // un handler para dos versiones
  @Post()     @Version('2')        crearV2() {}    // solo v2
}
// health, métricas y webhooks NUNCA se versionan:
@Controller({ path: 'health', version: VERSION_NEUTRAL })
export class HealthController {}

// --- app.module.ts ---
ConfigModule.forRoot({
  isGlobal: true,          // se registra como @Global: no hay que importarlo en cada módulo
  cache: true,             // memoiza los accesos a process.env (recomendado en producción)
  expandVariables: true,   // permite ${OTRA_VAR} dentro del .env
  envFilePath: ['.env.local', `.env.${process.env.NODE_ENV}`, '.env'],  // por prioridad
  ignoreEnvFile: process.env.NODE_ENV === 'production',  // en prod, variables del entorno
  load: [appConfig, databaseConfig, pagosConfig],        // configuración por namespaces
  validate: validateEnv,   // validación propia (Zod). Alternativa: validationSchema (Joi)
});

// --- OPCIÓN A: Joi. En forRoot: validationSchema: envSchema,
//     validationOptions: { allowUnknown: true, abortEarly: false }
export const envSchema = Joi.object({
  NODE_ENV: Joi.string().valid('development', 'test', 'production').default('development'),
  PORT: Joi.number().port().default(3000),
  DATABASE_URL: Joi.string().uri().required(),
  JWT_SECRET: Joi.string().min(32).required(),        // longitud real, no simbólica
  STRIPE_KEY: Joi.string().pattern(/^sk_/).required(),
});

// --- OPCIÓN B: Zod (mismo resultado, y el tipo sale del esquema) ---
const esquema = z.object({
  NODE_ENV: z.enum(['development', 'test', 'production']).default('development'),
  PORT: z.coerce.number().int().positive().default(3000),    // coerce: '3000' → 3000
  DATABASE_URL: z.string().url(),
  JWT_SECRET: z.string().min(32),
  STRIPE_KEY: z.string().startsWith('sk_'),
});
export type Env = z.infer<typeof esquema>;               // DRY: una sola definición

export function validateEnv(config: Record<string, unknown>): Env {
  const r = esquema.safeParse(config);
  // Fallar aquí es el objetivo: el proceso muere ANTES de escuchar en el puerto, con la
  // lista completa de variables mal puestas en el log de arranque.
  if (!r.success) throw new Error(`Configuración inválida: ${r.error.message}`);
  return r.data;
}

// --- Lectura puntual ---
const puerto = config.get<number>('app.port', 3000);    // con valor por defecto
const url = config.getOrThrow<string>('database.url');  // lanza si falta: preferible

@Injectable()
export class ColaConsumer implements OnApplicationBootstrap, BeforeApplicationShutdown {
  private enCurso = 0;
  private aceptando = true;
  onApplicationBootstrap() { this.suscribirse(); }   // todo el grafo está listo
  async beforeApplicationShutdown(signal?: string) {
    this.aceptando = false;                           // 1) no coger trabajo nuevo
    this.logger.log(`Apagando por ${signal}; ${this.enCurso} trabajos en curso`);
    const limite = Date.now() + 20_000;                // 2) esperar a los que quedan, con
    while (this.enCurso > 0 && Date.now() < limite) {  //    un tope por debajo del
      await new Promise((r) => setTimeout(r, 200));     //    terminationGracePeriodSeconds
    }
  }
}

// main.ts: sin esta línea NINGUNO de los hooks de destrucción se ejecuta con SIGTERM. Nest
// registra escuchadores de señales del proceso, y ese coste mínimo de memoria es la razón
// de que no esté activado por defecto.
app.enableShutdownHooks();

// --- main.ts ---
const config = new DocumentBuilder()
  .setTitle('API de Tareas').setDescription('API del manual full-stack').setVersion('1.0')
  .addTag('tareas', 'Gestión de tareas')
  .addBearerAuth()                                       // esquema de seguridad JWT
  .addServer('https://api.ejemplo.es', 'Producción')
  .build();
// Fábrica perezosa: el documento se construye al pedir /docs, no en el arranque.
SwaggerModule.setup('docs', app, () => SwaggerModule.createDocument(app, config),
  { jsonDocumentUrl: 'docs/json' });   // el JSON queda en /docs/json (por defecto /docs-json)

// --- dto/create-tarea.dto.ts ---
export class CreateTareaDto {
  @ApiProperty({ example: 'Revisar el informe', minLength: 3, maxLength: 120 })
  @IsString() @Length(3, 120)
  titulo!: string;

  @ApiPropertyOptional({ enum: Prioridad, default: Prioridad.MEDIA })
  @IsEnum(Prioridad) @IsOptional()
  prioridad?: Prioridad;
}

// --- tareas.controller.ts ---
@ApiTags('tareas') @ApiBearerAuth()
@Controller('tareas')
export class TareasController {
  @Post()
  @ApiOperation({ summary: 'Crea una tarea' })
  @ApiCreatedResponse({ type: TareaResponseDto })
  @ApiBadRequestResponse({ description: 'Datos inválidos' })
  @ApiConflictResponse({ description: 'Ya existe una tarea con ese título' })
  crear(@Body() dto: CreateTareaDto) { return this.svc.crear(dto); }
}

// --- nest-cli.json: el plugin evita repetir @ApiProperty en cada campo ---
{ "compilerOptions": { "plugins": [{ "name": "@nestjs/swagger", "options": {
  "classValidatorShim": true,     // deriva las reglas de class-validator al esquema
  "introspectComments": true,     // usa los comentarios /** */ como 'description'
  "dtoFileNameSuffix": [".dto.ts", ".entity.ts"] } }] } }
// Con el plugin, tipo, opcionalidad y ejemplo se infieren del TypeScript: solo escribes
// @ApiProperty para añadir lo que el compilador no puede saber.

# 1) Exportar el esquema (en CI, o con un script que arranca la app y lo escribe)
curl -s http://localhost:3000/docs/json > openapi.json

# 2a) Cliente con servicios de Angular inyectables sobre HttpClient
npx @openapitools/openapi-generator-cli generate -i openapi.json \
    -g typescript-angular -o src/app/api
npx ng-openapi-gen --input openapi.json --output src/app/api   # 2b) alternativa Angular
npx openapi-typescript openapi.json -o src/app/api/schema.d.ts # 2c) solo los tipos

# 3) Regenera en CI y falla si hay diferencias sin cometer: así el contrato entre
#    backend y frontend no puede desincronizarse sin que alguien se entere.

const app = await NestFactory.create<NestFastifyApplication>(
  AppModule, new FastifyAdapter({ trustProxy: true, bodyLimit: 1_048_576 }));

await app.register(fastifyHelmet);        // los plugins se REGISTRAN, no se usan con use()
await app.register(fastifyCompress, { encodings: ['gzip', 'br'] });

await app.listen(3000, '0.0.0.0');        // dentro de un contenedor, siempre 0.0.0.0