3.9 KiB
3.9 KiB
Espec: 004-depuracion-flask-total - Erradicación Total de Flask y Migración a SQLAlchemy 2.0 Nativo
1. Visión General y Propósito
El backend de admin-edu-space completó la transición a una arquitectura FastAPI ASGI desacoplada y frontend BFF en Node.js/Express. Sin embargo, persisten remanentes de Flask en el repositorio:
- Código muerto en
backend/app/routes/(antiguas vistas Jinja2) ybackend/app/forms/(formularios WTForms). - Dependencia artificial de
FlaskyFlask-SQLAlchemyenbackend/app/__init__.pyybackend/database.pyúnicamente para abastecer el contexto de aplicación (flask_app.app_context()) que requieredb.session. - Dependencias residuales en
requirements.txt,setup.pyeinstall.sh.
Esta especificación formaliza la eliminación completa de toda dependencia de Flask, centralizando la persistencia en SQLAlchemy 2.0 nativo (scoped_session, sessionmaker, declarative_base) e integrándolo de forma transparente con FastAPI.
2. Requisitos en Sintaxis EARS (Español Estricto)
2.1. Persistencia y Sesión de Base de Datos
- RF-01 (Ubicuo): EL SISTEMA gestionará la persistencia y el ciclo de vida de sesiones relacionales mediante SQLAlchemy 2.0 nativo de forma agnóstica a cualquier microframework web, exportando
db.session(scoped_session) ydb.Modelsin requerir ningún contexto de aplicación externo. - RF-02 (Ubicuo): EL SISTEMA inyectará la sesión de base de datos en los routers de FastAPI mediante la dependencia
get_dbgarantizando cierre y rollback seguro ante excepciones no controladas. - RF-03 (Basado en Eventos): CUANDO un router de FastAPI (
backend/routers/*.py) o servicio de negocio acceda adb.sessiono a los modelos ORM, EL SISTEMA ejecutará las consultas de forma directa sin requerir bloques auxiliareswith flask_app.app_context():. - RF-04 (No Deseado / Excepciones): SI ocurre un error durante una transacción en una corrutina o hilo de FastAPI, ENTONCES EL SISTEMA revertirá los cambios pendientes con
session.rollback()y liberará la conexión al pool.
2.2. Depuración de Código Legado y Formularios
- RF-05 (Ubicuo): EL SISTEMA eliminará permanentemente los módulos y directorios obsoletos de Flask (
backend/app/routes/ybackend/app/forms/), consolidando todos los contratos de entrada/salida exclusivamente en los esquemas de Pydantic v2 bajobackend/schemas/y los routers de FastAPI bajobackend/routers/. - RF-06 (Ubicuo): EL SISTEMA removerá las dependencias obsoletas
Flask,Flask-SQLAlchemy,Flask-Login,Flask-WTF,Flask-Migrate,Flask-CORSyFlask-Babelderequirements.txt,setup.pyeinstall.sh.
2.3. Suite de Pruebas y Fixtures
- RF-07 (Basado en Eventos): CUANDO se ejecuten las pruebas automatizadas (
pytest tests -v), EL SISTEMA inicializará el entorno de testing en memoria (sqlite:///:memory:) utilizando el motor y sesión nativos de SQLAlchemy sin instanciar la claseFlaskni requerirapp.test_client(). - RF-08 (Ubicuo): EL SISTEMA mantendrá el 100% de la suite de pruebas unitarias y de integración aprobada (mínimo 57 tests exitosos) sin degradación de cobertura ni regresiones.
3. Criterios de Aceptación y Finalización (DoD)
- Cero ocurrencias de
import flaskofrom flasken todo el directoriobackend/(excluyendo únicamente entornos virtuales.venv). - Directorios obsoletos
backend/app/routes/ybackend/app/forms/eliminados del árbol del proyecto. - Routers de
backend/routers/operando sin imports deget_flask_appni bloqueswith flask_app.app_context():. - Todos los modelos de
backend/app/models/y servicios funcionando con el motor nativo de SQLAlchemy 2.0. - Cero problemas reportados por el Language Server (
@[current_problems]). - Suite de pruebas pasando al 100% (
57 passed). - Despliegue verificado en producción en
10.0.0.217con HTTP 200 en/version.