Skip to content

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 strict con noUnusedLocals y noUnusedParameters. Backend además emitDecoratorMetadata y strictPropertyInitialization:false (TypeORM).
  • ESM: ambos package.json declaran "type": "module". En el backend los imports internos se escriben con extensión .js y alias @/...js.
  • Alias: @/ → src/ en backend (resuelto con tsc-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 y defineComponent donde 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 de utils/errors.ts (NotFoundError, ConflictError, ValidationError, etc.) y los capturiza error.middleware.ts.
  • Validación: todo body/query relevante se valida con un esquema Zod en backend/src/dtos/ y el middleware validateBody/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 con useModalStore().openModal(id, { component, ... }).
  • Base de datos: cambios de esquema requieren una migración (synchronize:false).

Tests ​

ÁmbitoFrameworkUbicaciónComando
BackendVitest (entorno node)backend/src/__tests__/*.test.tscd backend && npm run test
FrontendVitest + jsdom + Vue Test Utilsfrontend/src/**/__tests__/*.test.tscd 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 en frontend/src/test/setup.ts.
  • Cobertura: cd frontend && npm run test:coverage.
  • Escritura: un fichero *.test.ts junto 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 "" o null: se guarda null (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_normalized mantenida por los hooks @BeforeInsert/@BeforeUpdate con generateSearchNormalized([...]), y las consultas filtran con searchNormalized LIKE :term usando el helper normalizeSearch(search) (backend/src/utils/string.util.ts) para construir el término. No se hace LIKE sobre columnas con acentos (nombre, direccion, descripcion, …).
  • Frontend. Las búsquedas locales (filtrado en cliente) usan normalizeSearch/matchesSearch de frontend/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ón CreateTables) y sus hooks, y añadir un test de acentos.

Checklist antes de abrir un PR ​

  1. cd backend && npm run typecheck sin errores.
  2. cd frontend && npm run build sin errores (incluye vue-tsc -b).
  3. cd backend && npm run test y cd frontend && npm run test en verde.
  4. Si cambia el esquema: migración incluida y probada (migration:run/migration:revert).
  5. Si cambia la API: actualizar API.md y, si aplica, openapi.yaml y las anotaciones @swagger.
  6. Si cambia la UI: verificar accesibilidad básica (foco, aria-label, contraste) y el requisito WCAG 2.1 AA / RD 1112/2018.
  7. No incluir secretos (.env, .env.prod) ni artefactos de build (dist/, coverage/). Las plantillas .env.example sí se versionan y deben mantenerse actualizadas.
  8. 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.md ni 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) y documentation/system/ (sistema), con VitePress.
  • Convención: no duplicar; redactar la versión publicada a partir de la interna.

SIVA — Sistema Integral de Vigilantes de Aulas