4.9 KiB
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 sobreAuditLog.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).
- Modificar firma para admitir
ReservationServiceyReservationRepository:- Trasladar los filtros en memoria (
floor,shift,search,is_virtual) a la consulta SQLAlchemy relacional. - Añadir
limit: int = 1000predeterminado a las consultas para proteger los buffers del gestor de base de datos.
- Trasladar los filtros en memoria (
- Modelos SQLAlchemy:
- Verificar índices en columnas frecuentes de ordenamiento y filtrado (
role_id,is_activeenUser,status,start_timeenReservation).
- Verificar índices en columnas frecuentes de ordenamiento y filtrado (
1.3 Capa de Routers FastAPI (backend/routers/)
backend/routers/admin.py:get_users: Recibirpage: int = Query(1, ge=1),per_page: int = Query(25, ge=1, le=100),all: bool = Query(False).- Si
allesFalse, ejecutartotal = 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 soloid,name,emailordenado alfabéticamente. get_audit_logs: Aceptarpage: int = Query(1, ge=1),per_page: int = Query(25, ge=1, le=100),search: Optional[str] = Query(None). Retornar el objetopaginationestructurado contotal,pages,has_prev,has_next.
backend/routers/academic.py:list_commissions: Agregarpage,per_page,searchcon filtrado SQL y cálculo de totales.list_subjects: Agregarpage,per_page, manteniendo compatibilidad con llamadas sin paginación explícita.
backend/routers/reservations.py:- Integrar filtros SQL en
list_reservationscon límite máximo de registros.
- Integrar filtros SQL en
1.4 Capa de Frontend BFF (Node.js Express + Nunjucks)
frontend/src/routes/admin.js:handleUsersList: Extraerpage: parseInt(req.query.page, 10) || 1,per_page: 25,search,role,status. Llamar a/admin/userspasando estos parámetros. Armar el objetopaginationconpages_listpara 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 aGET /usersporGET /users/teacherspara poblar el dropdown de docentes.
frontend/views/admin/users/list.html:- Actualizar el markup de paginación para iterar sobre
pagination.pages_listy 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)".
- Actualizar el markup de paginación para iterar sobre
2. Plan de Pruebas Automatizadas
- Pruebas de Backend (
backend/tests/test_pagination_db.py):test_get_users_pagination_defaults: Verificar que/api/v1/usersretornepage=1,per_page=25y las propiedadestotal,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/teachersdevuelva solo usuarios docentes con datos mínimos.test_get_audit_logs_pagination: Validar cálculo correcto de páginas yhas_next/has_prevcon filtrado SQL.test_reservations_sql_filtering: Validar filtros por modalidad y rango temporal con límites.
- Inspección de Linter y Tipado:
- Ejecutar
pyrightsobre todo el backend para garantizar 0 errores (Principio 10).
- Ejecutar