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