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

Á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 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.

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.