5.9 KiB
Especificación: Paginación Server-Side y Buenas Prácticas de Base de Datos en Listas y Vistas
1. Contexto y Justificación del Problema
En entornos con ingesta masiva de datos (como la sincronización con Moodle institucional que incorpora más de 14.000 registros), la recuperación de entidades sin paginación ni cláusulas LIMIT/OFFSET (mediante .all()) provoca cuellos de botella críticos:
- Saturación de Memoria: La carga de miles de usuarios o registros en memoria sobre el proceso ASGI FastAPI y el BFF Express genera picos de RAM, lentitud y potencial caída del contenedor.
- Filtrado Ineficiente en CPU: Filtrar arrays en memoria Node.js o bucles Python en lugar del motor relacional PostgreSQL / SQLite desaprovecha los índices B-Tree y genera latencias de red por transferencia innecesaria de payloads masivos.
- Consumo de Ancho de Banda y Renderizado Lento: Enviar listas completas al frontend satura el DOM del navegador y degrada severamente la experiencia de usuario.
Esta especificación establece la arquitectura estándar de paginación server-side, optimización de consultas SQL (filtros en WHERE, conteo con count(), proyecciones ligeras para selectores) y controles visuales en los módulos de:
- Usuarios (
/admin/users,/admin/users_list). - Auditoría (
/admin/audit-logs,/admin/audit_logs). - Espacios y Sedes (
/classrooms,/buildings). - Estructura Académica (
/careers,/subjects,/commissions,/academic-terms). - Reservas y Calendario (
/reservations).
2. Requisitos Funcionales en Sintaxis EARS
2.1 Módulo de Usuarios (/users, /admin/users_list)
-
RF-01 (Ubicuo - Paginación y Conteo Server-Side en Usuarios):
EL SISTEMA aplicará paginación server-side basada en LIMIT y OFFSET sobre la tabla users en los endpoints /api/v1/users y /api/v1/admin/users, retornando el total de registros coincidentes, la página actual, la cantidad por página y el total de páginas. -
RF-02 (Basado en Eventos - Filtrado en Motor SQL):
CUANDO el cliente envíe parámetros de búsqueda ('search'), rol ('role') o estado ('status'), EL SISTEMA aplicará los filtros en la cláusula WHERE de la consulta SQL antes de ejecutar el conteo y la paginación, sin cargar el universo completo de usuarios en memoria. -
RF-03 (Opcional - Consulta Ligera para Selectores y Modales):
DONDE una operación requiera poblar selectores de docentes o modales rápidos, EL SISTEMA proveerá el endpoint especializado /api/v1/users/teachers o el parámetro query all=true con límite de seguridad, retornando únicamente los atributos esenciales (id, name, email) para evitar transferencias masivas innecesarias. -
RF-04 (Basado en Estados - Preservación de Estado de Navegación en UI):
MIENTRAS el operador navegue entre páginas de la lista de usuarios en /admin/users_list, EL SISTEMA preservará los filtros activos de búsqueda, rol y estado en los enlaces de la barra de paginación.
2.2 Módulo de Auditoría (/audit-logs, /admin/audit_logs)
-
RF-05 (Ubicuo - Paginación y Filtrado SQL en Bitácora):
EL SISTEMA ejecutará las consultas de auditoría en /api/v1/audit-logs con paginación server-side nativa (page, per_page), calculando el número total de eventos coincidentes mediante COUNT() y aplicando LIMIT y OFFSET en la base de datos. -
RF-06 (Basado en Eventos - Búsqueda de Texto en Eventos de Auditoría):
CUANDO el administrador filtre por texto libre ('search'), módulo ('module'), acción ('action') o usuario ('user_id'), EL SISTEMA evaluará las condiciones en el motor relacional sobre las columnas indexadas de AuditLog.
2.3 Módulo de Estructura Académica (Carreras, Asignaturas, Comisiones)
-
RF-07 (Ubicuo - Paginación y Carga Optimizada de Comisiones y Asignaturas):
EL SISTEMA soportará parámetros de paginación (page, per_page) y filtros en SQL para /api/v1/subjects y /api/v1/commissions, garantizando que el listado administrativo no transfiera entidades innecesarias. -
RF-08 (No Deseado - Prevención de Carga Masiva de Usuarios en Comisiones):
SI la vista de comisiones /admin/commissions_list requiere el catálogo de docentes para asignación, ENTONCES EL SISTEMA consultará únicamente a los usuarios con rol docente (/api/v1/users/teachers) en lugar de invocar la totalidad de usuarios de la base de datos.
2.4 Módulo de Reservas y Calendario (/reservations)
- RF-09 (Basado en Eventos - Filtrado SQL de Reservas):
CUANDO se consulte el cronograma de reservas (/api/v1/reservations), EL SISTEMA resolverá los filtros de modalidad virtual, piso, turno y texto de búsqueda en la consulta relacional con JOINs y cláusula WHERE, restringiendo el resultado a un límite máximo de seguridad (por defecto 1000 registros).
2.5 Módulo de Espacios y Sedes (/classrooms, /buildings)
- RF-10 (Ubicuo - Filtrado Indexado y Métricas de Espacios):
EL SISTEMA ejecutará los filtros de sede, piso y modalidad en /api/v1/classrooms y /api/v1/buildings directamente en la base de datos, asegurando tiempos de respuesta sub-segundo sin degradación por volumen.
3. Criterios de Aceptación y Validación
- La llamada a
/api/v1/userssin parámetros debe retornar por defectopage=1,per_page=25y el total real calculado mediantequery.count(). - La navegación en
/admin/users_listno debe congelar el navegador ni la memoria del servidor al paginar o buscar. - El endpoint
/api/v1/audit-logsdebe devolver metadatos de paginación (page,per_page,total,pages,has_prev,has_next) consistentes con la vista/admin/audit_logs. - El endpoint
/api/v1/users/teachersdebe responder únicamente con docentes activos y campos{id, name, email}, reemplazando la llamada masiva a/usersen la vista de comisiones. - Cero errores de diagnóstico en Pyright y 100% de la suite de pruebas unitarias/integración en verde.