David
0e7106f30c
- Updated "Ficha del proyecto UECKO.md" to clarify architectural boundaries and continuity rules. - Revised "README.md" to enhance structure and clarify sources of truth for documentation. - Improved "backend.md" with clearer definitions of responsibilities and architectural layers. - Streamlined "convenciones.md" to emphasize naming conventions and TypeScript best practices. - Enhanced "datos-persistencia.md" to specify persistence rules and data integrity measures. - Updated "frontend.md" to define frontend rules and state management practices. - Refined "testing.md" to clarify testing levels and validation processes. - Revised "vision-general.md" to outline system architecture and module boundaries more clearly.
34 lines
2.6 KiB
Markdown
34 lines
2.6 KiB
Markdown
# 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.
|
|
|
|
## 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<T>` 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.
|