feat: release v3.5.0 - formal MVP Bedelia closure, SDD harness, cartelera export, docs cleanup & model fixes
This commit is contained in:
@@ -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`.
|
||||
@@ -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.
|
||||
@@ -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.
|
||||
Reference in New Issue
Block a user