fix: corregir layout de dashboard, resiliencia en filtros de asignaturas y paginacion de bd (v3.8.12)
This commit is contained in:
@@ -0,0 +1,67 @@
|
||||
# Plan Técnico: Paginación Server-Side y Optimización de Base de Datos
|
||||
|
||||
## 1. Arquitectura Técnica de la Solución (4 Capas)
|
||||
|
||||
### 1.1 Capa de Esquemas y Contratos (Schemas / DTOs)
|
||||
- **Contrato Estándar de Respuesta Paginada (`PaginatedResponse[T]`)**:
|
||||
```python
|
||||
{
|
||||
"status": "success",
|
||||
"total": int,
|
||||
"page": int,
|
||||
"per_page": int,
|
||||
"pages": int,
|
||||
"has_prev": bool,
|
||||
"has_next": bool,
|
||||
"items": List[T]
|
||||
}
|
||||
```
|
||||
- Para endpoints existentes (`/users`, `/audit-logs`), mantener retrocompatibilidad incorporando las claves esperadas por los clientes existentes (`users`, `logs`, `commissions`, etc.) junto al bloque de metadatos de paginación.
|
||||
|
||||
### 1.2 Capa de Persistencia y Repositorios (Storage / Repositories)
|
||||
- **`AuditService.get_logs`**:
|
||||
- Modificar firma para admitir `page: int = 1`, `per_page: int = 25`, `search: Optional[str] = None`.
|
||||
- Construir query con `AuditLog.query`.
|
||||
- Si `search`: agregar filtro OR sobre `AuditLog.details.ilike(f'%{s}%')`, `AuditLog.user_email.ilike(f'%{s}%')`, `AuditLog.action.ilike(f'%{s}%')`.
|
||||
- Calcular `total = query.count()`.
|
||||
- Aplicar `.order_by(AuditLog.created_at.desc()).offset((page - 1) * per_page).limit(per_page)`.
|
||||
- Retornar tupla `(logs, total)`.
|
||||
- **`ReservationService` y `ReservationRepository`**:
|
||||
- Trasladar los filtros en memoria (`floor`, `shift`, `search`, `is_virtual`) a la consulta SQLAlchemy relacional.
|
||||
- Añadir `limit: int = 1000` predeterminado a las consultas para proteger los buffers del gestor de base de datos.
|
||||
- **Modelos SQLAlchemy**:
|
||||
- Verificar índices en columnas frecuentes de ordenamiento y filtrado (`role_id`, `is_active` en `User`, `status`, `start_time` en `Reservation`).
|
||||
|
||||
### 1.3 Capa de Routers FastAPI (`backend/routers/`)
|
||||
- **`backend/routers/admin.py`**:
|
||||
- `get_users`: Recibir `page: int = Query(1, ge=1)`, `per_page: int = Query(25, ge=1, le=100)`, `all: bool = Query(False)`.
|
||||
- Si `all` es `False`, ejecutar `total = query.count()`, `.offset((page - 1) * per_page).limit(per_page)` y devolver metadatos completos (`total`, `page`, `per_page`, `pages`, `has_prev`, `has_next`).
|
||||
- Crear endpoint `/api/v1/users/teachers`: Consulta filtrada de usuarios activos con rol docente (`docente`, `profesor`, etc.) proyectando solo `id`, `name`, `email` ordenado alfabéticamente.
|
||||
- `get_audit_logs`: Aceptar `page: int = Query(1, ge=1)`, `per_page: int = Query(25, ge=1, le=100)`, `search: Optional[str] = Query(None)`. Retornar el objeto `pagination` estructurado con `total`, `pages`, `has_prev`, `has_next`.
|
||||
- **`backend/routers/academic.py`**:
|
||||
- `list_commissions`: Agregar `page`, `per_page`, `search` con filtrado SQL y cálculo de totales.
|
||||
- `list_subjects`: Agregar `page`, `per_page`, manteniendo compatibilidad con llamadas sin paginación explícita.
|
||||
- **`backend/routers/reservations.py`**:
|
||||
- Integrar filtros SQL en `list_reservations` con límite máximo de registros.
|
||||
|
||||
### 1.4 Capa de Frontend BFF (Node.js Express + Nunjucks)
|
||||
- **`frontend/src/routes/admin.js`**:
|
||||
- `handleUsersList`: Extraer `page: parseInt(req.query.page, 10) || 1`, `per_page: 25`, `search`, `role`, `status`. Llamar a `/admin/users` pasando estos parámetros. Armar el objeto `pagination` con `pages_list` para navegación compacta.
|
||||
- Desacoplar `fetchUsersAndRoles`: En pantallas de alta/edición (`handleUserAdd`, `handleUserEdit`), solicitar únicamente roles y document_types sin descargar toda la base de usuarios.
|
||||
- `handleCommissionsList`: Reemplazar la llamada a `GET /users` por `GET /users/teachers` para poblar el dropdown de docentes.
|
||||
- **`frontend/views/admin/users/list.html`**:
|
||||
- Actualizar el markup de paginación para iterar sobre `pagination.pages_list` y generar enlaces conservando query params:
|
||||
`href="/admin/users_list?page={{ p }}{% if search %}&search={{ search }}{% endif %}{% if role_filter %}&role={{ role_filter }}{% endif %}{% if status_filter %}&status={{ status_filter }}{% endif %}"`.
|
||||
- Incorporar métricas de página: *"Mostrando página {{ pagination.page }} de {{ pagination.pages }} (Total: {{ pagination.total }} usuarios)"*.
|
||||
|
||||
---
|
||||
|
||||
## 2. Plan de Pruebas Automatizadas
|
||||
1. **Pruebas de Backend (`backend/tests/test_pagination_db.py`)**:
|
||||
- `test_get_users_pagination_defaults`: Verificar que `/api/v1/users` retorne `page=1`, `per_page=25` y las propiedades `total`, `pages`, `has_prev`, `has_next`.
|
||||
- `test_get_users_search_and_role_filters`: Comprobar que los filtros por texto y rol se ejecutan a nivel SQL.
|
||||
- `test_get_teachers_endpoint`: Validar que `/api/v1/users/teachers` devuelva solo usuarios docentes con datos mínimos.
|
||||
- `test_get_audit_logs_pagination`: Validar cálculo correcto de páginas y `has_next`/`has_prev` con filtrado SQL.
|
||||
- `test_reservations_sql_filtering`: Validar filtros por modalidad y rango temporal con límites.
|
||||
2. **Inspección de Linter y Tipado**:
|
||||
- Ejecutar `pyright` sobre todo el backend para garantizar 0 errores (Principio 10).
|
||||
@@ -0,0 +1,62 @@
|
||||
# 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.
|
||||
@@ -0,0 +1,59 @@
|
||||
# Desglose de Tareas: Paginación Server-Side y Optimización de Base de Datos
|
||||
|
||||
## Tareas de Implementación
|
||||
|
||||
- [x] **Tarea 1: Optimización de Backend en Usuarios y Endpoint Especializado de Docentes**
|
||||
- **Estimación**: 25 min
|
||||
- **Acciones**:
|
||||
- Actualizar `get_users` en `backend/routers/admin.py` para aceptar `page`, `per_page`, `all` y filtros SQL con conteo `query.count()` y `.offset().limit()`.
|
||||
- Crear endpoint `/api/v1/users/teachers` en `backend/routers/admin.py` con filtro de rol y proyección ligera (`id`, `name`, `email`).
|
||||
- Añadir índices en `User.role_id` y `User.is_active` en `backend/app/models/user.py`.
|
||||
- **Hecho cuando**: `/api/v1/users?page=1&per_page=25` retorna estructura con `total`, `pages`, `page`, `per_page`, `has_prev`, `has_next` y `/api/v1/users/teachers` retorna solo docentes activos sin errores.
|
||||
|
||||
- [x] **Tarea 2: Optimización de Backend en Auditoría y Reservas**
|
||||
- **Estimación**: 25 min
|
||||
- **Acciones**:
|
||||
- Actualizar `AuditService.get_logs` para recibir `page`, `per_page`, `search` y calcular `total = query.count()` con `.offset().limit()`.
|
||||
- Actualizar `get_audit_logs` en `backend/routers/admin.py` para exponer el bloque `pagination` completo.
|
||||
- Actualizar `list_reservations` en `backend/routers/reservations.py` para mover los filtros en Python (`floor`, `shift`, `search`, `is_virtual`) a la consulta SQLAlchemy relacional con joins e imponer un `limit` de seguridad predeterminado de 1000 registros.
|
||||
- **Hecho cuando**: Las consultas a `/api/v1/audit-logs` retornan metadatos de paginación precisos y `/api/v1/reservations` ejecuta sus filtros en la cláusula SQL WHERE.
|
||||
|
||||
- [x] **Tarea 3: Optimización de Backend en Estructura Académica (Comisiones y Asignaturas)**
|
||||
- **Estimación**: 20 min
|
||||
- **Acciones**:
|
||||
- Modificar `list_commissions` en `backend/routers/academic.py` para soportar `search`, `page`, `per_page`, `subjects`, `academic_terms` y `careers` en la respuesta unificada.
|
||||
- Modificar `list_subjects` en `backend/routers/academic.py` para admitir `page`, `per_page` con retrocompatibilidad.
|
||||
- **Hecho cuando**: Las llamadas con parámetros de paginación a `/api/v1/commissions` y `/api/v1/subjects` retornan datos paginados y los conteos de registros reales.
|
||||
|
||||
- [x] **Tarea 4: Implementación de Paginación en Frontend BFF y Vistas Nunjucks**
|
||||
- **Estimación**: 30 min
|
||||
- **Acciones**:
|
||||
- Modificar `handleUsersList` en `frontend/src/routes/admin.js` para consumir `/admin/users` con `page`, `per_page`, `search`, `role`, `status` y construir el objeto `pagination` con `pages_list`.
|
||||
- Optimizar `fetchUsersAndRoles` y `handleCommissionsList` para que la vista de comisiones use `/api/v1/users/teachers` en vez de cargar todos los usuarios.
|
||||
- Modificar `frontend/views/admin/users/list.html` para renderizar la barra de paginación conservando los query parameters activos y mostrando el contador total de registros y páginas.
|
||||
- **Hecho cuando**: Al navegar por `/admin/users_list`, la página se divide en bloques de 25 registros, los enlaces de página funcionan manteniendo los filtros y la memoria se mantiene estable.
|
||||
|
||||
- [x] **Tarea 5: Suite de Pruebas Automatizadas y Verificación de Tipos (Zero Errors)**
|
||||
- **Estimación**: 25 min
|
||||
- **Acciones**:
|
||||
- Crear `backend/tests/test_pagination_db.py` cubriendo paginación de usuarios, auditoría, endpoint de docentes y filtros de reservas.
|
||||
- Ejecutar suite `pytest tests -v` en backend y verificar 100% verde.
|
||||
- Verificar con `pyright` (Principio 10) que no haya errores de tipado o diagnóstico.
|
||||
- **Hecho cuando**: Todas las pruebas automatizadas pasan y no hay advertencias ni errores en el Language Server.
|
||||
|
||||
- [x] **Tarea 6: Reparación de Layout de Dashboard y Resiliencia en Filtros de Asignaturas/Comisiones**
|
||||
- **Estimación**: 20 min
|
||||
- **Acciones**:
|
||||
- Reparar balance de etiquetas `</div>` en `frontend/views/dashboard/dashadm.html` para devolver módulos de gestión, menús visuales y gráfico de tendencia a su posición correcta en el grid principal.
|
||||
- Soportar parámetros de búsqueda vacíos en `list_subjects`, `list_commissions`, `list_classrooms` y `list_reservations` en FastAPI evitando códigos 422.
|
||||
- Limpiar el objeto de parámetros en `frontend/src/routes/admin.js` para `/subjects` y `/commissions`.
|
||||
- **Hecho cuando**: `/dashboard`, `/admin/subjects_list` y `/admin/commissions_list` renderizan perfectamente los elementos y datos en la UI.
|
||||
|
||||
- [x] **Tarea 7: Bump Semántico a v3.8.12, Git Push y Despliegue en Producción**
|
||||
- **Estimación**: 20 min
|
||||
- **Acciones**:
|
||||
- Incrementar versión semántica a `v3.8.12` en `package.json`, `app.js`, `__init__.py`, `setup.py`.
|
||||
- Actualizar `CHANGELOG.md` y `MEMORY.md`.
|
||||
- Ejecutar `git add .`, commit y `git push origin dev`.
|
||||
- Desplegar en el contenedor LXC de producción `10.0.0.217` mediante script y verificar HTTP 200 en `/version` y funcionamiento fluido en `/admin/users_list`, `/dashboard`, `/admin/subjects_list` y `/admin/commissions_list`.
|
||||
- **Hecho cuando**: Producción corre en `v3.8.12` con respuesta exitosa y verificación de disponibilidad.
|
||||
Reference in New Issue
Block a user