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

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)

  1. Incorporar dependencias en requirements.txt: fastapi>=0.115.0, uvicorn[standard]>=0.30.0, httpx>=0.27.0.
  2. Implementar database.py: Adaptar la conexión existente a SQLite/PostgreSQL para proveer SessionLocal y la función generadora get_db() sin alterar los modelos app/models/.
  3. Implementar dependencies.py: Lógica de autenticación que inspeccione la cookie access_token o cabecera Authorization: Bearer <token>, decodifique el JWT con PyJWT y retorne la instancia de User.
  4. Implementar main.py con OpenAPI /docs, /redoc y configuración CORS completa para el puerto :3000 del Frontend BFF.

Fase 2: Schemas Pydantic y Routers Críticos

  1. Módulo Auth (routers/auth.py & schemas/auth.py):
    • /api/v1/auth/login, /logout, /me, /google, /moodle, /impersonate.
    • Set-Cookie de JWT HttpOnly y retorno del payload de usuario idéntico.
  2. Módulo Classrooms & Buildings (routers/classrooms.py & schemas/classrooms.py):
    • Listados de sedes, edificios, pisos y aulas físicas/virtuales con filtros.
  3. 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.
  4. Módulo Dashboard & Cartelera (routers/dashboard.py):
    • Endpoints de agenda diaria/semanal, aulas libres, comisiones sin aula y sincronización de Google Sheets.
  5. Módulo Admin & Auditoría (routers/admin.py):
    • Endpoints de auditoría (AuditLog), ABMs de carreras, materias, comisiones, configuraciones globales y purgas.
  6. 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

  1. Migrar tests/conftest.py y fixtures de testing para instanciar TestClient(app) de FastAPI.
  2. Ejecutar y verificar que los 52 tests existentes pasen con 100% de éxito.
  3. Corregir cualquier advertencia o problema de tipado (@[current_problems]).

Fase 4: Despliegue en Producción

  1. Actualización de script de arranque del servicio systemd en 10.0.0.217 (admin-edu-space-backend.service).
  2. Validación en caliente con el frontend Node.js / Express en https://eduspace.oemspot.com.ar.
  3. Bump semántico de versión a v3.6.0, commit, push a dev y documentación en MEMORY.md y CHANGELOG.md.

4. Riesgos Identificados y Mitigaciones

  1. Riesgo: Sesiones de SQLAlchemy desconectadas o cerradas prematuramente.
    • Mitigación: Utilizar el patrón estándar yield db en el dependency get_db(), asegurando que db.close() se ejecute al completar cada request.
  2. Riesgo: Discrepancias en serialización de fechas (ISO strings vs objetos).
    • Mitigación: Tipar los schemas Pydantic con datetime y serializador explícito ISO 8601 idéntico al emitido por Flask.
  3. 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 cabecera Set-Cookie previa.