# 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).