# 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 `, 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.