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
+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.