feat: release v3.5.0 - formal MVP Bedelia closure, SDD harness, cartelera export, docs cleanup & model fixes

This commit is contained in:
2026-10-16 13:18:02 -03:00
parent 94009ec552
commit 39c80f573b
53 changed files with 767 additions and 32 deletions
+57
View File
@@ -0,0 +1,57 @@
# Plan Técnico 001 — Cierre del MVP de Bedelía
Basado en: `specs/001-cierre-mvp-bedelia/spec.md` y `docs/constitution.md`.
---
## 1. Análisis de Brecha (Gap Analysis)
Al contrastar la especificación `spec.md` con el estado real del repositorio:
- **Flujo de 9 Pasos**: Está implementado en un 95%. Requiere una prueba de recorrido integral (*smoke test*) para asegurar que no haya fallas de integración.
- **Matriz de Conflictos**: 100% implementada y validada en `test_phase2_rules.py`.
- **Cartelera del Día**: Agrupa franjas horarias y soporta filtros de fecha, pero **carece de exportación / impresión limpia**, lo cual fuerza a Bedelía a mantener planillas manuales para entregar a recepción.
- **Exportación / Impresión**: Falta agregar la vista de impresión optimizada (`@media print`) y la descarga directa de CSV/Excel de la agenda áulica del día/semana.
---
## 2. Modificaciones de Archivos y Responsabilidades
### A. Frontend BFF & Vistas
1. `frontend/src/routes/schedule.js`:
- Endpoint `GET /schedule/export_csv`: Genera y descarga un archivo CSV con las columnas: `Fecha`, `Horario`, `Turno`, `Aula / Espacio`, `Piso`, `Materia`, `Código`, `Comisión`, `Carrera`, `Docentes`, `Enlace Virtual`.
- Inyección de cabecera `Content-Type: text/csv; charset=utf-8` y `Content-Disposition: attachment; filename="cartelera_unicaba_YYYY-MM-DD.csv"`.
2. `frontend/views/schedule/today_schedule.html`:
- Incorporar en el encabezado los botones de acción rápida:
- `[ Imprimir Cartelera ]` (dispara `window.print()` con estilos CSS `@media print`).
- `[ Descargar Planilla CSV ]` (enlace directo a `/schedule/export_csv?date=...`).
- Agregar bloque de estilos CSS para impresión:
- Oculta sidebar, navbar, filtros y botones interactivos al imprimir.
- Imprime membrete formal: *"Universidad de la Ciudad de Buenos Aires (UniCABA) - Cartelera de Asignación de Aulas"*.
- Formato de tabla claro, legible y ajustado a hoja A4/Oficio.
3. `frontend/views/dashboard/dashbede.html`:
- Agregar botón de acceso directo *"Exportar Planilla de Hoy"* junto a la agenda operativa de Bedelía.
### B. Backend REST API
1. `backend/app/routes/api/reservations.py` o `backend/app/routes/api/dashboard.py`:
- Asegurar que el endpoint que nutre la agenda retorne la carrera, turno y docentes de forma plana para serialización inmediata.
### C. Suite de Pruebas
1. `backend/tests/test_cartelera_export.py`:
- Prueba unitaria/integración que valide la generación y completitud de datos de agenda diaria y semanal.
---
## 3. Decisiones Técnicas y Alternativas Descartadas
1. **Generación de PDF en Servidor vs. Impresión Nativa del Navegador (`window.print`)**:
- *Alternativa Descartada*: Librería pesada de generación de PDF en Node.js (Puppeteer o PDFKit), que consume más de 200MB de RAM y puede fallar en entornos LXC mínimos.
- *Decisión Adoptada*: Hoja de estilo CSS `@media print` optimizada para el navegador del usuario + exportación de datos crudos en CSV con UTF-8 con BOM (para compatibilidad total con Microsoft Excel en español).
2. **Exportador CSV en Frontend BFF vs. Backend**:
- *Decisión Adoptada*: El Frontend BFF puede construir y enviar el stream CSV directamente a partir de la respuesta del endpoint `/api/v1/dashboard/today-schedule`, reduciendo la carga del backend y aprovechando los formateadores de fecha en español ya existentes.
---
## 4. Cobertura de Requisitos Funcionales
- **RF-1, RF-2**: Verificados mediante el flujo de 9 pasos en UI.
- **RF-3, RF-4, RF-5, RF-6**: Cubiertos por `tests/test_phase2_rules.py`.
- **RF-7, RF-8**: Cubiertos por la nueva funcionalidad de exportación e impresión limpia.
- **RF-9**: Cubierto por el panel de comisiones sin aula en `dashbede.html`.
- **RF-10**: Cubierto por `sheets_importer.py` y `admin.js`.
+84
View File
@@ -0,0 +1,84 @@
# Spec 001 — Cierre y Entrega Definitiva del MVP de Bedelía
Estado: Aprobada para Ejecución
---
## 1. Contexto y Objetivo
El proyecto **Admin Edu-Space** de UniCABA tiene como meta fundacional erradicar el uso del archivo Excel manual que el personal de Bedelía utiliza diariamente para coordinar la asignación de espacios, aulas, comisiones y docentes. Aunque la plataforma cuenta con una arquitectura desacoplada sólida (v3.4.9) y más de 50 pruebas superadas, el equipo percibe que *"el MVP está lejos"* debido a la ausencia de una delimitación estricta de alcance (*Scope Creep*), la falta de herramientas para exportar/imprimir la cartelera diaria requerida en portería y pasillos, y la necesidad de certificar que el circuito operativo de 9 pasos puede ejecutarse de punta a punta sin recurrir a planillas auxiliares.
Esta especificación formaliza el perímetro exacto e inamovible para la entrega del **MVP Productivo de Bedelía**, fijando criterios de aceptación verificables bajo la metodología SDD (**Spec-Driven Development**) y sintaxis **EARS**.
---
## 2. Usuarios / Actores
- **Personal de Bedelía (Actor Primario)**: Administra la asignación física y virtual de aulas, verifica comisiones sin aula, resuelve colisiones horarias y emite los partes de ocupación diarios y semanales.
- **Cuerpo Docente (Actor Secundario)**: Consulta su aula asignada (o enlace Meet), registra notas en el libro de calificaciones y reporta incidencias de aula.
- **Estudiantes (Actor de Consulta)**: Consultan su aula en la cartelera del día y acceden al enlace virtual correspondiente.
- **Administrador del Sistema (Auditor/Soporte)**: Supervisa métricas globales, gestiona usuarios y audita operaciones sensibles en `AuditLog`.
---
## 3. Historias de Usuario
- **HU-1**: Como responsable de Bedelía, quiero gestionar el ciclo académico completo (Sedes, Aulas, Ciclos, Carreras, Materias, Comisiones, Docentes, Alumnos y Reservas) en la plataforma web para no depender de planillas de cálculo.
- **HU-2**: Como responsable de Bedelía, quiero ver en el Dashboard de forma inmediata las aulas libres y las comisiones sin aula del día y la semana para reasignar espacios en menos de tres clics.
- **HU-3**: Como personal de Bedelía, quiero imprimir o exportar a CSV/PDF la cartelera de clases del día y de la semana para entregarla a seguridad/recepción y publicarla en los pasillos de la sede.
- **HU-4**: Como docente, quiero ingresar con mi cuenta institucional y ver exactamente en qué aula física o enlace de Meet me toca dictar clase hoy sin consultar planillas en Bedelía.
- **HU-5**: Como estudiante, quiero consultar la cartelera áulica en mi móvil para saber en qué aula y piso curso hoy de forma inequívoca.
---
## 4. Requisitos Funcionales (Criterios de Aceptación en Notación EARS)
### Módulo 1: Flujo Operativo de 9 Pasos
- **RF-1 (EARS Ubicuo)**: EL SISTEMA mantendrá la integridad referencial relacional entre Sede ➔ Aula ➔ Ciclo Lectivo ➔ Carrera ➔ Materia ➔ Comisión ➔ Docentes (con co-docencia) ➔ Alumnos ➔ Reserva de Espacio en todas las operaciones.
- **RF-2 (EARS Basado en Eventos)**: CUANDO Bedelía cree una comisión desde `/admin/commissions_list`, EL SISTEMA asociará obligatoriamente la Asignatura, heredará y expondrá la Carrera en la interfaz y precargará el Ciclo Lectivo vigente.
- **RF-3 (EARS No Deseado)**: SI un alumno intenta ser matriculado en dos materias regulares en el mismo día, ENTONCES EL SISTEMA bloqueará la operación a menos que la materia sea curso corto (`is_short_course`) o Bedelía marque expresamente `allow_same_day_exception` con motivo justificado.
### Módulo 2: Matriz Infranqueable de Conflictos
- **RF-4 (EARS Basado en Eventos)**: CUANDO el operador intente guardar una reserva que solape físicamente un aula presencial en la misma fecha y bloque horario, EL SISTEMA rechazará la solicitud (HTTP 409) indicando la reserva en conflicto.
- **RF-5 (EARS Basado en Eventos)**: CUANDO se intente asignar una reserva a un docente que ya tiene otra clase presencial simultánea, EL SISTEMA bloqueará la asignación, SALVO que la comisión cuente con co-docencia activa registrada en `commission_teachers`.
- **RF-6 (EARS Basado en Estados)**: MIENTRAS la reserva corresponda al entorno `Campus Virtual (VIRTUAL)`, EL SISTEMA permitirá la concurrencia de múltiples comisiones en el mismo horario con enlaces de Google Meet independientes.
### Módulo 3: Cartelera, Aulas Libres y Exportación
- **RF-7 (EARS Basado en Eventos)**: CUANDO Bedelía o recepción consulte `/schedule/today_schedule`, EL SISTEMA agrupará las reservas por franja horaria real de cursada (`08:00 - 11:00 hs`, etc.), ordenadas cronológicamente y sin duplicaciones de fila.
- **RF-8 (EARS Ubicuo)**: EL SISTEMA dispondrá de un botón de exportación rápida a formato descargable (CSV estructurado) e impresión limpia (CSS print-friendly) en la Cartelera del Día y Semanal para emisión física inmediata.
- **RF-9 (EARS Basado en Estados)**: MIENTRAS existan comisiones sin espacio asignado para la fecha seleccionada, EL SISTEMA las listará en la pestaña *"Comisiones Sin Asignar"* del Dashboard de Bedelía con acceso directo al formulario de asignación en 1 clic.
### Módulo 4: Importación y Respaldo
- **RF-10 (EARS Opcional)**: DONDE Bedelía requiera importar masivamente la oferta cuatrimestral desde Google Sheets, EL SISTEMA proveerá previsualización interactiva con filtros por Carrera, Materia y Día antes de impactar en la base de datos.
---
## 5. Requisitos No Funcionales (RNF)
- **RNF-1 (Seguridad)**: Toda sesión de usuario debe gestionarse mediante JWT en cookie `HttpOnly` y registrarse en `AuditLog`.
- **RNF-2 (Rendimiento)**: Las consultas del Dashboard y Cartelera del Día deben responder en menos de 500 ms con una concurrencia estimada de 200 usuarios concurrentes.
- **RNF-3 (Compatibilidad)**: Interfaz adaptativa (Responsive) optimizada para terminales móviles (375px) y pantallas de recepción (1920x1080).
- **RNF-4 (Idioma)**: Todo mensaje, etiqueta, alerta y reporte debe estar redactado en español institucional rioplatense.
---
## 6. Casos Límite y Reglas Especiales
1. **Reinicio de Ciclo Lectivo**: Si la base se reinicia o está vacía, ninguna vista debe arrojar error 500; deben mostrarse componentes de estado vacío (*empty states*) con llamada a la acción clara.
2. **Asignaturas Compartidas**: Si una materia pertenece a múltiples carreras (Many-to-Many en `subject_careers`), la cartelera y el detalle de comisión deben exhibir todas las titulaciones asociadas.
3. **Pisos Alfanuméricos**: Aulas ubicadas en pisos no numéricos (PB, EP, Subsuelo, Piso 1) deben agruparse correctamente en los selectores en cascada.
---
## 7. FUERA DE ALCANCE (Out of Scope para el MVP)
Para garantizar la entrega inmediata y evitar demoras innecesarias, los siguientes aspectos quedan formalmente **excluidos** de esta entrega y se derivan a la Fase 6 / Roadmap v4.0:
- ❌ Sincronización continua de dos vías en segundo plano con Moodle WebServices mediante Daemons systemd persistentes (la importación inicial y SSO cubren la necesidad del MVP).
- ❌ Aplicación móvil nativa compilada para Android/iOS (el diseño web responsive cubre el 100% del acceso móvil).
- ❌ Módulo de pagos o aranceles de matrícula.
- ❌ Gestión de inventario de activos físicos dentro de las aulas (PCs, proyectores, cables HDMI).
---
## 8. Criterios de Finalización (Definition of Done)
El MVP se considerará **100% ENTREGADO** cuando:
1. [ ] El flujo completo de 9 pasos de Bedelía pueda ser ejecutado por un operador sin errores en consola ni en logs.
2. [ ] La cartelera del día cuente con el botón de **Impresión / Exportación** funcionando.
3. [ ] Todas las 52 pruebas automatizadas de backend (`pytest tests -v`) pasen en verde.
4. [ ] La suite de auditoría de seguridad (`security_audit.bat`) no registre vulnerabilidades críticas.
5. [ ] La versión esté desplegada y verificada en el servidor de producción institucional (`https://eduspace.oemspot.com.ar`).
6. [ ] La memoria del proyecto (`MEMORY.md`) y el `CHANGELOG.md` queden actualizados reflejando el cierre del MVP.
+37
View File
@@ -0,0 +1,37 @@
# Tareas de Implementación 001 — Cierre del MVP de Bedelía
Basado en: `specs/001-cierre-mvp-bedelia/spec.md` y `plan.md`.
---
## Lista de Tareas Atómicas
- [x] **T1 — Endpoint de Exportación CSV en Frontend BFF (`/schedule/export_csv`)**
- **Archivos:** `frontend/src/routes/schedule.js`
- **RF Cubiertos:** RF-8
- **Descripción:** Implementar el endpoint que toma el parámetro `date` (o fecha actual), consulta el cronograma real de la API backend, y retorna un archivo CSV estructurado con cabeceras en español (`Fecha`, `Horario`, `Turno`, `Aula`, `Piso`, `Materia`, `Código`, `Comisión`, `Carrera`, `Docentes`, `Modalidad/Meet`) y prefijo UTF-8 BOM (`\uFEFF`) para compatibilidad directa con Microsoft Excel.
- **Hecho cuando:** Una petición GET a `/schedule/export_csv?date=2026-10-16` responda con HTTP 200, cabecera `Content-Disposition: attachment` y el contenido CSV formateado con las reservas del día.
- [x] **T2 — Botones de Impresión y Descarga en Cartelera del Día (`today_schedule.html`)**
- **Archivos:** `frontend/views/schedule/today_schedule.html`
- **RF Cubiertos:** RF-7, RF-8
- **Descripción:** Añadir en la barra superior de acciones de la cartelera los botones `Imprimir Cartelera` (icono `bi-printer`, ejecuta `window.print()`) y `Descargar Planilla CSV` (icono `bi-file-earmark-excel`). Agregar estilos `@media print` para ocultar la barra lateral, botones y pie de página, mostrando un membrete institucional limpio para recepción.
- **Hecho cuando:** Al presionar `Imprimir`, la vista previa de impresión muestre únicamente la grilla de asignaciones sin elementos de navegación, y al presionar `Descargar Planilla`, se descargue el archivo `.csv`.
- [x] **T3 — Botón de Exportación en Dashboard de Bedelía (`dashbede.html`)**
- **Archivos:** `frontend/views/dashboard/dashbede.html`
- **RF Cubiertos:** RF-8, RF-9
- **Descripción:** Agregar un botón destacado de exportación en la sección de Cartelera & Agenda de Bedelía para descargar o imprimir el parte del día en 1 clic.
- **Hecho cuando:** El botón sea visible en el Dashboard de Bedelía y redirija a la descarga o apertura de la cartelera imprimible.
- [x] **T4 — Verificación de Calidad y Pruebas Automatizadas**
- **Archivos:** `backend/tests/`
- **RF Cubiertos:** Todos (RF-1 al RF-10)
- **Descripción:** Ejecutar la suite completa de pruebas del backend (`python -m pytest tests -v`) verificando 0 fallos.
- **Hecho cuando:** La suite ejecute 52 tests y reporte 100% passed.
- [x] **T5 — Cierre de Versión, Actualización de Memoria y Principio 9 de la Constitución**
- **Archivos:** `package.json`, `app.js`, `backend/__init__.py`, `MEMORY.md`, `CHANGELOG.md`
- **RF Cubiertos:** RNF-1, RNF-4, Principio 9
- **Descripción:** Incrementar la versión semántica a `v3.5.0` (Cierre Formal MVP Bedelía), registrar las decisiones en `MEMORY.md` y detallar los cambios en `CHANGELOG.md`.
- **Hecho cuando:** La versión `v3.5.0` esté registrada en todos los descriptores y el reporte final esté listo para despliegue.