Appearance
Componentes y frontend
El frontend es una SPA Vue 3 con <script setup> y defineComponent según el módulo, Pinia para estado y Bootstrap 5 para estilos. Punto de entrada frontend/src/main.ts → monta App.vue, que renderiza <router-view/> más los overlays globales (ModalContainer, Toasts, LoadingOverlay, RouteProgress).
Árbol de componentes
Rutas (Vue Router)
frontend/src/router/index.ts, historial HTML5, componentes con carga diferida.
| Ruta | Nombre | Componente | Acceso | Permiso (meta.can) |
|---|---|---|---|---|
/auth/login | Login | pages/auth/LoginPage.vue | Público | — |
/auth/forgot-password | ForgotPassword | pages/auth/ForgotPasswordPage.vue | Público | — |
/auth/reset-password | ResetPassword | pages/auth/ResetPasswordPage.vue | Público | — |
/auth/verify-email | VerifyEmail | pages/auth/VerifyEmailPage.vue | Público | — |
/dashboard | Dashboard | pages/dashboard/DashboardPage.vue | Privada | dashboard:read |
/dashboard/vigilantes | Vigilantes | pages/dashboard/VigilantesPage.vue | Privada | vigilantes:read |
/dashboard/sedes | Sedes | pages/dashboard/SedesPage.vue | Privada | sedes:read |
/dashboard/sedes/:sedeId/edificios | Edificios | pages/dashboard/EdificiosPage.vue | Privada | edificios:read |
/dashboard/edificios/:edificioId/aulas | Aulas | pages/dashboard/AulasPage.vue | Privada | aulas:read |
/dashboard/convocatorias | Convocatorias | pages/dashboard/ConvocatoriasPage.vue | Privada | convocatorias:read |
/dashboard/convocatorias/:convocatoriaId/miembros | Miembros | pages/dashboard/MiembrosPage.vue | Privada | tribunalMiembros:read |
/dashboard/convocatorias/:convocatoriaId/ejercicios | Ejercicios | pages/dashboard/EjerciciosPage.vue | Privada | ejercicios:read |
/dashboard/templates | Templates | pages/dashboard/TemplatesPage.vue | Privada | templates:read |
/dashboard/configuracion | Configuracion | pages/dashboard/ConfiguracionPage.vue | Privada | configuracion:read |
/dashboard/users | Users | pages/dashboard/UsersPage.vue | Privada | users:read |
/forbidden | Forbidden | pages/errors/ForbiddenPage.vue | Pública | — |
/ | — | redirección a /dashboard | — | — |
/:pathMatch(.*)* | NotFound | pages/errors/NotFoundPage.vue | Pública | — |
Guards
beforeEach:- Si hay
accessTokenenlocalStoragey el store no está autenticado →authStore.initialize()(GET /auth/me). requiresAuthy sin sesión →Login.- Ruta
/auth/*con sesión →Dashboard. meta.canyuseAcl().can(permiso)falso →Forbidden.
- Si hay
afterEach: cierra la barra de progreso y fijadocument.title.
Control de acceso (ACL)
| Fichero | Contenido |
|---|---|
auth/permissions.ts | Catálogo Permissions con claves recurso:acción. |
auth/role-permissions.ts | Matriz rol→permisos. SUPERADMIN y ADMIN = ["*"]; SUPERVISOR tiene todos los permisos operativos (lectura y CRUD de catálogos, convocatorias, ejercicios, tribunal y asignaciones, además de ASIGNACIONES_READ y CONFIGURACION_READ), excepto TEMPLATES_* y USERS_* (incluido users:verify). En Configuración, el backend y ConfiguracionPage bloquean las claves de CLAVES_CONFIGURACION_SOLO_ADMIN. |
composables/useAcl.ts | can(permiso); los roles con "*" siempre pueden. |
Se usa en el guard del router, en Sidebar (menú desde config/sidebarMenu.ts) y en las páginas para ocultar botones de acción. El menú admite entradas externas (external: true), como Ayuda (tras Usuarios): en lugar de navegar ejecuta una acción que comprueba url_pagina_ayuda con configuracionStore.checkPaginaAyuda() y abre la página en una pestaña nueva sin cambiar de foco.
Estado global (Pinia)
frontend/src/stores/ contiene 23 stores:
| Store | Fichero | Responsabilidad |
|---|---|---|
auth | authStore.ts | Login/logout, initialize, cambio/recuperación de contraseña, usuario actual. En logout resetea el resto de stores. |
user | userStore.ts | Perfil propio, avatar y usuarios. |
summary | summaryStore.ts | KPIs del dashboard. |
sede | sedeStore.ts | CRUD de sedes, municipios/provincias, modales. |
edificio | edificioStore.ts | CRUD de edificios y asignación de plantas. |
aula | aulaStore.ts | CRUD de aulas y etiquetas. |
planta | plantaStore.ts | CRUD de plantas y asignación a edificios. |
tag | tagStore.ts | Etiquetas (scope vigilante/aula) y conflictos al borrar. |
convocatoria | convocatoriaStore.ts | CRUD y cambio de estado. |
miembro | miembroStore.ts | Tribunal: CRUD y renuncias. |
vigilante | vigilanteStore.ts | CRUD, bloqueo, historial, penalizaciones e importación. |
ejercicio | ejercicioStore.ts | Store central: CRUD, ubicaciones, grupos, llamamientos, confirmaciones, asignaciones, asistencia, notificaciones y documentos. |
tipoEjercicio | tipoEjercicioStore.ts | Catálogo de tipos de ejercicio. |
template | templateStore.ts | Plantillas de email. |
documentTemplate | documentTemplateStore.ts | Plantillas de documento. |
simulationStore | simulationStore.ts | Motor de asignación rápida: meta, configuración, propuesta, fijados, presets. |
configuracion | configuracionStore.ts | Parámetros, mapas de colores, contacto del proceso selectivo (contactoProceso), política de contraseñas (passwordPolicy / fetchPasswordPolicy) y comprobación de la URL de ayuda (checkPaginaAyuda). |
modalStore | modalStore.ts | Pila de modales dinámicos (openModal/closeModal). |
loadingStore | loadingStore.ts | Overlay de carga con contador. |
toastStore | toastStore.ts | Cola de notificaciones toast. |
sidebarStore | sidebarStore.ts | Estado abierto/colapsado del menú. |
routeProgressStore | routeProgressStore.ts | Barra de progreso de navegación. |
preferenciasStore | preferenciasStore.ts | Preferencias de UI (pestaña de asignación rápida). |
groupClipboardStore | groupClipboardStore.ts | Portapapeles de grupos de vigilantes. |
Flujo de datos
- No existe capa
services/: los stores invocan directamenteapi(utils/api.ts). - Cachés locales por store (p. ej.
edificioStore.sedeEdificios,aulaStore.edificioAulas). simulationStorepersiste presets y orden de reglas enlocalStorage.
Componentes clave
Base
| Componente | Responsabilidad |
|---|---|
base/BaseModal.vue | Modal genérico. El componente interno puede exponer footerButtons, footerLeftText y footerLeftIcon desde su setup para controlar el pie. Z-index apilable y gestión de foco/Escape. |
base/ModalContainer.vue | Renderiza los modales de modalStore. |
base/SkeletonBlock/Cards/Table.vue | Estados de carga. |
base/ErrorPage.vue | Marco de error. |
Ejercicios (components/ejercicios/modals/)
| Componente | Responsabilidad |
|---|---|
CreateEjercicioModal / EditEjercicioModal / DetailsEjercicioModal | Alta, edición y detalle de ejercicio. Los detalles se muestran a pantalla completa (size: xl + fillBody) con pestañas Información del ejercicio, Ubicaciones (barra resumen con Sedes/Edificios/Aulas y tres tablas con cabeceras sticky dentro de un único scroll) y Asignaciones (barra resumen y tarjeta «Vigilantes» con los asignados, su ubicación, responsable y estado de asistencia en badges). Reutiliza el estilo de pestañas de DetailsVigilanteModal (.details-tabs). |
TipoEjercicioManagerModal / EditTipoEjercicioModal | Catálogo de tipos. |
GestionarUbicacionesModal (+ UbicacionSedeBody, UbicacionEdificioBody, EdificioUbicacionCard) | Configuración de sedes/edificios/aulas (calcular_aulas/manual, ratio/fijo), validación de impacto y export Excel cliente. |
GestionarVigilantesModal (+ GrupoVigilantesBody) | Selección de vigilantes, grupos, llamamientos, confirmaciones e importación/exportación. Excluye de la lista a los vigilantes bloqueados y penalizados (tratados igual) y avisa mediante un contador. Abre QuickSelectDialog con el botón Selección rápida. |
GestionarAsignacionesModal | Asignaciones y asistencia (responsables, anulaciones, penalizaciones), export PDF/XLSX y control de asistencia. Asignación manual (checkbox + «Asignar a…» o drag&drop) y Asignación rápida. La promoción desde la lista de espera usa utils/asignacionPrioridad.ts (primerCandidatoParaSede). Valida las horas del ejercicio (hora_vigilantes_aula_tribunal y hora_comienzo_ejercicio) antes de notificar, reenviar, restaurar o promover; si faltan, abre openFaltanHorasNotificacionDialog (utils/modal-dialogs.ts) y bloquea la acción. |
QuickAssignModal + QuickAssignScopeSelector, QuickAssignRulesList, QuickAssignOptionsPanel, QuickAssignSlotsList, QuickAssignResultsPanel | Asignación rápida: alcance, reglas, opciones, propuesta y drag&drop. Usa simulationStore. |
RealizarNotificacionDialog / PreviewEmailModal | Redacción, adjuntos y previsualización de notificaciones. |
ConfirmarExportacionLlamamientoDialog / ExportVigilantesFieldsModal | Exportación Excel de llamamientos y vigilantes. |
PromocionListaEsperaDialog | Diálogo «Cubrir la plaza liberada»: al anular una asistencia con candidatos en espera, muestra al reemplazado (el anulado, con su sede) y al sustituto y deja elegir Asignación automática (usa primerCandidatoParaSede: primer candidato por orden que encaje con la sede liberada —preferencia igual o sin preferencia—, con fallback al primero por orden; crea la asignación y notifica solo al promovido), Asignación manual (pestaña Asignación con el candidato marcado, el destino enfocado y la pestaña de sede/edificio activada) o Ahora no. El botón primario lo decide promocion_lista_espera_automatica. |
ImportarConfirmacionesExcelModal | Asistente de importación de confirmaciones desde Excel/CSV (3 pasos). En Revisar, el resumen es un filtro con contadores (se confirmarán, ya confirmados, fuera de plazo, rechazados ignorados, no encontrados, con cambios): muestra una categoría a la vez, cada tabla con scroll propio, y permite editar la sede asignada, sobrescribir ya confirmados y actualizar datos personales. |
QuickSelectDialog | Selección rápida: workspace XL (configuración a la izquierda, vista previa a la derecha). Origen Filtro actual (chips de solo lectura con todas las etiquetas del listado y las activas resaltadas, búsqueda, vista y orden del listado también en solo lectura) o Todos los disponibles (etiquetas editables y orden multicriterio propio que determina «los primeros» y pasa el método a Primeros al añadir un criterio, reutiliza utils/vigilanteSort.ts), buscador interno sobre el pool, método (aleatorios/primeros/porcentaje), cantidad (chips numéricos, Todo y porcentajes), opciones (añadir/reemplazar, excluir seleccionados), panel de información tipo QuickAssignResultsPanel, Restablecer (vuelve a los valores por defecto, sin persistencia) y estado propio por origen (método, cantidad, opciones, etiquetas y orden se conservan al alternar Filtro actual/Todos los disponibles) en memoria, sin localStorage. |
Selección rápida de vigilantes
QuickSelectDialog se abre desde Selección rápida en la pestaña Selección. Recibe del padre candidatos, disponibles, seleccionActual, tags y filtrosActuales (búsqueda, etiquetas, orden y vista del listado) y emite onConfirm con los identificadores resultantes. En Filtro actual los filtros del listado se muestran como chips de solo lectura (etiquetas con las activas resaltadas, búsqueda, vista y orden) y el orden propio no se aplica: «Primeros» usa el del listado. En Todos los disponibles las etiquetas y el orden son editables; al añadir un criterio de orden el método pasa a Primeros, de modo que el orden determina la selección (los N primeros de ese orden). Con Aleatorios o Porcentaje el orden no influye en la selección. Restablecer devuelve ambos orígenes a los valores por defecto. La configuración vive solo en memoria (no se persiste): cada origen mantiene su propio estado durante la sesión y al reabrir la ventana se parte de los valores por defecto (utils/quickSelectConfig.ts).

En el origen Todos los disponibles se filtra por etiquetas (coincidencia Y), que se reflejan en el contador pool/disponibles:

Importar confirmaciones — paso «Revisar»
El resumen del paso de revisión es un filtro con contadores: se muestra una categoría cada vez y cada tabla tiene su propio scroll. Las filas de Encontrados con cambios de datos personales se marcan con el badge datos, y el filtro Con cambios permite aplicarlos.

Pestaña Confirmación — columna «Orden»
La tabla de confirmaciones (GestionarVigilantesModal) muestra la columna Orden con el rango de confirmación efectivo del ejercicio. Lo calcula el backend (ParticipacionService.getOrdenConfirmacion) con el comparador canónico compararOrdenConfirmacion, el mismo que usa el motor de asignación. El rango es global (se calcula sobre todas las confirmaciones efectivas; filtrar o buscar no renumera) y denso (1, 2, 2, 3: dos confirmaciones que coinciden en fecha_confirmacion ?? fecha_respuesta y en orden_confirmacion comparten posición). La cabecera es ordenable (asc → desc → sin orden) y las filas sin orden muestran —; la ordenación usa frontend/src/utils/ordenConfirmacion.ts.
Correo
Las plantillas de correo (email_template) llevan el logo embebido como adjunto inline (<img src="cid:siva-logo" />). backend/src/utils/email-assets.ts expone getLogoAttachment() (public/images/logo.png como adjunto inline con Content-ID) y attachLogoIfNeeded(); backend/src/config/email.config.ts envuelve el sendMail del transporter para añadirlo automáticamente cuando el HTML contiene cid:siva-logo. En las vistas previas el cid: se sustituye por la URL remota /images/logo.png (email-template.service.ts en backend y frontend/src/utils/plantilla-email.ts en los diálogos de notificación), por lo que los assets de /public se sirven con Cross-Origin-Resource-Policy: cross-origin (backend/src/app.ts).
Plantillas
- Plantillas de email (
templateStore.ts,email-template.service.ts): además del CRUD, la UI permite duplicar cualquier plantilla (incluidas las de sistema, que no son editables) y muestra una vista previa en vivo al crear o editar asunto/cuerpo. La previsualización sin guardar usaPOST /api/templates/render(emailTemplateService.render), que compila asunto y cuerpo con Handlebars y sustituyecid:siva-logopor la URL del logo. Solo puede haber una plantilla activa por tipo; al activar una, la anterior se desactiva. - Plantillas de documento (
documentTemplateStore.ts,document-template.service.ts): catálogo de tipos endocument-template-tipo.catalog.ts(hoy soloCONTROL_ASISTENCIA). Igual que las de correo, se pueden duplicar y previsualizar en vivo mediantePOST /api/document-templates/render. Al generar el control de asistencia de un ejercicio se elige la plantilla activa del tipo dando prioridad a las de usuario sobre las de sistema (utils/document-template-select.ts); los datos de ejemplo de la previsualización viven enutils/document-template-samples.ts.
Otros dominios
components/vigilantes/modals/:CreateVigilanteModal,EditVigilanteModal,DetailsVigilanteModal,ToggleBloqueadoModal,TagManagerModal,EditTagModal,ImportVigilantesModal(+import/ImportConflictModal,ImportEditRowModal,SplitNameModal).components/sedes/modals/,edificios/modals/,aulas/modals/,convocatorias/modals/,miembros/modals/,users/modals/,templates/modals/: CRUD, detalle y cambios de estado por dominio.
Ventanas de detalle
Los modales de detalle (Details*Modal) de catálogos y plantillas comparten un formato estándar: una tarjeta (.card) con cabecera «Información de …» y una rejilla de dos columnas (row g-3 con col-12 col-md-6), donde cada campo es una etiqueta text-muted small seguida de un valor form-control-plaintext (con icono de Bootstrap Icons cuando aplica: contacto, fechas, ubicación). Los estados se muestran como badge, las etiquetas con TagBadge y los textos largos (dirección, observaciones, equipamiento, descripción, asunto) ocupan el ancho completo (col-12) con la clase prewrap. DetailsMiembroModal y DetailsUserModal son la referencia.
Los modales de detalle de plantillas (DetailsTemplateModal, DocumentTemplateDetailsModal) usan el patrón datos a la izquierda / vista previa a la derecha, el mismo que las ventanas de crear/duplicar plantilla. El contenedor raíz es .split-template con una row g-4 split-template-row de dos col-lg-6: a la izquierda (split-template-main) la tarjeta «Información de la plantilla» con los campos apilados, y a la derecha (split-template-aside) el panel .preview-panel con cabecera, spinner, el iframe.preview-frame y .preview-empty si no hay previsualización. Se abren con size: "xl" + fillBody: true, de modo que el panel de vista previa ocupa toda la altura. La vista previa se genera al abrir la ventana.
Las clases comunes de estas ventanas (.split-template, .split-template-row, .split-template-main, .split-template-aside, .preview-panel, .preview-subject, .preview-frame, .preview-empty) viven en frontend/src/assets/css/templates.css (importado en main.ts) y las reutilizan los formularios CreateTemplateModal, EditTemplateModal, DocumentTemplateUploadModal y DocumentTemplateEditModal. Las clases de los detalles a pantalla completa (.details-modal-root, .details-modal-body, .details-tabs, .tab-scroll-area, .tab-pane-fixed, .prewrap) viven en frontend/src/assets/css/details.css y las reutilizan DetailsVigilanteModal y DetailsEjercicioModal.
Compartidos
shared/Breadcrumb, ConfirmDialog, DateRangeFilter, YearRangeFilter, SelectFilter, PaginationBar, TagBadge, LoadingOverlay, RouteProgress, Toasts.
Capa de API (utils/api.ts)
api: instancia Axios principal,baseURL = VITE_API_URL || "/api".refreshApi: instancia auxiliar sin interceptores, solo para el refresco.- Interceptor de request: añade
Authorization: Bearer <accessToken>salvo en los endpoints de auth; paraFormDataeliminaContent-Type. - Interceptor de response: ante
401intentaPOST /auth/refresh-token, encola peticiones concurrentes y reintenta; si el refresh falla, limpia los tokens y redirige a/auth/login. - Tokens: en
localStorage(accessToken,refreshToken).
Tipos (frontend/src/types/)
Interfaces por dominio: User/UserProfile, ModalOptions, quickAssign, ejercicio, ejercicio-ubicacion (+ -local), ejercicio-grupo-vigilante, vigilante (+ import), asignacion, llamamiento, notificacion, sede, edificio, aula, planta, convocatoria, miembro, tag, template, document-template, tipo-ejercicio, configuracion, summary, ubicacion-uso. El envoltorio común ApiResponse<T> está en types/index.ts.
Convenciones de UI
El sistema de diseño está descrito en DESIGN.md (paleta "Sala de Exámenes", tipografía Poppins, modales apilables). Requisito de accesibilidad WCAG 2.1 AA (RD 1112/2018), con foco visible, aria-label en botones icon-only y skip-link en el layout.