Files

68 lines
4.9 KiB
Markdown

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