Files

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) 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.