feat(api): migracion completa de Flask API a FastAPI ASGI con arquitectura en 4 capas v3.6.0
This commit is contained in:
@@ -0,0 +1,95 @@
|
||||
# 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.
|
||||
Reference in New Issue
Block a user