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

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 /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.