6.1 KiB
6.1 KiB
Plan Técnico 003 — Migración de Flask API a FastAPI
Basado en: specs/003-migracion-fastapi/spec.md, docs/constitution.md (Principios 9, 10 y 11) y AGENTS.md.
1. Análisis de Situación y Mapeo Tecnológico
| Componente Flask Actual | Equivalente FastAPI Objetivo | Ubicación / Archivo |
|---|---|---|
Flask(app) + wsgi.py |
FastAPI(app) + uvicorn |
backend/main.py y backend/asgi.py |
Flask-CORS |
CORSMiddleware nativo |
backend/main.py |
Flask-SQLAlchemy (db.session) |
sqlalchemy.orm.Session con get_db generator |
backend/app/database.py o backend/storage.py |
Blueprints (app.routes.api.*) |
APIRouter(prefix="/api/v1/...", tags=[...]) |
backend/routers/ |
| Validación ad-hoc / diccionarios | pydantic.BaseModel con Field |
backend/schemas/ |
SecurityFilterChain / JWT cookies |
Depends(get_current_user) / Depends(require_roles) |
backend/security/auth.py |
flask.jsonify(...) |
Retorno nativo de dicts / Pydantic models (status_code automático) | routers/*.py |
Manejo de errores abort(...) |
raise HTTPException(status_code, detail=...) |
En todos los routers |
Pruebas pytest con client.get(...) |
pytest con starlette.testclient.TestClient o httpx.AsyncClient |
backend/tests/ |
2. Estructura de Capas Objetivo (Principio 11)
backend/
├── main.py # Bootstrap FastAPI, middlewares CORS/Audit, registro de routers
├── asgi.py # Entrypoint ASGI para producción (uvicorn asgi:app)
├── database.py / storage.py # Engine SQLAlchemy, sessionmaker y dependencia get_db
├── dependencies.py # Inyección de dependencias (get_current_user, require_roles, db)
├── schemas/ # Contratos Pydantic v2 (BaseModel, Field)
│ ├── auth.py
│ ├── classrooms.py
│ ├── reservations.py
│ ├── students.py
│ ├── dashboard.py
│ └── admin.py
├── routers/ # APIRouters modulares por dominio
│ ├── auth.py # /api/v1/auth
│ ├── classrooms.py # /api/v1/classrooms
│ ├── reservations.py # /api/v1/reservations
│ ├── students.py # /api/v1/students
│ ├── dashboard.py # /api/v1/dashboard
│ ├── admin.py # /api/v1/admin
│ └── optimizer.py # /api/v1/optimizer y /api/genetic
├── app/ # Modelos SQLAlchemy relacionales y servicios existentes
│ ├── models/ # Modelos relacionales existentes (User, Classroom, Reservation, etc.)
│ └── services/ # MoodleClient, CacheService, AuditService, EmailService, etc.
└── tests/ # Suite de tests adaptada a TestClient de FastAPI
3. Estrategia de Migración Modular sin Rupturas
Fase 1: Entorno, Dependencias y Núcleo Base (Capa 1 y Capa 4)
- Incorporar dependencias en
requirements.txt:fastapi>=0.115.0,uvicorn[standard]>=0.30.0,httpx>=0.27.0. - Implementar
database.py: Adaptar la conexión existente a SQLite/PostgreSQL para proveerSessionLocaly la función generadoraget_db()sin alterar los modelosapp/models/. - Implementar
dependencies.py: Lógica de autenticación que inspeccione la cookieaccess_tokeno cabeceraAuthorization: Bearer <token>, decodifique el JWT con PyJWT y retorne la instancia deUser. - Implementar
main.pycon OpenAPI/docs,/redocy configuración CORS completa para el puerto:3000del Frontend BFF.
Fase 2: Schemas Pydantic y Routers Críticos
- Módulo Auth (
routers/auth.py&schemas/auth.py):/api/v1/auth/login,/logout,/me,/google,/moodle,/impersonate.- Set-Cookie de JWT
HttpOnlyy retorno del payload de usuario idéntico.
- Módulo Classrooms & Buildings (
routers/classrooms.py&schemas/classrooms.py):- Listados de sedes, edificios, pisos y aulas físicas/virtuales con filtros.
- Módulo Reservations & Matriz de Conflictos (
routers/reservations.py&schemas/reservations.py):- Endpoints
/api/v1/reservations, verificación de conflictos de aula presencial, aforo, docentes y restricción de alumnos.
- Endpoints
- Módulo Dashboard & Cartelera (
routers/dashboard.py):- Endpoints de agenda diaria/semanal, aulas libres, comisiones sin aula y sincronización de Google Sheets.
- Módulo Admin & Auditoría (
routers/admin.py):- Endpoints de auditoría (
AuditLog), ABMs de carreras, materias, comisiones, configuraciones globales y purgas.
- Endpoints de auditoría (
- Módulo Optimizador IA (
routers/optimizer.py):- Endpoints de comisiones, previsualización y aplicación del algoritmo genético.
Fase 3: Suite de Pruebas y Tolerancia Cero
- Migrar
tests/conftest.pyy fixtures de testing para instanciarTestClient(app)de FastAPI. - Ejecutar y verificar que los 52 tests existentes pasen con 100% de éxito.
- Corregir cualquier advertencia o problema de tipado (
@[current_problems]).
Fase 4: Despliegue en Producción
- Actualización de script de arranque del servicio systemd en
10.0.0.217(admin-edu-space-backend.service). - Validación en caliente con el frontend Node.js / Express en
https://eduspace.oemspot.com.ar. - Bump semántico de versión a
v3.6.0, commit, push adevy documentación enMEMORY.mdyCHANGELOG.md.
4. Riesgos Identificados y Mitigaciones
- Riesgo: Sesiones de SQLAlchemy desconectadas o cerradas prematuramente.
- Mitigación: Utilizar el patrón estándar
yield dben el dependencyget_db(), asegurando quedb.close()se ejecute al completar cada request.
- Mitigación: Utilizar el patrón estándar
- Riesgo: Discrepancias en serialización de fechas (ISO strings vs objetos).
- Mitigación: Tipar los schemas Pydantic con
datetimey serializador explícito ISO 8601 idéntico al emitido por Flask.
- Mitigación: Tipar los schemas Pydantic con
- Riesgo: Incompatibilidad de cookies con el cliente Axios en Node.js.
- Mitigación: Usar
response.set_cookie(key="access_token", value=token, httponly=True, samesite="lax", path="/")reproduciendo exactamente la cabeceraSet-Cookieprevia.
- Mitigación: Usar