feat: alcance temporal configurable en importador y fix multi-carrera en ORM (v3.8.3)

This commit is contained in:
2026-10-19 17:27:36 -03:00
parent 4dd3e30698
commit c14ab0d49f
17 changed files with 682 additions and 39 deletions
@@ -0,0 +1,71 @@
# Plan Técnico: 005-importador-semanas-rango
## 1. Arquitectura y Componentes Afectados
### 1.1. Backend Core (`backend/`)
- **`app/models/subject.py` & `app/models/career.py`**:
- Garantizar `uselist=True` en `Subject.careers` y `Career.subjects` con anotaciones de lista explícitas (`List['Career']`, `List['Subject']`). *(Ya aplicado y verificado)*.
- **`app/services/sheets_importer.py`**:
- Ampliar firma de `sync(...)`:
```python
def sync(
self,
filter_career=None,
filter_subject=None,
filter_day=None,
filter_days=None,
manual_date=None,
single_date_only=False,
weeks_to_generate=16,
date_from=None,
date_to=None,
import_careers=True,
import_subjects=True,
import_commissions=True,
import_classrooms=True,
import_reservations=True,
selected_rows=None
):
```
- Lógica de cálculo de fechas por fila (`dates_to_generate`):
1. Si `row_specific_date` está presente en la fila: `[row_specific_date]`.
2. Si `single_date_only` y `manual_dt`: `[manual_dt]`.
3. Si `date_from_dt` y `date_to_dt`:
Calcular todas las fechas $d$ en el intervalo $[date\_from\_dt, date\_to\_dt]$ tales que $d.weekday() == effective\_day\_idx$.
4. En otro caso (por número de semanas):
Tomar $W = \max(1, \min(30, int(weeks\_to\_generate or 16)))$.
Generar $[base\_monday + timedelta(days=effective\_day\_idx, weeks=w) \text{ para } w \in [0..W-1]]$.
- **`app/services/dashboard_service.py`**:
- En `sync_sheets_data(data)`:
Extraer `weeks_to_generate`, `date_from`, `date_to` del payload y enviarlos al importador.
Reflejar `temporal_mode`, `weeks_to_generate`, `date_from`, `date_to` en las estadísticas retornadas (`stats['filters_applied']`).
- **`routers/admin.py`**:
- Validar los parámetros opcionales en el endpoint `/api/v1/admin/sync-sheets`.
### 1.2. Frontend BFF (`frontend/`)
- **`src/routes/admin.js`**:
- Propagar `weeks_to_generate`, `date_from`, `date_to`, `single_date_only`, `manual_date`, `time_scope_mode` en el payload de sincronización hacia el backend Core.
- **`views/admin/import.html`**:
- Incorporar selector de modalidad temporal mediante controles visuales Bootstrap 5:
- **Modo 1: Por Semanas**: Input numérico para $N$ semanas con badges de selección rápida (1 sem, 4 sem, 8 sem, 16 sem).
- **Modo 2: Rango de Fechas**: Dos campos `date_from` (Desde) y `date_to` (Hasta).
- **Modo 3: Fecha Puntual Única**: `single_date_only` activado con campo de fecha única puntual.
- Sincronización reactiva en JavaScript: al cambiar de modo, se habilitan o deshabilitan los inputs correspondientes y se actualiza el resumen del modal de confirmación.
---
## 2. Estrategia de Pruebas (Test-First)
- Crear `backend/tests/test_sheets_import_temporal_scope.py`:
1. `test_sync_single_date_only_creates_one_reservation()`
2. `test_sync_custom_weeks_count_creates_n_reservations()`
3. `test_sync_date_range_creates_reservations_within_range()`
4. `test_sync_multi_career_assignment_without_sa_instance_state_error()`
- Ejecución completa con `pytest tests -v` (61 tests esperados pasando).
---
## 3. Despliegue y Validación
- Bump a `v3.8.3`.
- Actualizar `CHANGELOG.md` y `MEMORY.md`.
- `git push origin dev` y despliegue SSH a `10.0.0.217`.
- Smoke test HTTP 200 en `/version` y verificación visual en `/admin/import`.
@@ -0,0 +1,41 @@
# Espec: 005-importador-semanas-rango - Selección de Semanas, Rango de Fechas y Fecha Puntual en Importador
## 1. Visión General y Propósito
El importador de Google Sheets oficial de Bedelía actualmente generaba de manera rígida 16 semanas (cuatrimestre completo) o 1 sola asignación cuando se marcaba la opción de fecha puntual.
Bedelía requiere flexibilidad operativa total para poder:
1. **Elegir el número exacto de semanas a importar** (ej. 1, 2, 4, 8, 12, 16 semanas).
2. **Definir un rango de fechas explícito ("Desde" y "Hasta")** para importar reservas que caigan dentro de un período o corte de calendario específico.
3. **Importar ÚNICAMENTE para fecha puntual** (1 sola asignación por fila).
4. Resolver el error de asignación de carreras múltiples en asignaturas (`'list' object has no attribute '_sa_instance_state'`).
---
## 2. Requisitos en Sintaxis EARS (Español Estricto)
### 2.1. Estrategias Temporales de Importación
- **RF-01 (Ubicuo)**: EL SISTEMA dispondrá en la interfaz de Bedelía (`/admin/import`) de tres modos de alcance temporal para la generación de reservas:
1. *Número de Semanas*: Permite ingresar un entero positivo (por defecto 16).
2. *Rango de Fechas (Desde - Hasta)*: Permite ingresar fecha de inicio (`date_from`) y fecha de fin (`date_to`).
3. *Fecha Puntual Única*: Crea 1 sola asignación por fila en la fecha especificada (`manual_date`).
- **RF-02 (Basado en Eventos)**: CUANDO el usuario elija el modo por número de semanas y defina $N$ semanas, EL SISTEMA generará reservas para las primeras $N$ semanas a partir de la fecha base del cuatrimestre o la fecha sugerida.
- **RF-03 (Basado en Eventos)**: CUANDO el usuario elija el modo por rango de fechas (`date_from` y `date_to`), EL SISTEMA calculará todas las fechas que correspondan al día de la semana de cada comisión dentro del intervalo cerrado `[date_from, date_to]` y generará las reservas correspondientes.
- **RF-04 (Basado en Eventos)**: CUANDO el usuario active "Importar ÚNICAMENTE para fecha puntual" (`single_date_only`), EL SISTEMA creará exactamente 1 reserva por fila en la fecha puntual designada.
- **RF-05 (No Deseado / Excepciones)**: SI el usuario ingresa un rango de fechas donde `date_from > date_to`, ENTONCES EL SISTEMA bloqueará la sincronización y mostrará una alerta indicando que la fecha inicial no puede ser posterior a la fecha final.
- **RF-06 (No Deseado / Excepciones)**: SI el número de semanas configurado es menor a 1 o superior a 30, ENTONCES EL SISTEMA limitará automáticamente el valor a los extremos válidos (1 a 30 semanas).
### 2.2. Robustez del Modelo de Asignaturas y Carreras
- **RF-07 (Ubicuo)**: EL SISTEMA preservará la relación Many-to-Many entre `Subject` y `Career` configurada con colección explícita (`uselist=True`), garantizando que la importación de asignaturas multi-carrera (ej. `ASIG00125`) asigne la lista de carreras sin arrojar excepciones de tipo `'list' object has no attribute '_sa_instance_state'`.
---
## 3. Criterios de Aceptación y Finalización (DoD)
1. Selector interactivo en la vista `/admin/import` con opciones claras: "Cuatrimestre / Por Semanas", "Rango de Fechas (Desde - Hasta)" y "Fecha Puntual Única".
2. Endpoint `/api/v1/admin/sync-sheets` y servicio `GoogleSheetsImporter.sync()` procesando `weeks_to_generate`, `date_from`, `date_to`, `manual_date` y `single_date_only`.
3. Pruebas unitarias y de integración que verifiquen:
- Importación con 4 semanas generando exactamente 4 reservas.
- Importación con rango de fechas generando las fechas intermedias exactas.
- Importación con fecha puntual generando 1 sola reserva.
- Importación de materias multi-carrera sin errores de estado en SQLAlchemy.
4. Cero errores en `@[current_problems]` y Pyright (`0 errors, 0 warnings`).
5. Suite de tests automatizados al 100% aprobada.
6. Despliegue en producción institucional verificado en `https://eduspace.oemspot.com.ar`.
@@ -0,0 +1,47 @@
# Tareas de Implementación: 005-importador-semanas-rango
- [x] **Tarea 1: Pruebas Automatizadas (Test-First)**
- Archivo: `backend/tests/test_sheets_import_temporal_scope.py`
- Contenido:
- Test de importación con `single_date_only=True` (1 asignación por fila).
- Test de importación con `weeks_to_generate=4` (4 asignaciones consecutivas).
- Test de importación con rango `date_from` y `date_to` (asignaciones estrictamente dentro del rango).
- Test de importación de materia con múltiples carreras (`ASIG00125` o similar) sin errores de `_sa_instance_state`.
- Hecho cuando: Los tests reflejen la especificación y fallen o validen según corresponda.
- [x] **Tarea 2: Backend Core - Servicio `sheets_importer.py`**
- Archivos: `backend/app/services/sheets_importer.py`
- Contenido:
- Agregar parámetros `weeks_to_generate`, `date_from`, `date_to` a `sync(...)`.
- Implementar parser y normalización de fechas `date_from` y `date_to`.
- Generar fechas correspondientes al día lectivo dentro del intervalo o por cantidad de semanas.
- Exponer en `stats['filters_applied']` la configuración temporal seleccionada.
- Hecho cuando: `sheets_importer.py` genere las fechas precisas según el modo indicado.
- [x] **Tarea 3: Backend Core - Servicio y Routers**
- Archivos: `backend/app/services/dashboard_service.py`, `backend/routers/admin.py`
- Contenido:
- Extraer parámetros temporales en `sync_sheets_data(data)` y pasarlos a `importer.sync(...)`.
- Validar en router que si se envía `date_from` y `date_to`, `date_from <= date_to`.
- Hecho cuando: El endpoint `/api/v1/admin/sync-sheets` acepte y aplique los parámetros temporales.
- [x] **Tarea 4: Frontend BFF e Interfaz de Usuario**
- Archivos: `frontend/src/routes/admin.js`, `frontend/views/admin/import.html`
- Contenido:
- Diseñar bloque de configuración temporal en `import.html` con 3 opciones claras:
1. Por Semanas (Input numérico + badges rápidos: 1, 4, 8, 16 semanas).
2. Rango de Fechas (Campos Desde y Hasta con datepickers).
3. Fecha Puntual Única (Switch `single_date_only` + campo de fecha puntual).
- Manejar la interacción JavaScript para alternar visibilidad o habilitación de campos según la opción elegida.
- Actualizar modal de confirmación mostrando el resumen temporal.
- Adaptar `admin.js` para recibir y enviar los campos en el payload JSON.
- Hecho cuando: Bedelía pueda elegir visualmente semanas, rango o fecha puntual y ver el resultado exacto en el resumen.
- [x] **Tarea 5: Verificación Integral, Cero Diagnósticos y Despliegue**
- Contenido:
- Ejecutar suite completa `pytest tests -v` (100% aprobada).
- Verificar `npx pyright` con 0 errores y 0 advertencias.
- Incrementar versión semántica a `v3.8.3` en backend y frontend.
- Actualizar `CHANGELOG.md` y `MEMORY.md`.
- `git push origin dev` y despliegue SSH a `10.0.0.217` con reinicio de servicios y smoke test HTTP 200 en `/version`.
- Hecho cuando: El servidor de producción esté corriendo `v3.8.3` activo y verificado.