Files
admin-edu-space/specs/003-migracion-fastapi/spec.md
T

69 lines
7.2 KiB
Markdown

# Spec 003 — Migración de Backend Core de Flask API a FastAPI
Estado: En Planificación / Propuesta SDD
---
## 1. Contexto y Objetivo
El backend de **Admin Edu-Space** fue construido inicialmente sobre Flask 3.1. Con la evolución del sistema hacia la versión 3.5.x, la incorporación del **Principio 11 de la Constitución** (estándares modernos de APIs, arquitectura modular en 4 capas, tipado estricto con Pydantic y soporte asíncrono para inferencias con LLMs) y la necesidad de maximizar la concurrencia operativa, se determinó la migración del Core REST API de Flask a **FastAPI**.
Esta especificación formaliza los requisitos, alcance, criterios de compatibilidad y arquitectura objetivo de la migración, garantizando **cero disrupción** para el Frontend BFF (Express.js / Axios) y preservando el 100% de la lógica de negocio académica (circuito de 9 pasos de Bedelía, matriz de conflictos, sincronización con Moodle y Google Sheets).
---
## 2. Usuarios y Sistemas Afectados
- **Frontend BFF (Node.js/Express.js)**: Consumidor principal de la API REST bajo `/api/v1/`. Espera contratos JSON idénticos, códigos de respuesta semánticos y manejo de cabeceras de autorización JWT.
- **Personal de Bedelía y Gestión Académica**: Usuarios operativos que interactúan a través de la UI para administrar sedes, aulas, ciclos, carreras, materias, comisiones y reservas.
- **Cuerpo Docente y Estudiantes**: Usuarios que consultan agendas, carteleras y aulas virtuales.
- **Desarrolladores y Auditores**: Acceso a la documentación interactiva Swagger UI en `/docs` y ReDoc en `/redoc`.
- **Servidor Productivo LXC (`10.0.0.217`)**: Entorno de ejecución donde el servicio `admin-edu-space-backend` correrá bajo servidor ASGI (`uvicorn`) gestionado por `systemd`.
---
## 3. Historias de Usuario
- **HU-1**: Como desarrollador y mantenedor, quiero que la API Core esté construida sobre FastAPI con contratos fuertemente tipados mediante Pydantic para validar entradas automáticamente y generar documentación interactiva OpenAPI en tiempo real.
- **HU-2**: Como desarrollador frontend (BFF Express), quiero que todos los endpoints de `/api/v1/` mantengan intacta su estructura de rutas, parámetros y payloads JSON para que la interfaz web continúe funcionando sin modificar el código de vistas ni controladores Express.
- **HU-3**: Como administrador del sistema, quiero que la API gestione las peticiones concurrentes mediante ASGI asíncrono de alto rendimiento para soportar picos de consulta en carteleras y llamadas prolongadas a modelos de IA locales sin degradar la respuesta del servidor.
- **HU-4**: Como oficial de seguridad, quiero que la autenticación continúe operando mediante JWT en cookies `HttpOnly` y cabeceras `Authorization: Bearer <token>`, manteniendo la trazabilidad íntegra en `AuditLog`.
---
## 4. Requisitos Funcionales (Notación EARS)
### Módulo 1: Arquitectura y Compatibilidad de Contratos
- **RF-1 (EARS Ubicuo)**: EL SISTEMA mantendrá la totalidad de las rutas de la API bajo el prefijo `/api/v1/` retornando exclusivamente respuestas JSON estructuradas con compatibilidad 100% con las llamadas de Axios del Frontend BFF.
- **RF-2 (EARS Ubicuo)**: EL SISTEMA estructurará el backend en 4 capas desacopladas:
1. `main.py`: Inicialización de la aplicación FastAPI, configuración de middlewares (CORS, excepción global, auditoría) y montaje de enrutadores.
2. `routers/`: Enrutadores por dominio agrupados con `APIRouter` (auth, classrooms, reservations, students, dashboard, admin, optimizer).
3. `schemas/`: Modelos de validación de datos de entrada/salida heredando de `pydantic.BaseModel` con reglas `Field`.
4. `storage.py` (o `database.py` y `models/`): Gestión de sesiones de base de datos SQLAlchemy ORM y persistencia.
- **RF-3 (EARS Basado en Eventos)**: CUANDO el usuario o cliente HTTP envíe una petición con datos que no cumplan las restricciones declaradas en los esquemas Pydantic, EL SISTEMA responderá automáticamente con código `422 Unprocessable Entity` detallando el campo exacto y la regla infringida.
### Módulo 2: Autenticación, Seguridad y Roles (RBAC)
- **RF-4 (EARS Basado en Eventos)**: CUANDO un usuario envíe credenciales válidas a `/api/v1/auth/login`, EL SISTEMA emitirá un token JWT firmado y lo retornará tanto en el cuerpo JSON como en la cookie de sesión `access_token` (`HttpOnly`, `SameSite=Lax`).
- **RF-5 (EARS No Deseado)**: SI una petición intenta acceder a un endpoint protegido sin un token JWT válido o expirado, ENTONCES EL SISTEMA rechazará el acceso con código `401 Unauthorized` y registrará el incidente en auditoría si corresponde.
- **RF-6 (EARS Basado en Estados)**: MIENTRAS una ruta protegida requiera roles específicos (ej. `ADMIN`, `Bedelia`), EL SISTEMA verificará los privilegios del token mediante inyección de dependencias (`Depends(require_roles([...]))`), respondiendo con `403 Forbidden` ante privilegios insuficientes.
### Módulo 3: Lógica Académica y Matriz de Conflictos
- **RF-7 (EARS Basado en Eventos)**: CUANDO se intente registrar o modificar una reserva en `/api/v1/reservations`, EL SISTEMA ejecutará la validación de la matriz integral de conflictos (físico, docente con excepción de co-docencia, aforo y restricción diaria del estudiante), respondiendo con `409 Conflict` en caso de colisión no autorizada.
- **RF-8 (EARS Basado en Estados)**: MIENTRAS una comisión sea de modalidad virtual (`Campus Virtual`), EL SISTEMA permitirá la concurrencia horaria de múltiples reservas sin colisión física.
### Módulo 4: Documentación y Asistencia con IA
- **RF-9 (EARS Ubicuo)**: EL SISTEMA expondrá contratos OpenAPI v3 interactivos en `/docs` (Swagger UI) y `/redoc` (ReDoc) permitiendo probar los endpoints en vivo con autenticación Bearer/Cookie.
- **RF-10 (EARS Opcional)**: DONDE se invoque inferencia de modelos de IA locales (LLMs) o sincronizaciones externas (Moodle / Google Sheets), EL SISTEMA ejecutará las llamadas utilizando clientes asíncronos no bloqueantes (`httpx.AsyncClient`) con timeouts de hasta 600 segundos.
---
## 5. Requisitos No Funcionales (RNF)
- **RNF-1 (Rendimiento ASGI)**: El servidor debe ejecutarse sobre `uvicorn` procesando un mínimo de 1.000 peticiones por segundo en endpoints livianos y latencias inferiores a 50 ms.
- **RNF-2 (Tolerancia Cero a Errores - Principio 10)**: El código migrado debe contar con cero errores de análisis estático (`@[current_problems]`), tipos estrictos y passing total en la suite de pruebas.
- **RNF-3 (Compatibilidad de Base de Datos)**: Se mantendrá el esquema relacional existente en PostgreSQL / SQLite (`classrooms_db`) sin migraciones destructivas ni pérdida de datos.
- **RNF-4 (Despliegue Continuo - Principio 9)**: La migración incluirá la actualización del servicio `systemd` en producción (`10.0.0.217`) para iniciar con `uvicorn main:app --host 0.0.0.0 --port 5000` preservando el puerto :5000 para no requerir cambios en Nginx ni en el BFF.
---
## 6. Fuera de Alcance
- Modificar las vistas o controladores del Frontend BFF Express (salvo ajustes de configuración si fueran estrictamente necesarios).
- Modificar el esquema de tablas o estructura de datos en PostgreSQL/SQLite.
- Reescribir los algoritmos de optimización genéticos más allá de adaptarlos como dependencias asíncronas en FastAPI.