Skip to content

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.

RutaNombreComponenteAccesoPermiso (meta.can)
/auth/loginLoginpages/auth/LoginPage.vuePúblico—
/auth/forgot-passwordForgotPasswordpages/auth/ForgotPasswordPage.vuePúblico—
/auth/reset-passwordResetPasswordpages/auth/ResetPasswordPage.vuePúblico—
/auth/verify-emailVerifyEmailpages/auth/VerifyEmailPage.vuePúblico—
/dashboardDashboardpages/dashboard/DashboardPage.vuePrivadadashboard:read
/dashboard/vigilantesVigilantespages/dashboard/VigilantesPage.vuePrivadavigilantes:read
/dashboard/sedesSedespages/dashboard/SedesPage.vuePrivadasedes:read
/dashboard/sedes/:sedeId/edificiosEdificiospages/dashboard/EdificiosPage.vuePrivadaedificios:read
/dashboard/edificios/:edificioId/aulasAulaspages/dashboard/AulasPage.vuePrivadaaulas:read
/dashboard/convocatoriasConvocatoriaspages/dashboard/ConvocatoriasPage.vuePrivadaconvocatorias:read
/dashboard/convocatorias/:convocatoriaId/miembrosMiembrospages/dashboard/MiembrosPage.vuePrivadatribunalMiembros:read
/dashboard/convocatorias/:convocatoriaId/ejerciciosEjerciciospages/dashboard/EjerciciosPage.vuePrivadaejercicios:read
/dashboard/templatesTemplatespages/dashboard/TemplatesPage.vuePrivadatemplates:read
/dashboard/configuracionConfiguracionpages/dashboard/ConfiguracionPage.vuePrivadaconfiguracion:read
/dashboard/usersUserspages/dashboard/UsersPage.vuePrivadausers:read
/forbiddenForbiddenpages/errors/ForbiddenPage.vuePública—
/—redirección a /dashboard——
/:pathMatch(.*)*NotFoundpages/errors/NotFoundPage.vuePública—

Guards ​

  • beforeEach:
    1. Si hay accessToken en localStorage y el store no está autenticado → authStore.initialize() (GET /auth/me).
    2. requiresAuth y sin sesión → Login.
    3. Ruta /auth/* con sesión → Dashboard.
    4. meta.can y useAcl().can(permiso) falso → Forbidden.
  • afterEach: cierra la barra de progreso y fija document.title.

Control de acceso (ACL) ​

FicheroContenido
auth/permissions.tsCatálogo Permissions con claves recurso:acción.
auth/role-permissions.tsMatriz 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.tscan(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:

StoreFicheroResponsabilidad
authauthStore.tsLogin/logout, initialize, cambio/recuperación de contraseña, usuario actual. En logout resetea el resto de stores.
useruserStore.tsPerfil propio, avatar y usuarios.
summarysummaryStore.tsKPIs del dashboard.
sedesedeStore.tsCRUD de sedes, municipios/provincias, modales.
edificioedificioStore.tsCRUD de edificios y asignación de plantas.
aulaaulaStore.tsCRUD de aulas y etiquetas.
plantaplantaStore.tsCRUD de plantas y asignación a edificios.
tagtagStore.tsEtiquetas (scope vigilante/aula) y conflictos al borrar.
convocatoriaconvocatoriaStore.tsCRUD y cambio de estado.
miembromiembroStore.tsTribunal: CRUD y renuncias.
vigilantevigilanteStore.tsCRUD, bloqueo, historial, penalizaciones e importación.
ejercicioejercicioStore.tsStore central: CRUD, ubicaciones, grupos, llamamientos, confirmaciones, asignaciones, asistencia, notificaciones y documentos.
tipoEjerciciotipoEjercicioStore.tsCatálogo de tipos de ejercicio.
templatetemplateStore.tsPlantillas de email.
documentTemplatedocumentTemplateStore.tsPlantillas de documento.
simulationStoresimulationStore.tsMotor de asignación rápida: meta, configuración, propuesta, fijados, presets.
configuracionconfiguracionStore.tsPará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).
modalStoremodalStore.tsPila de modales dinámicos (openModal/closeModal).
loadingStoreloadingStore.tsOverlay de carga con contador.
toastStoretoastStore.tsCola de notificaciones toast.
sidebarStoresidebarStore.tsEstado abierto/colapsado del menú.
routeProgressStorerouteProgressStore.tsBarra de progreso de navegación.
preferenciasStorepreferenciasStore.tsPreferencias de UI (pestaña de asignación rápida).
groupClipboardStoregroupClipboardStore.tsPortapapeles de grupos de vigilantes.

Flujo de datos ​

  • No existe capa services/: los stores invocan directamente api (utils/api.ts).
  • Cachés locales por store (p. ej. edificioStore.sedeEdificios, aulaStore.edificioAulas).
  • simulationStore persiste presets y orden de reglas en localStorage.

Componentes clave ​

Base ​

ComponenteResponsabilidad
base/BaseModal.vueModal 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.vueRenderiza los modales de modalStore.
base/SkeletonBlock/Cards/Table.vueEstados de carga.
base/ErrorPage.vueMarco de error.

Ejercicios (components/ejercicios/modals/) ​

ComponenteResponsabilidad
CreateEjercicioModal / EditEjercicioModal / DetailsEjercicioModalAlta, 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 / EditTipoEjercicioModalCatá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.
GestionarAsignacionesModalAsignaciones 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, QuickAssignResultsPanelAsignación rápida: alcance, reglas, opciones, propuesta y drag&drop. Usa simulationStore.
RealizarNotificacionDialog / PreviewEmailModalRedacción, adjuntos y previsualización de notificaciones.
ConfirmarExportacionLlamamientoDialog / ExportVigilantesFieldsModalExportación Excel de llamamientos y vigilantes.
PromocionListaEsperaDialogDiá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.
ImportarConfirmacionesExcelModalAsistente 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.
QuickSelectDialogSelecció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).

Selección rápida de vigilantes

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

Selección rápida filtrando por etiquetas

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.

Revisión antes de aplicar

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 usa POST /api/templates/render (emailTemplateService.render), que compila asunto y cuerpo con Handlebars y sustituye cid:siva-logo por 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 en document-template-tipo.catalog.ts (hoy solo CONTROL_ASISTENCIA). Igual que las de correo, se pueden duplicar y previsualizar en vivo mediante POST /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 en utils/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; para FormData elimina Content-Type.
  • Interceptor de response: ante 401 intenta POST /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.

SIVA — Sistema Integral de Vigilantes de Aulas