feat(migration): v3.8.0 - erradicacion total de flask, persistencia nativa sqlalchemy 2.0 y compatibilidad pura fastapi
This commit is contained in:
@@ -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`.
|
||||
@@ -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`.
|
||||
@@ -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`.
|
||||
Reference in New Issue
Block a user