# 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: 1. **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. 2. **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. 3. **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 1. La llamada a `/api/v1/users` sin parámetros debe retornar por defecto `page=1`, `per_page=25` y el total real calculado mediante `query.count()`. 2. La navegación en `/admin/users_list` no debe congelar el navegador ni la memoria del servidor al paginar o buscar. 3. El endpoint `/api/v1/audit-logs` debe devolver metadatos de paginación (`page`, `per_page`, `total`, `pages`, `has_prev`, `has_next`) consistentes con la vista `/admin/audit_logs`. 4. El endpoint `/api/v1/users/teachers` debe responder únicamente con docentes activos y campos `{id, name, email}`, reemplazando la llamada masiva a `/users` en la vista de comisiones. 5. Cero errores de diagnóstico en Pyright y 100% de la suite de pruebas unitarias/integración en verde.