# Convenciones del proyecto ## Idioma y naming - Código e identificadores en inglés; comentarios, TSDoc y documentación en castellano. - Ficheros y directorios en `kebab-case`. - Clases, tipos e interfaces en `PascalCase`; variables, funciones y métodos en `camelCase`. - `UPPER_SNAKE_CASE` solo para constantes globales reales. - Mantener el prefijo `I` para interfaces cuando el área existente lo use. Las convenciones existentes del área prevalecen sobre introducir una variación aislada. ## Principios de diseño Aplicar pragmáticamente SOLID, Clean Code, DRY, KISS, YAGNI, SSOT, Fail Fast, programación defensiva, inmutabilidad cuando resulte adecuada, idempotencia, menor privilegio y observabilidad en APIs y servicios. Son criterios de diseño, no motivos por sí solos para refactorizar código ajeno ni crear abstracciones prematuras; prevalecen los patrones existentes adecuados y el contexto. ```text claridad y explicitud > abstracción prematura ``` ## TypeScript Preservar la seguridad de tipos. Usar `import type` para símbolos utilizados exclusivamente como tipos y mantenerlos en la cabecera; no usar imports runtime innecesarios ni referencias inline salvo en `.d.ts`, module augmentation, código generado o casos técnicamente justificados. Evitar `any`; usar `unknown` cuando el tipo no se conozca. Las assertions y non-null assertions solo proceden con una garantía verificable que TypeScript no pueda inferir. Preferir tipos semánticos, unions o enums existentes y `switch` exhaustivos; no añadir `default` si ocultaría casos comprobables. No duplicar tipos derivados de schemas Zod, ni usar `Partial` cuando el contrato modele la opcionalidad explícitamente. Mantener inmutabilidad cuando no sea necesaria la mutación. Al cambiar DTOs, schemas, APIs, eventos, modelos persistidos o tipos compartidos, revisar todos sus productores y consumidores. ## Comentarios y TSDoc Los comentarios explican decisiones, riesgos, contratos, efectos laterales, invariantes o limitaciones no evidentes; no traducen el código. Documentar con TSDoc APIs públicas cuando aporte propósito, parámetros, retorno, errores, efectos o restricciones. Tras un refactor se actualizan o eliminan comentarios obsoletos. ## Asincronía y errores locales La regla `lint/complexity/noVoid` prohíbe usar `void` para descartar promesas. Toda promesa se espera, se devuelve o gestiona explícitamente con un manejador de error. No dejar promesas flotantes ni silenciar errores con `.catch(() => undefined)`; si un callback debe devolver `void`, encapsular la operación y gestionar su fallo. ## Dependencias y documentación No añadir ni actualizar dependencias salvo necesidad real: comprobar alternativa existente, justificarla, evaluar mantenimiento, compatibilidad e impacto de bundle o runtime. No modificar lockfiles ni versiones de PNPM incidentalmente, ni introducir supresiones de análisis sin justificación. La documentación vive en `/docs`, usa Markdown y nombres en castellano. Debe ser clara, directa y no duplicar fuentes de verdad. Actualizar el documento autoritativo aplicable antes de crear otro equivalente.