68 lines
4.9 KiB
Markdown
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).
|