# 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) y `backend/app/forms/` (formularios WTForms). - Dependencia artificial de `Flask` y `Flask-SQLAlchemy` en `backend/app/__init__.py` y `backend/database.py` únicamente para abastecer el contexto de aplicación (`flask_app.app_context()`) que requiere `db.session`. - Dependencias residuales en `requirements.txt`, `setup.py` e `install.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`) y `db.Model` sin 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_db` garantizando 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 a `db.session` o a los modelos ORM, EL SISTEMA ejecutará las consultas de forma directa sin requerir bloques auxiliares `with 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/` y `backend/app/forms/`), consolidando todos los contratos de entrada/salida exclusivamente en los esquemas de Pydantic v2 bajo `backend/schemas/` y los routers de FastAPI bajo `backend/routers/`. - **RF-06 (Ubicuo)**: EL SISTEMA removerá las dependencias obsoletas `Flask`, `Flask-SQLAlchemy`, `Flask-Login`, `Flask-WTF`, `Flask-Migrate`, `Flask-CORS` y `Flask-Babel` de `requirements.txt`, `setup.py` e `install.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 clase `Flask` ni requerir `app.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) 1. Cero ocurrencias de `import flask` o `from flask` en todo el directorio `backend/` (excluyendo únicamente entornos virtuales `.venv`). 2. Directorios obsoletos `backend/app/routes/` y `backend/app/forms/` eliminados del árbol del proyecto. 3. Routers de `backend/routers/` operando sin imports de `get_flask_app` ni bloques `with flask_app.app_context():`. 4. Todos los modelos de `backend/app/models/` y servicios funcionando con el motor nativo de SQLAlchemy 2.0. 5. Cero problemas reportados por el Language Server (`@[current_problems]`). 6. Suite de pruebas pasando al 100% (`57 passed`). 7. Despliegue verificado en producción en `10.0.0.217` con HTTP 200 en `/version`.