feat(migration): v3.8.0 - erradicacion total de flask, persistencia nativa sqlalchemy 2.0 y compatibilidad pura fastapi

This commit is contained in:
2026-10-19 15:49:50 -03:00
parent ae071d7f72
commit 5ed62d5d30
56 changed files with 3706 additions and 12756 deletions
+61
View File
@@ -0,0 +1,61 @@
# Plan Técnico: 004-depuracion-flask-total - Erradicación Total de Flask y Migración a SQLAlchemy 2.0 Nativo
## 1. Arquitectura de la Solución
### 1.1. Capa de Persistencia Nativa (`backend/database.py` y `backend/app/__init__.py`)
Actualmente, los modelos (`Building`, `Classroom`, `User`, etc.) importan `db` desde `app` (`from app import db`), y dependen de propiedades como `db.Model`, `db.Column`, `db.relationship` y `db.session`.
Para desacoplarlo de Flask sin tener que reescribir manualmente cada modelo:
- Diseñamos una clase/adaptador `SQLAlchemyWrapper` en `backend/database.py` (o en `backend/app/db.py` reexportado en `app/__init__.py`) construido 100% sobre SQLAlchemy 2.0 estándar:
- `engine = create_engine(DATABASE_URL, pool_pre_ping=True, ...)`
- `SessionLocal = sessionmaker(autocommit=False, autoflush=False, bind=engine)`
- `session = scoped_session(SessionLocal)`
- `Model = declarative_base()`
- Reexporta directamente tipos de SQLAlchemy: `Column = sa.Column`, `Integer = sa.Integer`, `String = sa.String`, `relationship = orm.relationship`, etc.
- Métodos `create_all()` y `drop_all()` ejecutados directamente contra `engine`.
- En `backend/database.py`, la dependencia FastAPI `get_db()` yieldará la sesión nativa:
```python
def get_db():
db_session = SessionLocal()
try:
yield db_session
finally:
db_session.close()
```
- Ya no existirá `get_flask_app()` ni necesidad de `flask_app.app_context()`.
### 1.2. Limpieza de Routers (`backend/routers/*.py`)
- Remover:
```python
from database import get_flask_app
flask_app = get_flask_app()
```
- Remover envoltorios `with flask_app.app_context():`.
- Las consultas accederán directamente a `db.session` (que es el `scoped_session` nativo de SQLAlchemy) o a la dependencia inyectada `db: Session = Depends(get_db)`.
### 1.3. Poda de Archivos y Directorios Legados
- Eliminar recursivamente:
- `backend/app/routes/` (antiguo monolito Jinja2 y APIs de Flask).
- `backend/app/forms/` (formularios WTForms).
- Modificar:
- `install.sh`: eliminar `flask` de la verificación de dependencias.
- `backend/requirements.txt`: remover `Flask`, `Flask-SQLAlchemy`, `Flask-Login`, `Flask-WTF`, `Flask-Migrate`, `Flask-CORS`, `Flask-Babel`.
- `backend/setup.py`: remover las mismas dependencias de `install_requires`.
- `backend/app/__init__.py`: eliminar imports de Flask, `request`, `session`, `Babel`, `Migrate`, `CORS` y el registro de blueprints de Flask.
### 1.4. Actualización del Arnés de Tests (`backend/tests/conftest.py`)
- Modificar `conftest.py` para inicializar SQLAlchemy en memoria (`sqlite:///:memory:`) sin depender de `create_app()` de Flask.
- Los tests que hacían peticiones HTTP utilizarán `fastapi.testclient.TestClient` apuntando a `backend.main:app`.
---
## 2. Fases de Ejecución
1. **Fase 1: Motor SQLAlchemy 2.0 Desacoplado**:
Implementar la capa nativa de base de datos en `backend/database.py` y actualizar `backend/app/__init__.py`.
2. **Fase 2: Retiro de `app_context()` en Routers y Servicios**:
Eliminar `get_flask_app()` y `with flask_app.app_context():` de los routers de FastAPI.
3. **Fase 3: Eliminación de Código Muerto y Dependencias**:
Borrar carpetas `app/routes/` y `app/forms/`. Actualizar `requirements.txt`, `setup.py` e `install.sh`.
4. **Fase 4: Adaptación de Tests y Verificación**:
Actualizar `conftest.py` y correr la suite completa de 57 tests.
5. **Fase 5: Despliegue y Validación en Producción**:
Bump de versión, commit, git push a `dev` y despliegue a LXC `10.0.0.217`.
+38
View File
@@ -0,0 +1,38 @@
# 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`.
+27
View File
@@ -0,0 +1,27 @@
# Desglose de Tareas: 004-depuracion-flask-total - Erradicación Total de Flask
## Tareas de Implementación
- [X] **Tarea 1: Capa de Persistencia Nativa SQLAlchemy 2.0 en `backend/database.py` y `backend/app/__init__.py`**
- **Objetivo**: Crear adaptador nativo de SQLAlchemy (SessionLocal, scoped_session, Base declarativa, alias de tipos y session) y reexportarlo en `app.__init__.py` eliminando la inicialización de `Flask` y `Flask-SQLAlchemy`.
- **Hecho cuando**: Los modelos en `backend/app/models/` puedan importarse e interactuar con `db.session` y `db.Model` sin lanzar `RuntimeError: Working outside of application context`.
- [X] **Tarea 2: Eliminar `flask_app.app_context()` y `get_flask_app` de los Routers FastAPI**
- **Objetivo**: Limpiar `backend/routers/` (`academic.py`, `admin.py`, `buildings.py`, `classrooms.py`, `dashboard.py`, `reservations.py`, `auth.py`) retirando los envoltorios `with flask_app.app_context():`.
- **Hecho cuando**: Ningún archivo en `backend/routers/` contenga `flask_app` ni `get_flask_app`.
- [X] **Tarea 3: Poda de Código Muerto (`app/routes/` y `app/forms/`)**
- **Objetivo**: Eliminar permanentemente los directorios `backend/app/routes/` y `backend/app/forms/`.
- **Hecho cuando**: Los directorios ya no existan en el sistema de archivos y no queden imports rotos en el proyecto.
- [X] **Tarea 4: Depuración de Scripts y Dependencias Residuales de Flask**
- **Objetivo**: Actualizar `install.sh`, `backend/requirements.txt` y `backend/setup.py` retirando `Flask`, `Flask-SQLAlchemy`, `Flask-WTF`, `Flask-Login`, `Flask-Migrate`, `Flask-CORS`, `Flask-Babel`.
- **Hecho cuando**: No haya referencias a librerías de Flask en los archivos de configuración y manifiestos de instalación.
- [X] **Tarea 5: Adaptación de Fixtures en `backend/tests/conftest.py` y Verificación de Suite de Pruebas**
- **Objetivo**: Ajustar `conftest.py` para usar el motor de base de datos nativo y correr la suite de tests completa (`pytest tests -v`).
- **Hecho cuando**: Los 57 tests automatizados pasen al 100% (0 errores, 0 fallos) y `@[current_problems]` reporte 0 problemas.
- [X] **Tarea 6: Bump Semántico, Git Push y Despliegue en Producción**
- **Objetivo**: Seguir la skill `deploy` y Principio 9 de la Constitución para incrementar versión a `3.8.0`, actualizar `CHANGELOG.md` y `MEMORY.md`, push a `dev` y desplegar a `10.0.0.217`.
- **Hecho cuando**: El endpoint remoto `/version` retorne HTTP 200 con versión `3.8.0` y estado `ok`.