7.2 KiB
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
/docsy ReDoc en/redoc. - Servidor Productivo LXC (
10.0.0.217): Entorno de ejecución donde el servicioadmin-edu-space-backendcorrerá bajo servidor ASGI (uvicorn) gestionado porsystemd.
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
HttpOnlyy cabecerasAuthorization: Bearer <token>, manteniendo la trazabilidad íntegra enAuditLog.
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:
main.py: Inicialización de la aplicación FastAPI, configuración de middlewares (CORS, excepción global, auditoría) y montaje de enrutadores.routers/: Enrutadores por dominio agrupados conAPIRouter(auth, classrooms, reservations, students, dashboard, admin, optimizer).schemas/: Modelos de validación de datos de entrada/salida heredando depydantic.BaseModelcon reglasField.storage.py(odatabase.pyymodels/): 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 Entitydetallando 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ónaccess_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 Unauthorizedy 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 con403 Forbiddenante 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 con409 Conflicten 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
uvicornprocesando 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
systemden producción (10.0.0.217) para iniciar conuvicorn main:app --host 0.0.0.0 --port 5000preservando 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.