feat(bedelia): associate careers to commissions and subjects, clean dashboard mock fallbacks, and update SSD documentation

This commit is contained in:
2026-10-07 17:02:56 -03:00
parent 1e6f493358
commit 8dc055cd1e
18 changed files with 564 additions and 318 deletions
+156
View File
@@ -0,0 +1,156 @@
# CHANGELOG MVP — Admin Edu-Space (UniCABA)
> **Nota de Unificación:** Este archivo documenta la progresión de los hitos y entregables de las Fases del [ROADMAP_MVP.md](./ROADMAP_MVP.md). Para el historial técnico exhaustivo conforme a *Keep a Changelog* y *Semantic Versioning*, consultar el archivo oficial unificado: **[CHANGELOG.md](./CHANGELOG.md)**.
---
## [Fase 5: Integración Auth, Email & Moodle Backend] — v3.0.0 (2026-09-23)
**Estado:** ✅ 100% Completada
### Épica 1: Panel de Configuración Global (Perfil ADMIN)
* **Cifrado Simétrico Fernet:** Creación de `CryptoService` (`backend/app/services/crypto_service.py`) derivando de forma determinística una clave Fernet de 32 bytes a partir de `SECRET_KEY`.
* **Modelo `SystemSetting` Extendido:** Soporte para columnas `category` y flag `is_encrypted`. Almacenamiento seguro de secretos con métodos polimórficos `get_decrypted_value()` y enmascaramiento con `get_masked_value()`.
* **Endpoints Administrativos:**
- `GET /api/v1/admin/settings/all`: Retorna la configuración completa organizada por categorías (`smtp`, `auth_providers`, `google_oauth`, `moodle`) con secretos enmascarados.
- `POST /api/v1/admin/settings/smtp`: Configuración dinámica de Host, Puerto, Usuario, Contraseña cifrada, Protocolo de Seguridad (TLS/SSL/NONE), y Remitente.
- `POST /api/v1/admin/settings/smtp/test`: Handshake SMTP en vivo y envío opcional de correo de prueba con plantilla HTML oficial.
- `POST /api/v1/admin/settings/auth-providers`: Activación y desactivación de proveedores de acceso (`local`, `google`, `moodle`).
- `POST /api/v1/admin/settings/google-oauth`: Guardado de Client ID, Client Secret cifrado, Dominios autorizados y Callback URL.
- `POST /api/v1/admin/settings/moodle`: URL base del servidor, Token Web Services cifrado, timeout y frecuencia de sincronización.
* **Interfaz de Usuario Web:** Nueva pantalla responsiva `frontend/views/admin/settings/global_config.html` con pestañas navegables, validación en vivo, spinners y monitores de estado (100% adaptada para resoluciones desde 720p hasta 1080p).
* **Navegación:** Integración de enlace directo *"Config. Global"* en el menú lateral bajo Administración en `frontend/views/base.html`.
### Épica 2: Infraestructura Asíncrona y Caché
* **Capa de Caché Híbrida:** Creación de `CacheService` (`backend/app/services/cache_service.py`) con soporte nativo de Redis y fallback transparente en memoria con TTL para sesiones de usuario y perfiles de Moodle.
* **Cola Persistente de Sincronización:** Modelo `MoodleSyncTask` (`backend/app/models/sync_task.py`) y servicio `MoodleQueueService` (`backend/app/services/moodle_queue_service.py`) para registrar operaciones de sincronización (`CREATE_USER`, `UPDATE_USER`, `ENROL_USER`, `UNENROL_USER`, `ASSIGN_ROLE`).
* **Tolerancia a Fallos y DLQ:** Política de Exponential Backoff ($2^{\text{intentos}} \times 30$s) ante indisponibilidad de Moodle. Si se superan los intentos máximos, la tarea se traslada automáticamente a la **Dead Letter Queue (DLQ)** (`status = 'FAILED'`).
* **Endpoints de Cola & DLQ:**
- `GET /api/v1/admin/moodle/queue/stats`: Métricas en tiempo real (Pendientes, En Proceso, Reintentando, Completadas, Fallidas DLQ).
- `GET /api/v1/admin/moodle/queue/tasks`: Lista paginada con filtrado por estado.
- `POST /api/v1/admin/moodle/queue/process-now`: Disparo manual inmediato de sincronización.
- `POST /api/v1/admin/moodle/queue/tasks/<id>/retry`: Reintento de tarea individual de DLQ.
- `POST /api/v1/admin/moodle/queue/retry-all`: Reintento masivo de todas las tareas en DLQ.
### Épica 3: Sistema de Autenticación Híbrida (SSO & Local)
* **Login Local Refactorizado:** Endpoint `/api/v1/auth/login` respeta la configuración global. Si `auth_local_enabled` está desactivado, sólo admite acceso de contingencia a usuarios con rol `ADMIN`.
* **Google OAuth 2.0 (Arquitectura AlumnosLS):** Endpoint `POST /api/v1/auth/google` con validación estricta de dominios institucionales (`google_allowed_domains`), aprovisionamiento automático de perfil y emisión de tokens JWT.
* **Moodle Delegated Login:** Endpoint `POST /api/v1/auth/moodle` validando contra `/login/token.php` de Moodle 4.1 (`moodle_mobile_app`), obtención de datos de usuario con Web Services, caché en Redis y emisión de JWT.
* **Mapeo y Desacople de Roles:** Si el usuario es nuevo y posee rol de manager/admin en Moodle, se le asigna rol local `ADMIN`; en caso contrario se asigna `Docente` o `Alumno`. La administración y cambio de roles posterior permanece 100% local e independiente de Moodle.
* **Frontend Login:** Vista `frontend/views/auth/login.html` adaptada para consultar `/api/v1/auth/providers` y renderizar dinámicamente el botón de Google Workspace, el botón desplegable de Moodle y el formulario tradicional.
### Épica 4: Integración Bidireccional Moodle 4.1 (Backend)
* **Cliente REST Moodle 4.1:** `MoodleClient` (`backend/app/services/moodle_client.py`) con métodos para:
- `core_user_create_users`, `core_user_update_users`, `core_user_get_users`.
- `enrol_manual_enrol_users`, `enrol_manual_unenrol_users`, `core_enrol_get_enrolled_users`.
- `core_role_assign_roles`, `core_role_unassign_roles`.
- `test_connection()` contra `core_webservice_get_site_info`.
* **Desacople en CRUD Local:** Creación y edición de usuarios en `backend/app/routes/api/admin.py` encola automáticamente la sincronización sin bloquear las peticiones locales.
### Épica 5: Motor de Notificaciones (Email Server)
* **Cliente SMTP Dinámico:** Creación de `EmailService` (`backend/app/services/email_service.py`) que obtiene credenciales en tiempo de ejecución de la base de datos (con desencriptación de contraseña al vuelo).
* **Plantillas Transaccionales Profesionales:**
- `notify_teacher_assignment`: Notificación a profesores sobre asignación a comisiones y horarios.
- `notify_exam_schedule`: Convocatoria y citación a mesas de examen final.
- `test_smtp_connection`: Verificación de handshake y autenticación SMTP con feedback claro.
### Cobertura de Pruebas
* Suite completa en `backend/tests/test_phase6_integration.py` con 7 pruebas unitarias e integrales que validan cifrado Fernet, SystemSetting, CacheService, MoodleQueueService (Backoff & DLQ), EmailService dinámico, y autenticación híbrida (Google & Moodle). **30/30 pruebas pasando en verde** en la suite global de regresión.
---
## [Fase 4: UI/UX Avanzada para Bedelía & Modo Impersonación] — v2.8.0 (2026-09-23)
**Estado:** ✅ 100% Completada
### Estadio 4.1 — Grilla Semanal Interactiva (Drag-and-Drop) con Detección de Colisiones
* **FullCalendar Interactivo:** Habilitación de `editable: true` y `droppable: true` en el calendario general de Bedelía (`/schedule/calendar`).
* **Sidebar de Comisiones Pendientes:** Panel lateral dinámico con catálogo de comisiones que aún no tienen aula asignada (`unassigned_commissions`), permitiendo arrastrarlas directamente hacia los bloques horarios del calendario.
* **Validación de Choques en Tiempo Real:** Integración con `POST /api/v1/reservations/drag-update`. Al mover o soltar una clase, el backend somete la nueva posición a la matriz integral de conflictos (`ReservationService.check_full_conflicts_matrix`):
- Conflicto físico de aula (doble asignación simultánea).
- Conflicto docente (profesor ocupado en otra aula).
- Conflicto de aforo (capacidad de aula insuficiente).
* **Manejo de Respuestas:** Si hay colisión, devuelve HTTP 409 (`status: conflict`), FullCalendar revierte automáticamente el movimiento (`info.revert()`) y se dispara un Toast de alerta detallando el motivo del bloqueo. Si está libre, persiste la reserva y confirma con Toast de éxito.
### Estadio 4.2 — Modo Impersonación del Superadmin con Trazabilidad
* **Cabecera `X-Impersonate-User`:** Inyección y soporte en `backend/app/utils/jwt_decorators.py` dentro de `jwt_required` para usuarios administradores. Asigna `g.jwt_user` al usuario objetivo preservando `g.real_admin_user` y marcando `g.is_impersonating = True`.
* **Endpoints de Control:** `POST /api/v1/admin/impersonate` y `POST /api/v1/admin/stop-impersonating` en Backend Flask con auditoría inmutable en `AuditLog` (`IMPERSONATE_START` e `IMPERSONATE_END`).
* **Integración en BFF Node.js:** Middleware `authMiddleware.js` y proxy `/api` en `app.js` configurados para propagar cookies seguras `impersonate_user_id` e inyectar `X-Impersonate-User` en todas las peticiones a la API Flask.
* **Banner Visual Institucional:** Banner de advertencia permanente en `base.html` con fondo de alerta ámbar, spinner de estado, identificación del usuario y rol adoptado, y botón de salida inmediata.
* **Acceso de un Clic:** Botón directo de impersonación (`bi-incognito`) en cada fila de usuario activo en `/admin/users_list`.
### Estadio 4.3 — Acople del Optimizador Genético a Datos y Turnos Reales
* **Turnos Académicos Reales:** `ReservationOptimizer._calculate_preferred_time` sincronizado con las franjas horarias de UniCABA (`Mañana`: 08:00 a 12:00, `Tarde`: 14:00 a 18:00, `Vespertino`/`Noche`: 18:30 a 22:30).
* **Persistencia Segura:** Endpoint `POST /api/genetic/apply-optimization` adaptado con parseo riguroso de strings ISO y prevención de colisiones físicas en guardado masivo.
### Cobertura de Pruebas
* Suite completa en `backend/tests/test_phase4_interactive_impersonation.py` validando los 6 criterios de aceptación (impersonación de docente, impersonación de alumno, trazabilidad en auditoría, rechazo a no-admins, bloqueo 409 por colisión en drag-drop y actualización exitosa 200). 18/18 tests aprobados en suite global de Fases 2, 3 y 4.
---
## [Fase 3: Gestión de Hitos Evaluativos y Libro de Calificaciones] — v2.7.0 (2026-09-23)
**Estado:** ✅ 100% Completada
### Estadio 3.1 — Calendario de Evaluación por Comisión y Notificaciones Preventivas
* **Modelo `MilestoneGrade`:** Tabla relacional `milestone_grades` para registrar calificaciones por estudiante y reserva evaluativa, con validación de unicidad (`student_id`, `reservation_id`), notas en escala 1.0 a 10.0, estado de inasistencia (`is_absent`) y devoluciones pedagógicas (`feedback`).
* **Consulta de Hitos del Alumno:** Endpoint `GET /api/v1/students/my-upcoming-milestones` que detecta dinámicamente exámenes parciales, recuperatorios y entregas de TP de las comisiones del estudiante con cálculo automático de días restantes (`days_remaining`).
* **Dashboard del Alumno:** Widget interactivo de próximos exámenes en `/dashboard?role=alumno` con badges visuales de urgencia (*¡Hoy!*, *¡Mañana!*, *Faltan X días*) y acceso directo desde el Launchpad a *"Mis Calificaciones"*.
### Estadio 3.2 — Libro de Calificaciones (*Gradebook*) y Cierre Formal de Actas
* **Extensiones en `Commission`:** Incorporación de columnas `grades_closed` (boolean), `grades_closed_at` (datetime), `grades_closed_by` (foreign key) y `acta_number` (identificador oficial generado).
* **Servicio `GradebookService`:** Motor centralizado para matriz de notas por comisión, guardado asíncrono individual y por lote (`bulk_save_grades`), cálculo dinámico de promedios ponderados y condiciones académicas en tiempo real (*Promocionado* ≥ 7, *Regular* ≥ 4, *Libre* < 4).
* **Cierre Formal de Actas:** Sellado institucional con código único (`ACTA-YYYY-Sem-ID`), auditoría inmutable en `audit_logs` con acción `CLOSE_ACTA` y bloqueo total contra modificaciones posteriores.
* **Reapertura Excepcional:** Endpoint para Bedelía/Administración (`POST /api/v1/commissions/<id>/gradebook/reopen`) con justificación administrativa obligatoria asentada en auditoría.
* **Interfaz Docente & Bedelía (`/schedule/gradebook/:id`):** Matriz interactiva de carga rápida con autoguardado asíncrono debounced (500ms), indicador visual flotante de sincronización, recálculo instantáneo de promedios en el cliente y modales de sellado y reapertura de actas.
* **Portal del Alumno (`/schedule/my_grades` / `/mis-materias/mis-notas`):** Vista consolidada de todas las materias del estudiante, notas de parciales, condición final y número de acta emitida, con soporte de impresión de certificado de regularidad.
* **Acceso Directo en Comisión:** Botón destacado *"Libro de Calificaciones (Actas)"* y badge de acta sellada incorporados en `/admin/commission_detail`.
### Cobertura de Pruebas
* Suite completa en `backend/tests/test_phase3_gradebook.py` validando los 6 criterios de aceptación: estructura de matriz bidimensional, persistencia y autoguardado de notas, validación estricta de notas inválidas (fuera del rango 1-10), cierre formal de acta e inmutabilidad estricta ante intentos de edición, consulta integral del alumno y cuenta regresiva de próximos hitos. 6/6 tests aprobados (12/12 en conjunto con Fase 2).
---
## [Fase 2: Co-docencia, Matriz de Conflictos y Regla Diaria] — v2.6.0 (2026-09-19)
**Estado:** ✅ 100% Completada
### Estadio 2.1 — Modelo y Gestión Integral de Co-docencia
* **Modelo `CommissionTeacher`:** Soporte para múltiples docentes por comisión en base de datos (`commission_teachers`), admitiendo roles académicos diferenciados (`Titular`, `Adjunto`, `JTP`, `Ayudante`) y flag `is_primary`.
* **API REST de Cátedras:** Endpoints `POST /api/v1/commissions/<id>/teachers` y `DELETE /api/v1/commissions/<id>/teachers/<user_id>` con serialización completa de cátedra en comisiones.
* **Interfaz de Gestión:** Tarjeta interactiva *"Equipo Docente / Cátedra"* en `/admin/commission_detail` para incorporar y desvincular profesores con rol dinámico, y visualización de badges en `/admin/commissions_list`.
### Estadio 2.2 — Matriz de Conflictos y Validación Integral
* **Conflicto Físico:** Bloqueo estricto e infranqueable de superposiciones de reservas en la misma aula física (`ReservationRepository.find_overlapping`).
* **Conflicto Docente:** Detección de doble asignación simultánea para un mismo docente en diferentes aulas o formatos.
* **Excepción Justificada por Co-docencia:** Si un docente asignado presenta solapamiento pero la comisión cuenta con co-docentes registrados en `CommissionTeacher`, la matriz de validación autoriza la reserva validando la cobertura del equipo de cátedra.
* **Conflicto de Aforo:** Bloqueo estricto cuando `expected_attendees > classroom.capacity` en espacios físicos.
* **Endpoint de Pre-validación:** `POST /api/v1/reservations/check-conflicts` para validación asíncrona de conflictos físicos, docentes y de aforo antes del commit.
### Estadio 2.3 — Regla de Restricción Diaria del Alumno y Motor de Excepciones
* **Servicio `EnrollmentService`:** Lógica de matriculación académica con análisis de días de cursada por comisión y verificación de cupos.
* **Regla Restrictiva:** Un alumno no puede cursar dos asignaturas regulares el mismo día de la semana.
* **Excepción Automática por Curso Corto:** Atributo `is_short_course` en modelo `Subject`; si una de las materias es un taller o curso corto, el sistema autoriza la cursada simultánea en el mismo día.
* **Excepción Expresa de Bedelía:** Campos `allow_same_day_exception` y `exception_reason` en `StudentEnrollment`. La oficina de Bedelía puede autorizar la matriculación simultánea mediante switch justificado en la interfaz.
* **Endpoints de Matrícula:** `GET/POST /api/v1/commissions/<id>/enrollments`, `DELETE/PUT /api/v1/commissions/<id>/enrollments/<student_id>`.
* **UI en Detalle de Comisión:** Formulario de matriculación con toggle de autorización de Bedelía, motivo de excepción y tabla de inscriptos con badges de estado.
### Cobertura de Pruebas
* Suite completa en `backend/tests/test_phase2_rules.py` validando los 6 criterios de aceptación (conflicto físico, aforo, co-docencia, restricción diaria, bypass de curso corto y bypass de Bedelía). 6/6 tests aprobados con 100% de éxito.
### Complementos y Seguridad Transversal
* **Dashboard de Bedelía:** Integración de paneles en tiempo real para análisis de **Comisiones Sin Reserva** y grilla de **Aulas Disponibles** (Filtros Semana/Mes) conectando frontend UI con el servicio analítico backend.
* **Auditoría Automatizada (Fase 1):** Implantación de un pipeline de seguridad local/Gitea que aísla dependencias de desarrollo (`requirements-dev.txt`) y ejecuta controles SAST, DAST y SCA (Bandit, pip-audit, njsscan y Schemathesis) sin vulnerabilidades detectadas.
* **Optimizador Genético de Reservas:** Reparación de enrutamiento 404, migración a JWT (`@jwt_required`), corrección de UI de métricas dinámicas de algoritmo, y refactorización de layout para superposición de herramientas.
* **UI/UX General:** Ajustes de CSS en modo claro (soporte dinámico de contraste de isologotipo blanco a rosa institucional mediante filtros) y traducciones de menús de usuario en `base.html`.
---
## [Fase 1: Paridad Legacy y Estabilización] — v2.5.0 / v2.4.0 (2026-09-19)
**Estado:** ✅ 100% Completada
* Seguridad automatizada SAST/DAST/SCA (Bandit, pip-audit, schemathesis, njsscan, npm audit).
* Tipificaciones de documentos argentinos y extranjeros, perfiles extendidos de usuarios con email personal e institucional.
* Gestión completa de aulas físicas vs virtuales con percentiles de asignación y métricas de ocupación real.
* Reingeniería del modal de edición y eliminación segura de asignaturas.
---
## [Fase 0: Desacople y Arquitectura Base] — v2.0.0 (2026-09-18)
**Estado:** ✅ 100% Completada
* Desacople arquitectónico completo: Backend Flask RESTful (`/api/v1/`) + Frontend BFF Node.js/Express con Nunjucks.
* Autenticación basada en tokens JWT con sincronización de estado de sesión.
@@ -0,0 +1,223 @@
# Estado Actual de la Migración y Arquitectura Objetivo
## Sistema Integral de Gestión de Aulas, Cursadas y Seguimiento Académico — UniCABA
**Rol:** Arquitecto de Software y Analista Funcional Senior
**Institución:** Universidad de la Ciudad de Buenos Aires (UniCABA)
**Fecha de Actualización:** 19 de Septiembre de 2026
**Rama Activa:** `testing`
---
## 1. De Dónde Venimos: La Versión Monolítica (`legacy_admin-edu-space`)
La versión original del sistema correspondía a un monolito clásico desarrollado en Python (Flask) con renderizado del lado del servidor mediante plantillas Jinja2 y ORM SQLAlchemy:
```
[Cliente Web / Navegador]
│
▼ (HTTP / HTML)
┌────────────────────────────────────────────────────────┐
│ Monolito Legacy (legacy_admin-edu-space) │
│ - Rutas Flask con render_template (Jinja2) │
│ - Sesión en Cookies de Flask (Flask-Login con estado) │
│ - Consultas directas SQLAlchemy acopladas a vistas │
│ - Base de Datos (SQLite / PostgreSQL) │
└────────────────────────────────────────────────────────┘
```
### Fortalezas Heredadas del Monolito
1. **Modelado de Dominio Inicial:** Entidades base para Sedes (`Building`), Aulas (`Classroom`), Materias (`Subject`), Comisiones (`Commission`), Reservas (`Reservation`) y Usuarios (`User`).
2. **Importador de Planillas Oficiales:** Módulo de sincronización con Google Sheets para alimentar la cartelera con la oferta de comisiones y clases.
3. **Algoritmo Genético Experimental:** Prototipo de optimización predictiva para asignación de aulas físicas según aforo y equipamiento.
### Limitaciones Críticas que Forzaron la Migración
* **Acoplamiento Servidor-Vista:** Lógica de negocio mezclada dentro de controladores web y macros de plantillas Jinja2, impidiendo el consumo móvil (app institucional) o integraciones externas (SIU Guaraní, Moodle).
* **Fallas Graves en Virtualidad:** El importador de Google Sheets descartaba más del 75% de las clases virtuales por asumir que el aula `Campus Virtual · VIRTUAL` sufría colisiones físicas de horario ante comisiones simultáneas.
* **Falta de Perspectiva por Rol:** El dashboard era único y uniforme; no distinguía entre el trabajo administrativo de Bedelía, la consulta rápida de cursada del Alumno, o la gestión evaluativa del Docente.
* **Escalabilidad y Seguridad:** Autenticación dependiente de la sesión en memoria del servidor web, sin soporte de tokens JWT sin estado ni separación de responsabilidades (BFF pattern).
---
## 2. Dónde Estamos Actualmente: Arquitectura Desacoplada Backend-BFF
La infraestructura ha sido transformada en un modelo desacoplado y de alta disponibilidad:
```
[ Navegador Web / Cliente ]
│
│ (HTTP / HTML + Cookies HttpOnly)
▼
┌──────────────────────────────────────────────┐
│ Frontend BFF (Node.js + Express) │
│ Puerto: 3000 │
│ - Renderizado Nunjucks con herencia limpia │
│ - Orquestación y agregación de UI │
│ - Gestión de Cookie JWT y Contexto de Rol │
│ - Cliente Axios con Interceptor Bearer │
└──────────────────────┬───────────────────────┘
│
│ (REST JSON / JWT Bearer)
▼
┌──────────────────────────────────────────────┐
│ Backend Core API (Python + Flask) │
│ Puerto: 5000 │
│ - Endpoints RESTful bajo /api/v1/ │
│ - Autenticación Stateless JWT (HS256) │
│ - Pipeline Enterprise SecurityFilterChain │
│ - Capa de Servicios y DTOs (Pydantic) │
│ - Persistencia SQLAlchemy (Transaccional) │
└──────────────────────┬───────────────────────┘
│
▼
[ Base de Datos SQLite / PG ]
```
### Estado de Implementación al Día de la Fecha
| Componente / Módulo | Estado en Legacy | Estado Actual (Backend API + BFF) | Nivel de Paridad |
| :--- | :--- | :--- | :---: |
| **Autenticación & Sesión** | Flask-Login basado en sesión de servidor | Autenticación REST JWT con cookie HttpOnly segura y RBAC centralizado | **120% (Superado)** |
| **Dashboards por Rol** | Dashboard monolítico único para todos | 4 Dashboards especializados (`admin`, `bedelia`, `docente`, `alumno`) con selector dinámico | **150% (Superado)** |
| **Campus Virtual & Enlaces** | Colisión de clases virtuales; pérdida de enlaces Meet | Aulas virtuales concurrentes sin límite, auto-generación de enlaces Google Meet por comisión | **140% (Superado)** |
| **Importador Google Sheets** | 363 reservas importadas (colisiones masivas) | 643 reservas totales (388 virtuales) sin colisión horaria entre comisiones | **100% (Paridad Total)** |
| **Cartelera del Día (`today_schedule`)** | Vista Jinja con bloques rígidos | Timeline interactivo por horas (7 a 21 hs), filtros por piso/turno y switch `hide_virtual` | **110% (Superado)** |
| **Ficha de Reserva (`view_reservation`)** | Vista monolítica rígida | Acoplada al BFF con relaciones anidadas completas, edición en cascada, confirmación y cancelación | **100% (Paridad Total)** |
| **Gestión de Comisiones (`commissions_list`)** | Lista plana sin modal de creación en admin | Modal `#modalAddCommission` con vinculación obligatoria a Asignatura, docente, cupo, horarios y Meet | **125% (Superado)** |
| **Calendario FullCalendar** | Feed JSON básico | Endpoint `/api/v1/reservations` con discriminación cromática (`#6366F1` virtuales) | **100% (Paridad Total)** |
---
## 3. A Dónde Queremos Ir: El Sistema Integral UniCABA
El objetivo institucional es consolidar la plataforma como el **ERP Académico y Gestor de Espacios Oficial de UniCABA**, dando soporte a las dinámicas pedagógicas físicas y digitales de la universidad.
### A. Entorno Físico vs. Campus Virtual
1. **Edificio Físico (Central):**
- Espacios con aforo estrictamente limitado, asignación por piso/ala y equipamiento técnico (proyectores, laboratorios informáticos, acústica).
- Validación matemática de no-solapamiento temporal para evitar doble asignación de aula física.
2. **Campus Virtual:**
- Capacidad física infinita; asignación lógica de salas vinculadas a la plataforma oficial (Google Meet institucional, Zoom o Microsoft Teams).
- Control de concurrencia temporal de docentes y estudiantes (evitar que un docente o alumno deba estar en dos salas remotas al mismo tiempo).
---
## 4. Reglas de Negocio del Sistema Objetivo
### 1. Perfiles y Permisos (RBAC Avanzado)
* **Administrador General (Superadmin):**
* Gobernanza total del sistema, configuración de periodos y parametrización de reglas de conflicto.
* **Modo Impersonación / Vista Previa:** Visualización en tiempo real del sistema desde la perspectiva exacta de cualquier usuario (Bedelía, Docente, Alumno) para soporte y auditoría.
* Flexibilidad académica para autorizar excepciones de cursada simultánea y apertura de comisiones extraordinarias.
* **Bedelía / Gestión Operativa:**
* Administración integral del inventario físico (Sedes, Edificios, Pisos, Aulas) y virtual.
* Creación y parametrización de Ciclos Lectivos, Asignaturas y Comisiones.
* **Asignación Docente Co-docente:** Posibilidad de asignar más de un profesor a una misma comisión (equipo de cátedra: titulares, adjuntos, ayudantes).
* Gestión de cupos máximos, padrón de alumnos matriculados y resolución de conflictos de asignación.
* Supervisión de hitos evaluativos institucionales.
* **Docente:**
* Vista segmentada estrictamente a sus comisiones asignadas.
* Calendario de clases presenciales y accesos directos a sesiones de videoconferencia.
* Gestión del calendario de evaluación: carga de fechas de parciales, recuperatorios, entregas de trabajos prácticos y finales.
* Matriz ágil de carga y edición de calificaciones y estados de regularidad.
* **Alumno:**
* Acceso enfocado a sus materias cursadas en el periodo lectivo activo.
* Brújula de cursada diaria (*¿Dónde curso hoy?* con sede, piso y aula física o enlace virtual).
* Calendario unificado de entregas de TPs, parciales y finales con avisos preventivos.
* Consulta histórica de notas y retroalimentaciones pedagógicas.
### 2. Estructura Académica y Ciclo Lectivo
* **Ciclo Lectivo Flexible:** Estructurado por Año (ej. `2026`) y Periodos estándar (`1C`, `2C`, `Anual`), permitiendo el alta de "Cursos Cortos Intensivos" o trayectos formativos extracurriculares con fechas especiales.
* **Restricción Diaria de Cursada del Estudiante:**
* **Regla por defecto:** Un estudiante universitario no puede cursar dos asignaturas regulares el mismo día calendario.
* **Excepción parametrizable:** Se autoriza la coincidencia en el mismo día si una de las materias corresponde a un curso corto intensivo o mediante autorización explícita de Bedelía/Secretaría Académica.
### 3. Matriz de Conflictos y Validaciones de Solapamiento
```mermaid
flowchart TD
Req([Solicitud de Asignación / Reserva]) --> V1{¿Es Aula Física?}
V1 -- Sí --> C1{¿Aula ocupada en ese día y horario?}
C1 -- Sí --> Err1[BLOQUEO: Conflicto Físico Infranqueable]
C1 -- No --> C2{¿Aforo de alumnos <= Capacidad aula?}
C2 -- No --> Err2[BLOQUEO: Aforo Excedido]
C2 -- Sí --> V2
V1 -- No (Virtual) --> V2
V2{¿Docente en otra clase en el mismo horario?}
V2 -- Sí --> C3{¿Comisión cuenta con Co-Docencia?}
C3 -- No --> Err3[BLOQUEO: Conflicto Docente]
C3 -- Sí --> Warn1[ALERTA: Excepción Co-Docente Justificada]
C3 --> V3
V2 -- No --> V3
V3{¿Alumno cursa otra materia regular el mismo día?}
V3 -- Sí --> C4{¿Es Curso Corto o Autorizado?}
C4 -- No --> Err4[BLOQUEO: Regla Restricción Diaria]
C4 -- Sí --> Ok[ASIGNACIÓN EXITOSA]
V3 -- No --> Ok
```
---
## 5. Diseño Técnico: Base de Datos Relacional Normalizada
Para soportar las reglas de co-docencia, inscripciones, evaluaciones y restricciones de día, el esquema de datos evolucionará hacia la siguiente estructura:
### Entidades Principales
1. **`academic_terms` (Ciclos Lectivos):** `id`, `name`, `code` (ej. '2026-1C'), `year`, `term_type` ('1C', '2C', 'ANUAL', 'CORTO'), `start_date`, `end_date`, `is_active`.
2. **`subjects` (Materias / Asignaturas):** `id`, `code`, `name`, `career_id`, `is_short_course` (boolean), `credits`, `active`.
3. **`commissions` (Comisiones de Cursada):** `id`, `subject_id`, `term_id`, `code`, `shift`, `schedule_display`, `max_students`, `virtual_link`, `active`.
4. **`commission_teachers` (Co-docencia / Equipo Docente):** `id`, `commission_id`, `teacher_id`, `role` ('TITULAR', 'ADJUNTO', 'AYUDANTE'), `can_grade` (boolean).
5. **`commission_schedules` (Asignación Horaria y Espacial):**
* `id`, `commission_id`, `day_of_week` (1=Lunes .. 7=Domingo), `start_time`, `end_time`, `classroom_id` (física o virtual), `is_virtual`.
* *Constraint de Integridad:* `UNIQUE(classroom_id, day_of_week, start_time, end_time)` para aulas no virtuales.
6. **`enrollments` (Inscripciones de Alumnos):** `id`, `commission_id`, `student_id`, `status` ('REGULAR', 'CONDICIONAL', 'LIBRE', 'PROMOVIDO'), `enrolled_at`, `allow_same_day_exception` (boolean).
7. **`evaluation_milestones` (Hitos Evaluativos):** `id`, `commission_id`, `milestone_type_id`, `title`, `date`, `start_time`, `weight_percentage`, `is_mandatory`.
8. **`student_grades` (Calificaciones y Actas):** `id`, `milestone_id`, `student_id`, `numeric_score`, `concept_score`, `feedback`, `graded_by_teacher_id`, `graded_at`.
---
## 6. Diseño de Contratos de API RESTful (Backend Core)
### A. Módulo de Comisiones y Co-docencia
* `GET /api/v1/commissions`: Filtro por término académico, carrera, asignatura, turno y estado.
* `POST /api/v1/commissions`: Alta de comisión vinculada a una asignatura con generación automática de Meet.
* `POST /api/v1/commissions/{id}/teachers`: Asignación de docentes con rol en cátedra (co-docencia).
* `DELETE /api/v1/commissions/{id}/teachers/{teacher_id}`: Desvinculación de docente.
### B. Módulo de Matriz de Conflictos y Validación
* `POST /api/v1/schedules/validate`:
* **Payload:** `{ commission_id, classroom_id, day_of_week, start_time, end_time, teacher_ids, student_ids }`
* **Respuesta:** `{ valid: boolean, conflicts: [ { type: 'PHYSICAL'|'TEACHER'|'STUDENT_DAILY', message, details } ] }`
### C. Módulo de Hitos Evaluativos y Libro de Calificaciones
* `GET /api/v1/commissions/{id}/milestones`: Listado de exámenes, entregas y parciales.
* `POST /api/v1/commissions/{id}/milestones`: Creación de hito evaluativo.
* `GET /api/v1/commissions/{id}/gradebook`: Matriz completa de alumnos y notas de la comisión.
* `PUT /api/v1/commissions/{id}/gradebook`: Carga masiva o individual de calificaciones por docente.
### D. Modo Impersonación de Superadmin
* Cabecera HTTP: `X-Impersonate-User: {user_id}`
* Procesamiento en `authMiddleware`: Si el token emisor corresponde al rol `SUPERADMIN`, el contexto de ejecución adopta los permisos y vistas del usuario destino para auditoría, dejando registro en `audit_logs`.
---
## 7. Directrices UI/UX para el Frontend BFF
1. **Panel de Bedelía:**
- Grilla interactiva semanal (tipo TimeGrid) donde los bloques de comisiones se visualizan codificados por color según edificio, aula física o aula virtual.
- Detección inmediata de colisiones con carteles de advertencia flotantes antes de confirmar cambios.
2. **Matriz de Carga Rápida para Docentes:**
- Tabla editable en línea (*spreadsheet-like*) para volcar notas de parciales y entregas sin recargar la página, con autoguardado asíncrono.
3. **Perspectiva del Alumno:**
- Interfaz simplificada con diseño enfocado en dispositivos móviles, mostrando en la tarjeta de inicio la clase del momento con botón directo para ingresar a la videollamada o indicador de piso y aula física.
---
## 8. Conclusión del Diagnóstico
El sistema ha superado con éxito la fase de desacople inicial y estabilización de virtualidad:
- Se logró paridad total con `legacy_admin-edu-space` en importación de cronograma y cartelera.
- Se eliminaron las fallas de colisión virtual y se establecieron los 4 dashboards por rol.
- Se completó el acople de la ficha de reserva (`schedule.view_reservation`) y la creación asistida de comisiones en el BFF.
Las siguientes etapas se concentrarán en la consolidación de las reglas académicas complejas (co-docencia, restricción diaria de cursada, matriz de conflictos y libro de calificaciones) detalladas en el **`ROADMAP_MVP.md`**.
+175 -173
View File
@@ -1,208 +1,210 @@
# GUÍA OPERATIVA DE SISTEMA, RELEVAMIENTO DE BEDELÍA Y ROADMAP DE EVOLUCIÓN
# GUÍA OPERATIVA DE SISTEMA, MANUAL DE PROCEDIMIENTOS Y ROADMAP DE EVOLUCIÓN
## Plataforma Admin Edu-Space — UniCABA
**Documento de Operaciones y Prospectiva Tecnológica**
**Versión:** 1.0 (Producción MVP)
**Documento de Operaciones, Flujo Secuencial de Bedelía y Manual de Usuario**
**Versión:** 3.3.0 (Producción MVP)
**Institución:** Universidad de la Ciudad de Buenos Aires (UniCABA)
---
## 1. Guía de Procedimientos del Programa por Rol
## 1. Guía de Procedimientos Operativos por Rol
### 1.1. Para el Personal de Bedelía (Gestores de Espacios)
---
El personal de Bedelía es el corazón operativo de la infraestructura física universitaria. Su flujo de trabajo en Edu-Space sigue el siguiente ciclo:
### 1.1. Para el Personal de Bedelía (Gestores de Espacios y Cursadas)
El personal de Bedelía es el corazón operativo de la infraestructura física y académica. El objetivo central de este sprint es **reemplazar definitivamente el archivo Excel que Bedelía utiliza actualmente para sus gestiones diarias**. A partir de ahora, la plataforma es la fuente única de verdad para administrar sedes, aulas, ciclos lectivos, materias, comisiones, docentes, alumnos y reservas.
```
[ Inicio de Cuatrimestre ]
│
▼
1. Configuración del Ciclo Lectivo
(Fechas de inicio, fin, feriados y recesos)
│
▼
2. Carga/Actualización de Aulas y Sede
(Capacidad física, proyectores, computadoras, AC)
│
▼
3. Importación o Carga de Comisiones y Materias
(Docente a cargo, alumnos inscriptos, días y turnos)
│
▼
4. Ejecución del Optimizador Genético
(Distribución automatizada sin colisiones ni solapamientos)
│
▼
5. Publicación y Monitoreo en Tiempo Real
(Cartelera digital activa y gestión de contingencias/reparaciones)
[ 1. Sede / Edificio ] ──▶ [ 2. Aula (Física/Virtual) ]
│ │
▼ ▼
[ 3. Ciclo Lectivo ] ──▶ [ 4. Carrera / Titulación ]
│ │
▼ ▼
[ 5. Asignatura / Materia ] (Vinculada a la Carrera)
│
▼
[ 6. Crear Comisión ] (Vinculada a Materia, Carrera y Ciclo)
│
┌───────────────┴───────────────┐
▼ ▼
[ 7. Asociar Profesores ] [ 8. Asociar Alumnos ]
│ │
└───────────────┬───────────────┘
▼
[ 9. Reserva de Espacios ]
(Asignación en Aula & Horario)
```
#### Paso a Paso Operativo:
1. **Configuración de Ciclo Lectivo:**
- Navegar al menú **Ciclos Lectivos** en la barra lateral.
- Definir el ciclo activo (ej: `2026 - 2C`), fijando las fechas de inicio de clases, exámenes finales y cierres de actas.
2. **Inventario de Aulas y Recursos:**
- En **Gestión de Aulas**, registrar cada aula con su capacidad real de asientos, tipo de pizarrón, presencia de proyector, conectividad de red y climatización.
- Marcar aulas en estado `Mantenimiento` en caso de fallas edilicias para excluirlas del algoritmo de asignación.
3. **Carga y Verificación de Comisiones:**
- Ingresar a **Comisiones / Horarios** para verificar la nómina de materias activas, sus horarios (Turno Mañana, Tarde o Noche) y la cantidad estimada de matriculados.
4. **Asignación Asistida por IA (Optimizador Genético):**
- Acceder al módulo **Optimizador Genético**.
- Seleccionar el ciclo lectivo y pulsar **"Ejecutar Optimización"**.
- El sistema evaluará millones de combinaciones en segundos, priorizando que los grupos más numerosos ocupen las aulas mayores y minimizando distancias de traslado de docentes.
- Bedelía puede revisar el cronograma propuesto y confirmarlo con un clic.
5. **Atención de Cambios de Último Momento:**
- Si un docente requiere cambio de aula o si un equipo multimedia falla, Bedelía ingresa a **Reservas / Asignaciones**, busca la franja horaria y reubica la comisión en un aula alternativa libre sugerida por el sistema.
---
#### 📋 Flujo Secuencial de 9 Pasos (Paso a Paso Detallado):
#### Paso 1: Crear Sitio / Sede (Edificio)
1. **Acceso:** Ir al menú lateral ➔ **Espacios & Sedes** (o **Administración**) ➔ **Sedes / Edificios** (`/buildings/list_buildings`).
2. **Acción:** Presionar el botón `+ Nueva Sede`.
3. **Completar Datos:**
- **Nombre:** Ej. *Sede Central UniCABA*.
- **Dirección / Código:** Ej. *Paseo Colón 255* / *SEDE-CENTRAL*.
- **Estado:** Activo.
4. **Guardar:** Presionar `Guardar Sede`. El edificio queda registrado para albergar aulas físicas.
#### Paso 2: Crear Aula (Espacios Físicos o Virtuales)
1. **Acceso:** Ir al menú lateral ➔ **Espacios & Sedes** ➔ **Catálogo de Aulas** (`/classrooms/list_classrooms`).
2. **Acción:** Presionar el botón `+ Nueva Aula` (`/classrooms/add_classroom`).
3. **Seleccionar Tipo de Espacio:**
- **Espacio Físico:** Seleccionar la Sede creada en el Paso 1, indicar el Piso (ej. *1° Piso*), el Código/Nombre del aula (ej. *Aula 101*), Capacidad máxima de bancos (ej. *40*) y Recursos (Proyector, Aire Acondicionado, PCs).
- **Espacio Virtual:** Marcar el casillero `¿Es espacio virtual / remoto?`. El sistema lo vinculará al entorno institucional remoto (Campus Virtual).
4. **Guardar:** Presionar `Crear Aula`. Queda lista para recibir reservas.
#### Paso 3: Crear Ciclo Lectivo (Período Académico)
1. **Acceso:** Ir al menú lateral ➔ **Académica** ➔ **Ciclos Lectivos** (`/admin/academic_terms_list`).
2. **Acción:** Presionar el botón `+ Nuevo Ciclo Lectivo`.
3. **Completar Datos:**
- **Nombre:** Ej. *2026 - 2° Cuatrimestre* o *2026 - 1C*.
- **Fecha de Inicio y Fin:** Fechas formales del cuatrimestre.
- **Activar:** Marcar como `Ciclo Actual / Activo`. Todas las nuevas comisiones se asignarán por defecto a este ciclo.
4. **Guardar:** Presionar `Guardar Período`.
#### Paso 4: Crear Carrera (Programa Académico / Titulación)
1. **Acceso:** Ir al menú lateral ➔ **Académica** ➔ **Carreras** (`/admin/careers_list`).
2. **Acción:** Presionar el botón `+ Nueva Carrera`.
3. **Completar Datos:**
- **Nombre de la Carrera:** Ej. *Licenciatura en Tecnologías Informáticas* o *Tecnicatura Universitaria en Ciberseguridad*.
- **Código Institucional:** Ej. *LTI* o *TUC*.
- **Descripción:** Objetivos del plan de estudios.
4. **Guardar:** Presionar `Crear Carrera`. Las materias y comisiones quedarán agrupadas bajo esta carrera.
#### Paso 5: Crear Asignatura / Materia (Vinculada a la Carrera)
1. **Acceso:** Ir al menú lateral ➔ **Académica** ➔ **Asignaturas** (`/admin/subjects_list`).
2. **Acción:** Presionar el botón `+ Nueva Asignatura`.
3. **Completar Datos:**
- **Código de Materia:** Ej. *PROG-VANG-2026*.
- **Nombre de la Materia:** Ej. *Programación de Vanguardia*.
- **Carrera Vinculada:** Seleccionar obligatoriamente la Carrera creada en el Paso 4 (ej. *Licenciatura en Tecnologías Informáticas*).
- **Departamento / Créditos:** Indicar departamento y créditos académicos.
- **¿Es Curso Corto / Taller?:** Marcar si aplica para habilitar excepciones de cursada en el mismo día.
4. **Guardar:** Presionar `Crear Asignatura`.
#### Paso 6: Crear Comisión (Asociada a Materia, Carrera y Ciclo)
1. **Acceso:** Ir al menú lateral ➔ **Académica** ➔ **Comisiones** (`/admin/commissions_list`).
2. **Acción:** Presionar el botón `+ Nueva Comisión`.
3. **Completar Datos:**
- **Asignatura / Materia:** Seleccionar la Asignatura creada en el Paso 5 (el sistema muestra su carrera asociada).
- **Código de Comisión:** Ej. *Comisión A* o *K3001*.
- **Ciclo Lectivo:** Seleccionar el ciclo activo creado en el Paso 3.
- **Turno:** *Mañana* (08:00 - 12:00), *Tarde* (14:00 - 18:00) o *Noche / Vespertino* (18:30 - 22:30).
- **Docente Titular (Opcional en este paso):** Puede asignarse de inmediato o más tarde.
- **Cupo Máximo:** Cantidad estimada de matriculados (ej. *35*).
- **Enlace Virtual:** Enlace opcional de Google Meet, Zoom o Teams si cursará en modalidad remota o híbrida.
4. **Guardar:** Presionar `Crear y Asociar Comisión`. La comisión hereda la carrera y el plan de estudios.
#### Paso 7: Asociar Profesores (Equipo Docente / Co-docencia)
1. **Acceso:** En la lista de comisiones (`/admin/commissions_list`), hacer clic en la tuerca o nombre de la comisión para ingresar al **Detalle de Comisión** (`/admin/commission_detail?id=...`).
2. **Sección:** Localizar la tarjeta **"Equipo Docente / Cátedra"**.
3. **Acción:** Seleccionar al profesor en el desplegable de docentes, elegir su rol académico (*Titular*, *Adjunto*, *JTP*, *Ayudante*) y marcar si es el docente principal.
4. **Asignar:** Presionar `+ Vincular Docente`.
- *Nota de Co-docencia:* Si la comisión tiene múltiples docentes registrados, el sistema activará automáticamente la tolerancia de superposición horaria en la matriz de conflictos.
#### Paso 8: Asociar Alumnos (Matriculación de Estudiantes)
1. **Acceso:** Dentro de la misma vista de **Detalle de Comisión** (`/admin/commission_detail`), localizar la tarjeta **"Alumnos Matriculados"**.
2. **Acción:** Presionar `Inscribir Alumno` y seleccionar al estudiante registrado en el sistema.
3. **Validación Automática:** El sistema comprobará si el alumno ya cursa otra materia regular el mismo día.
- Si no hay conflicto: La matriculación se efectiviza inmediatamente.
- Si existe superposición de día: El sistema solicita autorización expresa de Bedelía activando el switch `Autorizar excepción de cursada en el mismo día` e ingresando el motivo institucional.
4. **Confirmar:** Presionar `Inscribir`.
#### Paso 9: Reserva de Espacios (Asignación de Aula y Horario)
Bedelía dispone de **3 modalidades complementarias** para efectuar la reserva según la conveniencia:
1. **Modalidad Rápida desde Comisiones:**
- En `/admin/commissions_list`, pulsar el botón con ícono de calendario `Asignar Aula` (`bi-calendar-plus`) en la fila de la comisión.
- El sistema redirige a `/schedule/add_reservation` precargando automáticamente la comisión, el cupo, la carrera y los datos de la materia.
- Seleccionar Edificio ➔ Piso ➔ Aula, día de la semana y franja horaria.
- Presionar `Confirmar Reserva`. La matriz de conflictos valida en tiempo real y confirma la reserva.
2. **Modalidad Interactiva (Drag & Drop en Calendario Semanal):**
- Ir a **Reservas / Calendario** (`/schedule/calendar`).
- En la barra lateral izquierda se muestran las *Comisiones Pendientes de Aula*.
- Arrastrar la tarjeta de la comisión directamente a la grilla horaria del aula deseada.
- El sistema valida instantáneamente; si no hay solapamiento ni choque de docentes, la reserva queda confirmada. Si hay colisión, revierte el movimiento y muestra una alerta clara en pantalla.
3. **Modalidad Automatizada con Inteligencia Artificial (Optimizador Genético):**
- Ir a **Optimizador de Aulas** (`/genetic-optimizer`).
- Seleccionar el ciclo lectivo y pulsar `Ejecutar Optimización`.
- El algoritmo heurístico evalúa millones de combinaciones, asignando las aulas de mayor capacidad a los grupos más numerosos y evitando todo solapamiento.
- Bedelía previsualiza el resultado y confirma la asignación masiva con 1 clic.
---
#### 📥 Ingesta Masiva desde Google Sheets / Planillas:
- Para no interrumpir la dinámica durante la transición, Bedelía puede usar la importación oficial desde Google Sheets:
- Ir a **Administración** ➔ **Configuración Global** (`/admin/settings`).
- Verificar la URL de la planilla oficial publicada.
- Ejecutar la sincronización masiva para poblar comisiones y horarios.
- *A partir de ese momento, toda modificación, reemplazo o ajuste se realiza exclusivamente en Edu-Space*, dejando la planilla congelada como copia de respaldo.
---
### 1.2. Para el Cuerpo Docente (Profesores)
1. **Consulta de Aulas Asignadas:**
- Iniciar sesión con la cuenta docente. En el **Dashboard de Cátedra**, el profesor ve inmediatamente su agenda semanal: nombre de la materia, número de comisión, aula física asignada, piso y capacidad.
2. **Clases Virtuales e Híbridas (Google Meet):**
- Para las materias con modalidad combinada, el sistema genera y exhibe el enlace directo de **Google Meet**. El docente puede iniciarlo con un solo clic sin necesidad de crear salas manualmente.
3. **Solicitud de Asistencia o Recursos:**
- Desde la ficha de su clase, el profesor puede reportar incidencias (ej: falta de marcadores, proyector averiado) notificando directamente al panel de Bedelía.
1. **Consulta Inmediata de Aulas Asignadas:**
- Iniciar sesión en la plataforma con cuenta institucional.
- En el **Dashboard de Cátedra** (`/dashboard?role=docente`), el docente visualiza su agenda del día y de la semana:
- Nombre de la materia y número de comisión.
- Aula física exacta asignada, piso y sede.
- Cantidad de alumnos matriculados y equipamiento disponible.
2. **Clases Virtuales y Enlace a Google Meet:**
- Si la comisión es virtual o híbrida, el docente visualiza el botón destacado `Unirse a Clase Virtual (Meet)`.
- Con un solo clic se abre la sala de Google Meet oficial vinculada a la comisión.
3. **Libro de Calificaciones (*Gradebook*) y Actas de Notas:**
- Acceder al menú **Mis Materias** ➔ Seleccionar la comisión ➔ Pulsar `Libro de Calificaciones (Actas)`.
- Cargar las notas de exámenes parciales, recuperatorios y TPs en la grilla interactiva.
- El sistema realiza autoguardado asíncrono y calcula promedios y condición académica (*Promocionado*, *Regular*, *Libre*).
- Al finalizar el cuatrimestre, pulsar `Cerrar y Sellar Acta Oficial`. Se genera un identificador inmutable (`ACTA-2026-2C-XXXX`) registrado en auditoría.
4. **Solicitud de Asistencia o Incidencias:**
- Desde la ficha de la clase, el docente puede reportar cualquier falla edilicia (proyector averiado, aire acondicionado, falta de bancos) para que Bedelía actúe de inmediato.
---
### 1.3. Para los Estudiantes (Alumnado)
1. **Localización de Aula en Tiempo Real:**
- Desde cualquier smartphone o computadora, el alumno ingresa a `eduspace.oemspot.com.ar` y visualiza en su pantalla principal el aula de cursada del día, evitando aglomeraciones en los pasillos de entrada.
2. **Calendario Académico y Fechas de Parciales:**
- El alumno consulta los días confirmados de exámenes parciales, recuperatorios y entregas de trabajos prácticos fijados por sus cátedras.
3. **Cartelera de Avisos:**
- Acceso a novedades institucionales y eventuales traslados de aula notificados al instante.
1. **Brújula de Cursada "¿Dónde curso hoy?":**
- Desde su teléfono inteligente o computadora, el estudiante ingresa a `eduspace.oemspot.com.ar`.
- En la pantalla principal visualiza inmediatamente:
- Aula exacta de cursada del día, piso y sede (ej. *Aula 203 - 2° Piso - Sede Central*).
- Horario de inicio y fin de la clase.
- Nombre de la materia y docente a cargo.
2. **Acceso a Clases Virtuales:**
- Si la clase del día es virtual, en lugar del aula física se despliega el botón `Ingresar a la Clase Virtual`.
3. **Calendario Académico y Próximos Exámenes:**
- Visualización de la cuenta regresiva para exámenes parciales, fechas de entrega de trabajos prácticos y recesos.
4. **Consulta de Notas y Certificados:**
- En la sección **Mis Calificaciones**, el alumno puede revisar sus notas de parciales, condición final y número de acta oficial sellada por el docente.
---
## 2. Relevamiento y Cuestionario para Entrevista con Bedelía
## 2. Relevamiento Operativo y Adaptación Institucional
Para perfeccionar la aplicación y adaptarla de forma quirúrgica a las particularidades de UniCABA, se diseñó la siguiente guía de preguntas para entrevistar al equipo de Bedelía:
Para asegurar una transición sin fricción desde el Excel hacia Edu-Space en UniCABA, se definen los siguientes criterios operativos:
### Bloque A: Dinámica y Cuellos de Botella Actuales
1. *¿Cuál es el proceso exacto que utilizan hoy cuando se abre un nuevo cuatrimestre? ¿Cuánto tiempo les demanda asignar manualmente todas las aulas?*
2. *¿Cuáles son los conflictos más frecuentes que ocurren durante las dos primeras semanas de clase? (Ej: grupos que superan la capacidad del aula, docentes que piden proyector sin aviso previo, ruidos molestos).*
3. *¿Cómo gestionan hoy los cambios de aula imprevistos? (¿Cartel de papel en la puerta, aviso por WhatsApp, grupos de delegados?)*
### Bloque B: Reglas de Negocio y Restricciones Específicas
4. *¿Existen docentes que por razones de movilidad reducida o edad deban tener asignadas aulas exclusivamente en Planta Baja o cerca de ascensores?*
5. *¿Hay cátedras que requieran software específico o laboratorios fijos que no puedan dictarse en aulas convencionales?*
6. *¿Qué margen de tolerancia de capacidad prefieren? (Ej: ¿Es aceptable ubicar a 30 alumnos en un aula de 32 bancos, o exigen un 15% de margen de seguridad libre?)*
### Bloque C: Integración con Sistemas Institucionales
7. *¿De qué sistema extraen la nómina de alumnos inscriptos? (¿SIU Guaraní, planillas CSV/Excel, sistema propio de la Ciudad de Buenos Aires?)*
8. *¿Qué formato de reporte o planilla deben entregar a Dirección Académica al cerrar la planificación?*
### Bloque D: Propuestas de Mejora Identificadas para Modificar en Edu-Space
* **Petición detectada:** Incorporación de un botón de "Intercambio Rápido de Aulas" entre dos comisiones simultáneas sin tener que desasignar y volver a asignar a ambas individualmente.
* **Petición detectada:** Alerta visual con código de colores cuando un aula física supere el 95% de aforo de seguridad.
* **Petición detectada:** Exportador directo en PDF imprimible con formato oficial apaisado para pegar en las carteleras de corcho tradicionales para aquellos alumnos sin batería en el móvil.
### Criterios Clave de Usabilidad para Bedelía:
1. **Intercambio Rápido de Aulas:** Permite permutar dos comisiones de aula en la misma franja horaria sin tener que desasignar y reasignar individualmente.
2. **Semáforo Visual de Aforo:** Alertas de color (Verde: < 80% ocupación, Amarillo: 80-95%, Rojo: > 95% o exceso de capacidad).
3. **Exportación Imprimible:** Generador de reportes de cartelera en formato apaisado para impresión en papel ante contingencias eléctricas o de red.
---
## 3. Especificación: Módulo y Pestaña de Beneficios Universitarios
### 3.1. Propósito y Justificación
Uno de los principales factores de permanencia y bienestar estudiantil es el acceso ágil a los convenios y beneficios que brinda la comunidad académica. La incorporación de la pestaña **Beneficios** dentro del ecosistema Edu-Space centraliza esta información en la misma plataforma donde el alumno consulta su vida académica diaria.
```
┌────────────────────────────────────────────────────────────────────────┐
│ PESTAÑA DE BENEFICIOS EDU-SPACE │
├──────────────────┬──────────────────┬─────────────────┬────────────────┤
│ 🏷️ COMERCIO │ 💻 LICENCIAS │ ☕ COMEDOR │ 📚 BIBLIOTECA │
│ Y LIBRERÍA │ DE SOFTWARE │ UNIVERSITARIO │ DIGITAL │
├──────────────────┼──────────────────┼─────────────────┼────────────────┤
│ 20% en fotocopias│ GitHub Student │ Menú estudiantil│ Préstamo de │
│ y apuntes con el │ Pack, JetBrains │ subsidiado con │ e-books y salas│
│ carnet digital. │ Pro y Office 365 │ reserva previa. │ de estudio. │
└──────────────────┴──────────────────┴─────────────────┴────────────────┘
```
### 3.2. Modelo de Datos Propuesto (Entidades)
* **Tabla `beneficio`:**
- `id`: Clave primaria autoincremental.
- `categoria`: Enum (`Librería`, `Gastronomía`, `Software/Tecnología`, `Salud/Deportes`, `Cultura`).
- `titulo`: Nombre del beneficio (ej: *Descuento 20% en Fotocopiadora Central*).
- `descripcion`: Condiciones de uso y letra chica.
- `validez_hasta`: Fecha límite de vigencia.
- `codigo_descuento`: Cupón alfanumérico o enlace de validación.
- `convenio_empresa`: Nombre del proveedor o área universitaria.
- `activo`: Booleano para activar/pausar la visualización.
### 3.3. Interfaz de Usuario (UI)
* Tarjetas dinámicas (*Cards*) con estética Glassmorphism, botón de "Copiar Código", botón de "Ver Mapa de Canje" y filtros por categoría.
## 3. Especificación: Módulo de Beneficios Universitarios (Futuro)
- Pestaña para centralizar convenios estudiantiles (Librerías, Software estudiantil, Comedor universitario, Biblioteca digital).
- Tarjetas con códigos de validación y mapa de canje.
---
## 4. Innovación a Futuro: Credencial Digital con QR y Rol "Recepción"
### 4.1. Arquitectura de Acceso Seguro mediante QR Dinámico
Para modernizar el control de ingreso al edificio de UniCABA y erradicar las credenciales plásticas costosas y extraviables, se proyecta el módulo de **Credencial QR Inteligente**:
```
[ Pantalla Alumno (Edu-Space) ]
Generación de Token TOTP Cifrado (HMAC-SHA256)
(Cambia cada 30 segundos para evitar capturas de pantalla compartidas)
│
▼ Muestra Código QR en Pantalla
[ Puesto de Acceso / Molinete ]
│
▼ Escaneo con Cámara Web o Lector Óptico 2D
[ Tablet / Terminal Rol "Recepción" ]
- Valida firma criptográfica con la API
- Consulta estado del estudiante: ¿Alumno Regular Activo? ¿Tiene clase en esta sede hoy?
│
▼
✅ ACCESO PERMITIDO: Nombre, Foto, Carrera y Aula asignada ("Aula 104 - 1° Piso")
❌ ACCESO DENEGADO / ALERTA: Matrícula suspendida o no regular
```
### 4.2. Especificación del Nuevo Rol de Usuario: `recepcion`
* **Permisos del Rol:**
- Acceso restringido exclusivamente a la pantalla de escaneo (`/reception/scanner`) y al monitor de aforo edilicio en vivo (`/reception/headcount`).
- Imposibilidad de alterar notas, comisiones o configuraciones de Bedelía.
* **Beneficios de Seguridad Institucional:**
- **Control de Aforo en Tiempo Real:** El personal de portería y seguridad conoce en todo momento la cantidad exacta de personas dentro del edificio, dato crítico ante evacuaciones por siniestros.
- **Guía al Ingresante:** Al momento del escaneo, el sistema le muestra en pantalla al recepcionista a qué aula debe dirigirse el estudiante, permitiendo orientarlo amablemente en el momento del ingreso.
- Credencial QR inteligente con token dinámico TOTP (HMAC-SHA256) que cambia cada 30 segundos en la pantalla del alumno.
- Rol de usuario `recepcion` en tablets de molinete para validar ingreso, registrar aforo edilicio en tiempo real y guiar al estudiante a su aula asignada.
---
## 5. Aplicación Móvil en Ionic (Capacitor) para Android e iOS
### 5.1. ¿Por Qué Ionic Framework + Capacitor?
Para llevar Edu-Space a los dispositivos móviles de los estudiantes y profesores sin duplicar el costo de desarrollo en lenguajes nativos independientes (Kotlin/Swift), la elección óptima de ingeniería es **Ionic con Capacitor**:
1. **Reutilización del Código y UI Web:** El diseño responsivo ya desarrollado en HTML5/CSS/JavaScript se compila directamente dentro de un contenedor webview de alto rendimiento nativo.
2. **Acceso a Hardware Nativo mediante Plugins Capacitor:**
- `@capacitor/camera`: Para que el personal de recepción o docentes escaneen códigos QR directamente con el lente del celular.
- `@capacitor/push-notifications`: Notificaciones Push en tiempo real emitidas por Firebase Cloud Messaging (FCM) ante avisos urgentes (ej: *"Tu clase de Algoritmos se trasladó al Aula 201"*).
- `@capacitor/preferences` / `@capacitor-community/sqlite`: Almacenamiento local para permitir al alumno consultar sus horarios sin consumir datos móviles o en zonas del edificio con baja señal de red.
### 5.2. Arquitectura de Distribución
```
┌──────────────────────────────────┐
│ Código Base Edu-Space Frontend │
└─────────────────┬────────────────┘
│
▼
┌──────────────────────────────────┐
│ Capacitor Bridge CLI │
└────────┬────────────────┬────────┘
│ │
┌───────────────▼──┐ ┌──▼────────────────┐
│ Proyecto Nativo│ │ Proyecto Nativo │
│ Android │ │ iOS │
│ (Gradle/APK) │ │ (Xcode/Archive) │
└───────┬──────────┘ └──┬────────────────┘
│ │
▼ ▼
Google Play Store Apple App Store
```
### 5.3. Fases de Implementación Móvil
* **Fase 1 (Empaquetado y Notificaciones):** Inicialización de Capacitor en el proyecto, configuración de iconos adaptativos y recepción de notificaciones Push de cambios de aula.
* **Fase 2 (Modo Desconectado / Offline):** Caché del cronograma semanal en almacenamiento interno del dispositivo para consulta sin internet.
* **Fase 3 (Publicación):** Firma digital de binarios (`.aab` para Android y `.ipa` para iOS) y subida a las consolas de Google Play y Apple Developer.
## 5. Aplicación Móvil Híbrida en Ionic (Capacitor)
- Envoltorio Capacitor multiplataforma para Android e iOS reutilizando la interfaz web responsiva de Edu-Space.
- Notificaciones Push institucionales ante traslados o cancelaciones de aula de último momento.
- Modo de consulta offline del cronograma semanal almacenado en caché interna del teléfono.
+188
View File
@@ -0,0 +1,188 @@
# ROADMAP MVP — Sistema Integral UniCABA
## Gestión de Espacios Áulicos, Actividad de Cursada y Seguimiento Académico
**Institución:** Universidad de la Ciudad de Buenos Aires (UniCABA)
**Versión:** 3.1.0
**Fecha de Actualización:** 23 de Septiembre de 2026
**Rama Base:** `mvp`
---
## 🗺️ Visión del Proyecto
Construir y evolucionar la plataforma de gestión académica y espacial de **UniCABA** hacia un sistema integral de clase universitaria, desacoplado en una arquitectura **Backend RESTful (Python/Flask) + Frontend BFF (Node.js/Express/Nunjucks)**, capaz de gobernar tanto los espacios físicos de la sede central como la dinámica áulica del campus virtual, garantizando una experiencia fluida para **Administradores**, **Bedelía**, **Docentes** y **Estudiantes**.
---
## 📊 Estado Global de Progreso
```
Fase 0: Desacople y Arquitectura Base [████████████████████] 100% (Completado)
Fase 1: Paridad Legacy y Estabilización [████████████████████] 100% (Completado)
Fase 2: Co-docencia y Matriz Conflictos [████████████████████] 100% (Completado)
Fase 3: Hitos Evaluativos y Calificaciones[████████████████████] 100% (Completado)
Fase 4: UI/UX Drag & Drop e Impersonación[████████████████████] 100% (Completado)
Fase 5: Integración Auth, Email & Moodle [████████████████████] 100% (Completado)
Fase 5.1: Bedelía UX, ABMs y Purga Datos [████████████████████] 100% (Completado)
Fase 6: Despliegue Producción e Infraest.[███████░░░░░░░░░░░░░] 35% (En Curso)
```
---
## 🚀 Detalle de Fases y Estadios
### Fase 0: Desacople y Arquitectura Base ✅ *(Completada)*
* **Objetivo:** Separar el monolito Jinja2 legacy en dos servicios independientes de alto rendimiento.
* **Entregables:**
* [x] Creación del Backend Flask como API REST pura bajo `/api/v1/` retornando exclusivamente JSON.
* [x] Implementación del Frontend BFF en Node.js + Express con renderizado de plantillas mediante Nunjucks.
* [x] Autenticación desacoplada mediante JWT (`access_token`) transportado en Cookie `HttpOnly` segura.
* [x] Pipeline de seguridad `SecurityFilterChain` con cabeceras de blindaje OWASP y rate limiting dinámico.
* [x] Cliente HTTP Axios centralizado con inyección automática de Bearer token y manejo de sesiones.
---
### Fase 1: Paridad Legacy, Estabilización de Virtualidad y BFF Core ✅ *(Completada)*
* **Objetivo:** Alcanzar paridad funcional total con la versión legacy, subsanando defectos críticos de virtualidad y dotando de interfaz específica a cada rol.
* **Entregables:**
* [x] **Importador de Google Sheets Corregido:**
* Eliminación de la colisión de horarios en el aula virtual única (`Campus Virtual · VIRTUAL`).
* Incremento de reservas registradas de 363 a 643 (incorporando 280 clases virtuales que se descartaban).
* Generación y persistencia automática de enlaces de Google Meet institucional por comisión y reserva.
* [x] **Dashboards Especializados por Rol:**
* Dashboard interactivo para **Bedelía** (aulas físicas, salas virtuales, aprobaciones pendientes).
* Dashboard interactivo para **Docente** (clases del día, comisiones, enlaces directos a Meet).
* Dashboard interactivo para **Alumno** (brújula de cursada *"¿Dónde curso hoy?"*, hitos y calendario).
* Cockpit institucional para **Admin** (métricas de capacidad, auditoría RBAC, demanda mensual).
* Selector dinámico de vista previa / roles en tiempo real (`?role=...`).
* [x] **Cartelera del Día (`today_schedule`):**
* Grilla temporal por bloques horarios (07:00 a 21:00 hs) con indicadores físicos y virtuales.
* Filtro dinámico para ocultar clases virtuales (`hide_virtual=1`) y segmentación por piso o turno.
* [x] **Acople de Ficha de Reserva (`schedule.view_reservation`):**
* Ruteo en BFF (`/schedule/view_reservation?id=...` y `/view/:id`).
* Endpoint REST `/api/v1/reservations/<id>` con enriquecimiento relacional (aula, comisión, docente).
* Soporte para modificar reserva (`edit_reservation`) con selectores en cascada, confirmación y cancelación.
* [x] **Gestión de Comisiones (`admin/commissions_list`):**
* Botón y modal interactivo `+ Nueva Comisión` (`#modalAddCommission`).
* Vinculación obligatoria y explícita a la **Asignatura / Materia**, indicando cuatrimestre, año lectivo, turno, docente a cargo, cupo y enlace virtual.
* Visualización en tabla de la materia vinculada con su código y carrera asociada.
---
### Fase 2: Co-docencia, Matriz de Conflictos y Regla Diaria ✅ *(100% Completado)*
* **Objetivo:** Implementar las reglas de negocio académicas complejas para asignación de cátedras y cursada de alumnos.
* **Estadios:**
1. **Estadio 2.1 — Modelo de Co-docencia:**
- [x] Tabla relacional `commission_teachers` para soportar múltiples docentes por comisión (titulares, adjuntos, ayudantes).
- [x] Endpoints `/api/v1/commissions/<id>/teachers` para asociar y desvincular docentes de cátedra.
- [x] Adaptación de vistas de Bedelía y Comisiones para visualizar el equipo docente completo.
2. **Estadio 2.2 — Matriz de Conflictos y Validación:**
- [x] Validación estricta de conflicto físico: bloqueo de doble asignación de aula en mismo día y horario.
- [x] Validación de conflicto docente: detección de superposición horaria del profesor, con soporte de excepción justificada cuando la comisión cuenta con co-docencia.
- [x] Validación de aforo: bloqueo cuando la cantidad de alumnos excede la capacidad del aula física.
3. **Estadio 2.3 — Regla de Restricción Diaria del Alumno:**
- [x] Validación al matricular: un alumno no puede cursar dos asignaturas regulares en el mismo día calendario.
- [x] Excepción parametrizable: autorización automática si al menos una de las materias es un "curso corto" (`is_short_course`) o si existe autorización manual de Bedelía (`allow_same_day_exception`).
---
### Fase 3: Gestión de Hitos Evaluativos y Libro de Calificaciones 📅 *(Completada)*
* **Objetivo:** Proveer al cuerpo docente y estudiantil el seguimiento completo de instancias evaluativas.
* **Estadios:**
1. **Estadio 3.1 — Calendario de Evaluación por Comisión:**
- [x] Programación de parciales, recuperatorios, entregas de trabajos prácticos y exámenes finales.
- [x] Notificaciones preventivas en el dashboard del alumno con cuenta regresiva para exámenes.
2. **Estadio 3.2 — Libro de Calificaciones (*Gradebook*):**
- [x] Matriz de carga rápida de notas para docentes con autoguardado asíncrono.
- [x] Consulta individualizada de calificaciones y retroalimentaciones pedagógicas para alumnos.
- [x] Cierre de actas de regularidad y promoción para Bedelía.
---
### Fase 4: UI/UX Avanzada para Bedelía & Modo Impersonación 🖥️ ✅ *(100% Completado)*
* **Objetivo:** Dotar a la oficina de Bedelía y a la Administración de herramientas interactivas de última generación.
* **Estadios:**
1. **Estadio 4.1 — Grilla Semanal Interactiva (Drag-and-Drop):**
- [x] Interfaz tipo TimeGrid interactiva con arrastre de comisiones para asignación rápida de aulas y turnos (`FullCalendar` `editable: true` + `droppable: true`).
- [x] Panel lateral de comisiones pendientes de aula (`unassigned_commissions`) con arrastre directo hacia la grilla.
- [x] Detección visual en tiempo real de aulas ocupadas, colisiones horarias, aforo insuficiente o choques de docentes con reversión automática y mensajes de alerta descriptivos vía `POST /api/v1/reservations/drag-update`.
2. **Estadio 4.2 — Modo Impersonación del Superadmin:**
- [x] Funcionalidad de *login as* con soporte para cabecera `X-Impersonate-User` en Backend Flask (`jwt_required`) y Frontend BFF (`authMiddleware`).
- [x] Botón directo de impersonación en la lista administrativa de usuarios (`admin/users/list.html`).
- [x] Banner de advertencia visual permanente en la barra superior con indicador de usuario impersonado y botón de salida inmediata hacia la sesión administrativa.
- [x] Trazabilidad obligatoria y estricta en el registro de auditoría (`audit_logs`) con eventos `IMPERSONATE_START` e `IMPERSONATE_END`.
3. **Estadio 4.3 — Integración del Optimizador Genético:**
- [x] Acople del motor heurístico de algoritmos genéticos a la base de datos real con cálculo de turnos reales (Mañana, Tarde, Vespertino).
- [x] Prevención de choques en guardado masivo con persistencia directa en base de datos (`POST /api/genetic/apply-optimization`).
---
### Fase 5: Integración Auth, Email & Moodle Backend 🛡️ ✉️ 🎓 ✅ *(100% Completado)*
* **Objetivo:** Centralizar la gestión de credenciales, autenticación híbrida, motor transaccional de correo y sincronización bidireccional asíncrona con Moodle 4.1 con tolerancia total a fallos.
* **Épicas Entregadas:**
1. **Épica 1 — Panel de Configuración Global (Perfil ADMIN):**
- [x] Módulo SMTP: UI/API dinámica con host, puerto, usuario, seguridad (TLS/SSL/NONE) y contraseña cifrada con Fernet (`/admin/settings`).
- [x] Módulo SSO: Toggles para habilitar/deshabilitar Login Local, Google OAuth 2.0 y Moodle SSO en base de datos.
- [x] Credenciales OAuth & Moodle: Client ID/Secret de Google y URL de Servidor / Token Web Services de Moodle 4.1.
2. **Épica 2 — Infraestructura Asíncrona y Caché:**
- [x] Capa de Caché Híbrida: `CacheService` con integración Redis y fallback en memoria/TTL.
- [x] Cola Persistente `MoodleSyncTask` con reintentos exponenciales y Dead Letter Queue (DLQ).
- [x] Panel de monitorización de cola con métricas en tiempo real, botón de "Forzar Sincronización Inmediata" y reintento masivo de tareas fallidas.
3. **Épica 3 — Autenticación Híbrida (SSO & Local Tolerante a Fallos):**
- [x] Login Local: Fallback con contraseña nativa y contingencia para ADMIN cuando está desactivado para usuarios generales.
- [x] Google OAuth 2.0: Restricción arquitectónica de dominios (`@unicaba.edu.ar`, `@lasalle.edu.ar`) inspirada en AlumnosLS.
- [x] Moodle Delegated Login: Autenticación contra `/login/token.php` de Moodle 4.1 con mapeo inicial de roles (Admin/Docente/Alumno) y desacople local para cambios posteriores por Bedelía/Admin.
4. **Épica 4 — Adaptadores Moodle 4.1 (Bidireccional):**
- [x] Cliente REST Moodle 4.1 (`moodle_client`) con soporte para `core_user_create_users`, `core_user_update_users`, `core_user_get_users`, `enrol_manual_enrol_users`, `enrol_manual_unenrol_users`, `core_enrol_get_enrolled_users`, `core_role_assign_roles`, `core_role_unassign_roles`.
- [x] Encolado automático y no bloqueante al crear o editar usuarios en Edu-Space.
5. **Épica 5 — Motor de Notificaciones (Email Dinámico):**
- [x] Transporte SMTP dinámico (`email_service`) instanciado en tiempo de ejecución leyendo credenciales descifradas de la BD.
- [x] Notificaciones transaccionales automáticas para profesores (asignación de comisiones, cronogramas de exámenes y alertas de sistema).
---
### Fase 5.1: Bedelía UX, Cobertura Integral de ABMs y Purga Segura de Datos 🏛️ ⚡ ✅ *(100% Completado)*
* **Objetivo:** Optimizar de punta a punta la experiencia de usuario de Bedelía, dotar de ABMs completos a todas las entidades de Espacios, Académica y Reservas, y asegurar la purga de datos sin comprometer identidades ni claves foráneas.
* **Entregables:**
1. **Circuito Ágil de Bedelía:**
- [x] Flujo de asignación ágil: de lista de comisiones (`/admin/commissions_list`) a reserva de aula (`/schedule/add_reservation?commission_id=...`) con 1 clic.
- [x] Sincronización en cascada de selectores (Edificio -> Piso -> Aula) con detección de modalidad física/virtual y aforo.
- [x] Conexión de reservas con comisiones activas en vivo vía API REST desacoplada (fin de mocks estáticos).
- [x] Creación de aulas con vinculación consistente de sede y tipología.
2. **Cobertura ABM 100% (Espacios, Académica y Reservas):**
- [x] **Ciclos Lectivos (`AcademicTerm`):** ABM completo (Crear, Editar, Activar como Ciclo Actual, Toggle Activo/Inactivo rápido y Borrado protegido con soft-deactivate ante comisiones asociadas). Endpoints `/api/v1/admin/academic-terms` y vistas en `/admin/academic_terms`.
- [x] **Aulas y Espacios Físicos/Virtuales (`Classroom`):** ABM completo (Alta, Edición de aforo y piso, Toggle rápido activo/inactivo vía `/api/v1/classrooms/<id>/toggle`, y Eliminación con validación de reservas previas). Botones y modales en lista y detalle.
- [x] **Sedes y Edificios (`Building`):** ABM completo (Crear, Editar, Toggle y Eliminar sedes físicas e institucionales).
- [x] **Carreras (`Career`):** ABM completo (`/admin/careers_list`) con protección ante asignaturas existentes (soft-deactivation).
- [x] **Asignaturas (`Subject`):** ABM completo (`/admin/subjects_list`) con vinculación por carrera y mitigación de desvinculación forzada.
- [x] **Comisiones (`Commission`):** ABM completo (`/admin/commissions_list`) con asignación directa de profesores, turnos y cupos.
- [x] **Reservas (`Reservation`):** ABM completo (Creación, Edición, Confirmación, Cancelación lógica y Eliminación definitiva / Hard Delete con `/api/v1/reservations/<id>?hard=true`).
3. **Purga Segura de Datos Académicos:**
- [x] Modal de confirmación interactivo en frontend (`#purgeConfirmModal`) con feedback visual y prevención de borrado accidental.
- [x] Secuencia de purga backend en estricto orden de integridad referencial (respetando Foreign Keys).
- [x] Preservación garantizada de usuarios y roles RBAC ante reseteos de datos de cursada.
4. **Configuración y Personalización UI:**
- [x] Panel de configuración global (`/admin/settings`) con opción para habilitar o deshabilitar el saludo superior y banner de rol en el dashboard.
5. **Inicialización y Despliegue con Base Limpia:**
- [x] Soporte `--empty-academic` / `--no-demo` en `install.sh` e `init_db.py` para inicializar el sistema con roles y usuarios intactos pero con tablas académicas y de espacios totalmente vacías para configuración desde cero.
---
### Fase 6: Producción Institucional, CI/CD y Despliegue 🏢 *(En curso)*
* **Objetivo:** Puesta en marcha definitiva en la infraestructura de servidores de UniCABA.
* **Estadios:**
1. **Estadio 6.1 — Despliegue e Infraestructura:**
- [ ] `docker-compose.yml` productivo orquestando Flask (Gunicorn), Node.js BFF (PM2) y PostgreSQL 15.
- [ ] Proxy inverso Nginx con certificados SSL/TLS y compresión Brotli/Gzip.
2. **Estadio 6.2 — Sincronización Continua Moodle:**
- [x] Sincronización automática de aulas virtuales y usuarios con Moodle 4.1 institucional (`10.0.0.207`).
- [ ] Automatización de workers persistentes (systemd / supervisor) para el procesamiento continuo de la cola.
3. **Estadio 6.3 — Pruebas de Carga y Hardening:**
- [ ] Pruebas de estrés de concurrencia en días pico de inicio de cuatrimestre (10.000 solicitudes simultáneas).
---
## 📈 Criterios de Aceptación del MVP
1. **Zero Colisiones Físicas:** Imposibilidad absoluta de asignar dos materias simultáneas a una misma aula física.
2. **Virtualidad Fluida:** Acceso con un clic a reuniones virtuales válidas para el 100% de las comisiones remotas.
3. **Roles Seguros:** Separación total de permisos donde ningún alumno o docente acceda a configuración global ni a datos privados de otras comisiones.
4. **Respuesta Sub-segundo:** Carga de carteleras y calendarios en menos de 300 ms en el BFF Node.js.
+112
View File
@@ -0,0 +1,112 @@
# Informe de Auditoría y Seguridad Automatizada (Python & Node.js)
**Proyecto:** Edu-Space Admin Architecture
**Fecha:** Septiembre 2026 (Actualización Post Fase 5)
**Entorno:** Backend Flask (REST API) + Node.js BFF (Express) + SQLite / PostgreSQL
**Estado General:** Aprobado ✅ (`[PASS]` en los 5 controles automatizados, 0 vulnerabilidades conocidas, 0 fallos críticos SAST/DAST)
---
## 1. Resumen Ejecutivo
Se ejecutó y validó la suite completa del **Plan de Auditoría y Seguridad Automatizada** que cubre el ciclo de vida completo de las dos capas de la plataforma:
- **Capa Core API (Python / Flask)**: Análisis Estático (SAST), Análisis de Dependencias de Terceros (SCA), Pruebas Dinámicas / Fuzzing contra especificación OpenAPI 3.0.3 (DAST).
- **Capa BFF / Frontend Server (Node.js / Express)**: Análisis Estático (SAST), Análisis de Dependencias (SCA) y Blindaje Activo con cabeceras HTTP (`helmet`) y limitador de tasa (`express-rate-limit`).
Todos los controles fueron unificados en el script ejecutable [security_audit.bat](file:///c:/Users/Soporte%20IT/workspace/admin-edu-space/security_audit.bat), compatible con ejecuciones interactivas en Windows y modos desatendidos (`--no-pause`) para integración continua.
---
## 2. Capa Backend Python (Flask API)
### 2.1. Análisis Estático de Código Fuente (SAST) - `Bandit`
- **Herramienta:** Bandit v1.8.3 (`backend/venv/Scripts/bandit.exe`)
- **Comando:** `bandit -r backend/app -ll -ii`
- **Líneas Escaneadas:** 11.321 líneas de código Python analizadas en toda la aplicación.
- **Hallazgos y Remediaciones:**
1. *CWE-22 / B310 en `sheets_importer.py`:* Uso de `urllib.request.urlopen` sin validación estricta de esquema. Remediado validando `url.startswith('https://')` o `http://` y documentando la verificación con `# nosec B310`.
2. *CWE-829 / B113 en `genetic_algorithm.py`:* Falso positivo producido por el parámetro de dominio `requests` (lista de solicitudes de aula `ReservationRequest`) que colisionaba con el analizador de llamadas HTTP sin timeout. Remediado renombrando el parámetro a `reservation_requests` con tipado estricto.
- **Resultado Actual:** **0 problemas identificados** (Medium = 0, High = 0).
### 2.2. Auditoría de Dependencias de Terceros (SCA) - `Pip-Audit`
- **Herramienta:** Pip-Audit v2.10.1 (`backend/venv/Scripts/pip-audit.exe`)
- **Comando:** `pip-audit -s osv --progress-spinner off -r backend/requirements.txt` (con fallback de resiliencia automática a servicio PyPI ante indisponibilidad de red).
- **Librerías Core Aseguradas:**
- `Flask>=3.1.3`
- `Werkzeug>=3.1.6` (v3.1.8 instalada)
- `requests>=2.32.4` (v2.34.2 instalada)
- `bleach>=6.4.0`
- `python-dotenv>=1.2.2` (v1.2.3 instalada)
- `cryptography>=44.0.0`
- **Resultado Actual:** **No known vulnerabilities found** (0 CVEs pendientes).
### 2.3. Pruebas Dinámicas y Fuzzing de API REST (DAST) - `Schemathesis`
- **Herramienta:** Schemathesis v4.27.4 (`backend/venv/Scripts/st.exe`)
- **Especificación OpenAPI:** OpenAPI 3.0.3 en `/api/v1/openapi.json`.
- **Comando:** `st run http://127.0.0.1:5000/api/v1/openapi.json --checks not_a_server_error --max-examples=10 --no-color`
- **Fuzzing & Robustez de Endpoints:**
- `POST /api/v1/auth/login`: Blindado contra payloads no estructurados (JSON arrays anómalos o tipos no diccionario devuelven `400 Bad Request` antes de invocar DTOs). Manejo seguro de base de datos garantizando códigos `401 Unauthorized` ante credenciales erróneas o usuarios no existentes sin generar fallos 500 no capturados.
- `GET /api/v1/admin/subjects`, `GET /api/v1/admin/users`, `GET /api/v1/auth/me`, `GET /api/v1/classrooms`: Rechazan peticiones sin token JWT con código `401 Unauthorized`.
- **Resultado Actual:** **114 casos de prueba generados y superados con éxito**, **0 errores 500 del servidor** (100% PASS).
---
## 3. Capa Backend Node.js (Express BFF)
### 3.1. Análisis Estático de Código Fuente (SAST) - `njsscan`
- **Herramienta:** NodeJsScan v1.0.0 (`backend/venv/Scripts/njsscan.exe`)
- **Comando:** `njsscan frontend/src`
- **Reglas Evaluadas:** Inyecciones de código, llamadas a `eval()`, exposición de credenciales hardcodeadas, omisión de headers de seguridad, CORS inseguro.
- **Resultado:** **No issues found** (0 problemas de seguridad).
### 3.2. Blindaje de Middleware (`helmet` & `express-rate-limit`)
- **Paquetes:** `helmet`, `express-rate-limit` en `frontend/src/app.js`.
- **Protecciones Activas:**
- `app.disable('x-powered-by')`: Oculta el motor Express.
- `helmet`:
- `X-Content-Type-Options: nosniff`
- `X-Frame-Options: SAMEORIGIN` (prevención de Clickjacking)
- `Strict-Transport-Security: max-age=31536000; includeSubDomains` (HSTS)
- `Cross-Origin-Opener-Policy: same-origin`
- `Cross-Origin-Resource-Policy: same-origin`
- `express-rate-limit`:
- `/auth/login`: Límite estricto de 30 peticiones por ventana de 15 minutos por IP (mitigación de ataques de fuerza bruta).
- Endpoints `/api`: Límite de 180 peticiones por minuto por IP (mitigación de scraping y saturación).
### 3.3. Auditoría de Dependencias (SCA) - `npm audit`
- **Herramienta:** `npm audit` nativo en `frontend/`
- **Comando:** `cmd.exe /c npm audit`
- **Resultado:** **found 0 vulnerabilities** en 108 dependencias evaluadas.
---
## 4. Automatización de la Suite de Seguridad
El archivo [security_audit.bat](file:///c:/Users/Soporte%20IT/workspace/admin-edu-space/security_audit.bat) provee la suite de ejecución automatizada:
```cmd
:: Ejecución interactiva con consola Windows:
security_audit.bat
:: Ejecución desatendida / CI:
security_audit.bat --no-pause
```
### Características de la suite adaptada:
1. **Página de códigos UTF-8 (`chcp 65001`) y variables de entorno Python (`PYTHONUTF8=1`):** Evita fallos de codificación `charmap` en terminales Windows tradicionales.
2. **Fallback resiliente en `pip-audit`:** Conmutación automática a base PyPI en caso de indisponibilidad temporal de la API OSV.
3. **Comprobación de conectividad al backend:** Antes de lanzar Schemathesis DAST, verifica la respuesta HTTP de `/api/v1/openapi.json`. Si el backend está inactivo, emite una advertencia sin abortar los controles estáticos previos.
4. **Bandera `--no-pause`:** Permite integración fluida en pipelines de CI/CD conservando la pausa para desarrolladores que ejecuten por doble click.
---
## 5. Matriz de Resultados Finales
| Control | Capa | Herramienta | Métricas Escaneadas | Estado Final |
|---|---|---|---|:---:|
| **SAST (Python)** | Flask API | `bandit` | 11.321 líneas de código | **0 Issues (PASS)** ✅ |
| **SCA (Python)** | Flask API | `pip-audit` | 42 librerías en requirements.txt | **0 CVEs (PASS)** ✅ |
| **SAST (Node.js)**| Express BFF| `njsscan` | Archivos en `frontend/src` | **0 Issues (PASS)** ✅ |
| **SCA (Node.js)** | Express BFF| `npm audit` | 108 paquetes npm | **0 Vulnerabilidades (PASS)** ✅ |
| **DAST (Python)** | Flask API | `schemathesis` | 114 casos de prueba generados | **114/114 Pasados - 0 Error 500 (PASS)** ✅ |
| **Protección HTTP** | Express BFF| `helmet` + `rate-limit` | HSTS, nosniff, limiters activos | **Activo y Blindado** ✅ |
**Dictamen:** **SUITE DE SEGURIDAD APROBADA AL 100% [PASS]**.
+42
View File
@@ -0,0 +1,42 @@
# Constitución de admin-edu-space
Principios innegociables y mandatorios del Software System Design (SSD). Toda especificación, diseño, plan y tarea del agente debe cumplirlos estrictamente sin excepción.
---
### 1. La Especificación y el SSD Mandan
Nada se implementa, refactoriza o modifica en la plataforma si no está documentado en la especificación activa o alineado con el Software System Design (SSD). Si se detecta un caso de uso no previsto o una ambigüedad en los requerimientos, se detiene la ejecución y se consulta al responsable del proyecto antes de avanzar.
### 2. Arquitectura Desacoplada (Backend RESTful + Frontend BFF)
El sistema opera bajo una arquitectura desacoplada de dos capas:
- **Backend Core API (Python / Flask + SQLAlchemy)**: Expone exclusivamente servicios RESTful bajo el prefijo `/api/v1/`, retornando respuestas JSON estructuradas con serializadores/DTOs. Gestiona la autenticación stateless mediante tokens JWT (HS256), la integridad referencial en base de datos y el pipeline de blindaje `SecurityFilterChain`.
- **Frontend BFF (Node.js / Express + Nunjucks)**: Orquesta la presentación y la experiencia de usuario (UX), mantiene la sesión mediante cookies seguras `HttpOnly`, inyecta encabezados de autorización Bearer en llamadas Axios hacia el backend y adapta las vistas según el rol del usuario autenticado.
### 3. Reemplazo Definitivo del Excel como Herramienta Operativa
El objetivo primordial del sistema es erradicar el uso del archivo Excel/planilla como herramienta de gestión cotidiana de Bedelía, convirtiendo a la plataforma en la **única fuente de verdad** (Single Source of Truth) para la administración de espacios, comisiones y cursadas a través del ciclo estructurado de 9 pasos (Sedes -> Aulas -> Ciclos Lectivos -> Carreras -> Asignaturas -> Comisiones -> Profesores -> Alumnos -> Reservas). Toda asignatura debe pertenecer a su carrera y toda comisión hereda y expone esta pertenencia institucional para filtros y reportes académicos.
- La importación desde Google Sheets / planillas externas se mantiene exclusivamente como mecanismo de **ingesta masiva inicial y compatibilidad**, mientras que todas las altas, modificaciones, cancelaciones y reubicaciones deben realizarse directamente en la plataforma.
### 4. Matriz Infranqueable de Conflictos Académicos y Espaciales
La asignación de reservas de aulas debe validar en tiempo real e impedir de forma determinística:
1. **Conflicto Físico**: Doble asignación horaria en una misma aula presencial para el mismo día y bloque horario.
2. **Conflicto de Aforo**: Asignación de una comisión cuyo cupo estimado supere la capacidad física del aula.
3. **Conflicto Docente**: Superposición horaria de un profesor en múltiples espacios simultáneos, permitiendo excepción **únicamente** cuando la comisión cuenta con co-docencia activa registrada en `CommissionTeacher`.
4. **Restricción Diaria del Alumno**: Bloqueo de cursada de dos asignaturas regulares en el mismo día de la semana, exceptuando talleres/cursos cortos (`is_short_course`) o autorización expresa y justificada de Bedelía (`allow_same_day_exception`).
### 5. Caché First y Resiliencia en Servicios Externos (Moodle 4.1 & SMTP)
- Toda consulta de datos o perfiles provenientes de Moodle 4.1 debe consultar en primer término la capa de caché (`CacheService` en Redis o memoria).
- Toda operación de sincronización hacia Moodle debe encolarse de forma asíncrona no bloqueante (`MoodleSyncTask`) utilizando reintentos exponenciales (*Exponential Backoff*) y derivación a Dead Letter Queue (DLQ) ante indisponibilidad.
- Prohibidas las peticiones síncronas bloqueantes a servicios externos dentro de las transacciones de los controladores web.
- El servicio de correo transaccional (`EmailService`) debe utilizar credenciales dinámicas descifradas con Fernet sin impactar los tiempos de respuesta.
### 6. Privacidad Estricta, Blindaje RBAC y Trazabilidad
- Los datos de alumnos, docentes y credenciales de acceso son de máxima confidencialidad. Ningún endpoint debe exponer contraseñas, secretos o información privada a roles no autorizados.
- La autenticación institucional de Google Workspace debe validar estrictamente los dominios institucionales autorizados (`@unicaba.edu.ar`).
- Toda acción sensible (reseteo de sistema, impersonación de usuarios, reapertura/cierre de actas de notas) debe quedar registrada de forma inmutable en la tabla de auditoría (`AuditLog`).
### 7. Convenciones de Código e Idioma
- **Código Fuente**: Nombres de variables, clases, métodos, commits y pruebas en **inglés**.
- **Interfaz y Documentación**: Vistas, mensajes de error, respuestas al usuario, correos electrónicos y documentación operativa en **español**.
### 8. Testing Automatizado como Puerta de Enlace (Quality Gate)
- La suite de pruebas automatizadas (`pytest backend/tests`) y los controles de seguridad SAST/DAST/SCA (`security_audit.bat`) son mandatorios.
- Queda terminantemente prohibido cerrar una tarea o fusionar cambios a la rama de integración con pruebas fallando o vulnerabilidades críticas no remediadas.