63 lines
5.9 KiB
Markdown
63 lines
5.9 KiB
Markdown
# 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.
|