Files

4.9 KiB

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]):
    {
        "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).