Appearance
Guía de contribución
Convenciones de código
- Idioma: dominio, nombres de tipos y mensajes en español; identificadores técnicos y de framework en inglés cuando es lo natural (
user,service,store). - Lenguaje: TypeScript en modo
strictconnoUnusedLocalsynoUnusedParameters. Backend ademásemitDecoratorMetadataystrictPropertyInitialization:false(TypeORM). - ESM: ambos
package.jsondeclaran"type": "module". En el backend los imports internos se escriben con extensión.jsy alias@/...js. - Alias:
@/→src/en backend (resuelto contsc-alias) y frontend (Vite/Vitest). - Comentarios: no añadir comentarios salvo que se pidan explícitamente (convención de
AGENTS.md). - Estilo Vue: usar
<script setup>en los módulos que ya lo usan ydefineComponentdonde es el patrón vecino; seguir el componente de referencia del dominio antes de crear uno nuevo. - Lint/format: no hay ESLint, Prettier, EditorConfig ni Biome. El único control estático es el typecheck.
Estructura y patrones
- Backend por capas:
routes → middlewares → controllers → services → entidades. Los controladores no contienen lógica de negocio; los servicios no construyen respuestas HTTP. Los errores de negocio se lanzan con las clases deutils/errors.ts(NotFoundError,ConflictError,ValidationError, etc.) y los capturizaerror.middleware.ts. - Validación: todo body/query relevante se valida con un esquema Zod en
backend/src/dtos/y el middlewarevalidateBody/validateQuery. - Respuestas: siempre con
successResponse/errorResponse. - Frontend: estado en stores Pinia; las llamadas HTTP se hacen contra
utils/api.ts(no crear clientes axios nuevos). Los modales se abren conuseModalStore().openModal(id, { component, ... }). - Base de datos: cambios de esquema requieren una migración (
synchronize:false).
Tests
| Ámbito | Framework | Ubicación | Comando |
|---|---|---|---|
| Backend | Vitest (entorno node) | backend/src/__tests__/*.test.ts | cd backend && npm run test |
| Frontend | Vitest + jsdom + Vue Test Utils | frontend/src/**/__tests__/*.test.ts | cd frontend && npm run test |
- Backend: los tests mockean repositorios con
vi.mock/vi.hoisted(no usan BD real). Cubren servicios y metadatos del esquema. - Frontend: cobertura por stores, utilidades, composables, router y modales. Configuración en
frontend/vitest.config.ts, setup global enfrontend/src/test/setup.ts. - Cobertura:
cd frontend && npm run test:coverage. - Escritura: un fichero
*.test.tsjunto al módulo o en__tests__/, siguiendo el patrón del módulo probado.
Convención de campos vacíos en create/update
La normalización de campos vacíos vive en el borde de la API (backend/src/dtos/helpers.ts), nunca en los formularios:
- Campo omitido (
undefined): no se modifica (actualización parcial). - Columna nullable con el campo presente
""onull: se guardanull(limpiar). - Columna NOT NULL requerida: un campo presente y vacío es
400; el cliente debe omitirlo para no cambiarlo. - Columna NOT NULL con "vacío" significativo (p. ej.
segundo_apellido):"".
Al añadir o modificar un esquema, usa nullableText, nullableEmail, nullableUuid, nullableInt, requiredText, requiredEmail o notNullText según la columna. Los formularios del frontend no deben borrar campos vacíos del payload: los envían tal cual. Esto aplica tanto a create como a update.
Convención de búsquedas (acentos y mayúsculas)
Todas las búsquedas deben ser insensibles a acentos y a mayúsculas.
- Backend. Cada entidad buscable declara una columna
search_normalizedmantenida por los hooks@BeforeInsert/@BeforeUpdatecongenerateSearchNormalized([...]), y las consultas filtran consearchNormalized LIKE :termusando el helpernormalizeSearch(search)(backend/src/utils/string.util.ts) para construir el término. No se haceLIKEsobre columnas con acentos (nombre,direccion,descripcion, …). - Frontend. Las búsquedas locales (filtrado en cliente) usan
normalizeSearch/matchesSearchdefrontend/src/utils/search.ts; nunca.toLowerCase().includes()directamente. - Al añadir una entidad buscable hay que crear también su columna
search_normalized(en la migraciónCreateTables) y sus hooks, y añadir un test de acentos.
Checklist antes de abrir un PR
cd backend && npm run typechecksin errores.cd frontend && npm run buildsin errores (incluyevue-tsc -b).cd backend && npm run testycd frontend && npm run testen verde.- Si cambia el esquema: migración incluida y probada (
migration:run/migration:revert). - Si cambia la API: actualizar
API.mdy, si aplica,openapi.yamly las anotaciones@swagger. - Si cambia la UI: verificar accesibilidad básica (foco,
aria-label, contraste) y el requisito WCAG 2.1 AA / RD 1112/2018. - No incluir secretos (
.env,.env.prod) ni artefactos de build (dist/,coverage/). Las plantillas.env.examplesí se versionan y deben mantenerse actualizadas. - Mensaje de commit conciso y en el estilo del repositorio.
⚠️ Nota: el repositorio no define una convención formal de branching ni de mensajes de commit (no hay
CONTRIBUTING.mdni plantillas de PR). Se recomienda confirmar con el equipo y, si se acuerda, documentarla aquí.
Ramas y commits (propuesta)
⚠️ Nota: no verificable en el código; no hay evidencias en el repositorio.
A falta de convención formal, se sugiere:
- Ramas:
feat/<descripcion>,fix/<descripcion>,docs/<descripcion>,refactor/<descripcion>. - Commits: imperativo y con ámbito, p. ej.
feat(ejercicios): permitir reabrir un ejercicio cerrado.
Documentación
- La documentación técnica interna vive en
docs/(Markdown). - La documentación publicada vive en
documentation/user/(manual) ydocumentation/system/(sistema), con VitePress. - Convención: no duplicar; redactar la versión publicada a partir de la interna.