Files

T

carlostellocba 7ad4e3f099 feat: completar fases 3 y 4 del roadmap mvp (gradebook, drag-and-drop, impersonacion) y actualizar README

2026-09-23 12:10:31 -03:00

11 KiB

Raw Blame History

Panel de Administración Edu-Space (UniCABA)

Plataforma integral de gestión áulica, asignación de espacios, control de horarios, seguimiento académico y reservas para la Universidad de la Ciudad de Buenos Aires (UniCABA).

El proyecto se basa en una arquitectura desacoplada (Frontend / Backend) en formato monorepo.

Versión Actual: 2.8.0 (Fases 0 a 4 del Roadmap MVP 100% completadas)
Institución: Universidad de la Ciudad de Buenos Aires (UniCABA)

🗺️ Estado del Roadmap MVP

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: Despliegue Producción e Integrac.[░░░░░░░░░░░░░░░░░░░░]   0% (Planificada)

🏛️ Sede Institucional y Ubicaciones

Sede Central UniCABA: Tte. Gral. Juan Domingo Perón 802, Ciudad Autónoma de Buenos Aires (CABA) — Aulas de grado, auditorio principal y laboratorios distribuidos desde Planta Baja (Piso 0) hasta el 4.° Piso.
Campus Virtual: Espacio áulico digital integrado (Microsoft Teams / Moodle) configurado con capacidad ilimitada (\infty).

🏗️ Arquitectura del Proyecto (Monorepo)

El repositorio está dividido en dos aplicaciones principales que interactúan mediante una API REST y un patrón Backend-For-Frontend (BFF).

/
├── backend/                  # API REST Backend (Python / Flask)
│   ├── app/                  # Lógica de negocio, base de datos y endpoints
│   ├── tests/                # Pruebas unitarias e integración
│   └── requirements.txt      # Dependencias de Python
│
├── frontend/                 # Backend-For-Frontend (Node.js / Express)
│   ├── src/                  # Controladores, middleware, servicios (Axios)
│   ├── views/                # Plantillas Nunjucks (.html)
│   ├── public/               # Archivos estáticos (CSS, JS cliente)
│   └── package.json          # Dependencias de Node.js
│
├── docs/                     # Historial de cambios y documentación técnica
└── unicaba_prerequitos/      # Requisitos académicos y de negocio

🐍 Backend (Python + Flask)

Funciona exclusivamente como una REST API que expone endpoints bajo /api/v1/ retornando JSON.
Encargado de la persistencia de datos (SQLAlchemy / PostgreSQL), lógica de negocio dura, JWT auth service, seguridad, y algoritmos de optimización (Módulo Predictivo).
Prohibido retornar HTML o utilizar Jinja2/render_template en este entorno.

🟢 Frontend BFF (Node.js + Express)

Aplicación de servicio que renderiza las vistas para el cliente mediante Nunjucks.
Gestiona la sesión segura del usuario almacenando el token JWT recibido de Flask en una Cookie HttpOnly.
Actúa como proxy de conexión con el Backend de Python empleando Axios (inyectando el Bearer token interceptado).
Utiliza Chart.js y JS vanilla en el lado del cliente para visualizaciones interactivas.

🎯 Dashboards Personalizados por Rol

La plataforma cuenta con paneles adaptados a las necesidades operativas de cada perfil institucional:

Administrador (/dashboard?role=admin): Cockpit institucional con métricas globales, auditoría de seguridad RBAC, tendencias mensuales y panel interactivo de Estado y Percentiles de Asignación de Aulas Físicas (asignadas vs disponibles en número y porcentaje).
Bedelía (/dashboard?role=bedelia): Control operativo del campus en tiempo real, balance de aulas presenciales asignadas (96.3%) y libres (3.7%), cartelera del día y bandeja de aprobación de reservas pendientes.
Docente / Profesor (/dashboard?role=docente): Sesiones del día con accesos directos a videollamadas y gestión de comisiones.
Alumno / Estudiante (/dashboard?role=alumno): Brújula de cursada "¿Dónde curso hoy?" con ubicación por piso y aula o enlace virtual, junto al cronograma de exámenes y entregas de TPs.

Modo Vista Previa: Los usuarios con perfil administrador o directivo pueden previsualizar cualquier perspectiva utilizando el selector de roles en la barra superior o pasando el parámetro ?role={admin|bedelia|docente|alumno} en la URL.

☁️ Sincronización Google Sheets, Configuración Global & Purga Académica

El sistema incluye sincronización automatizada con las planillas oficiales de cursada de UniCABA:

Configuración Global Dinámica: Selección y persistencia de la URL de Google Sheets directamente desde la interfaz web (/admin/google_sheets_import) sin valores fijos en el código.
Herramienta de Purga y Reinicio (reset_academic_data): Módulo CLI y web para limpiar selectivamente reservas, aulas, asignaturas, comisiones o carreras, garantizando pruebas limpias desde cero y preservando siempre usuarios y credenciales.
Concurrencia Virtual Ilimitada: Reconocimiento de espacios áulicos remotos (Campus Virtual · VIRTUAL), permitiendo la coexistencia de múltiples comisiones en la misma franja horaria sin colisiones de agenda.
Catálogo Presencial con Cursadas Asignadas: Listado de aulas físicas con cálculo de ocupación real (semana/mes), vista previa de asignaturas y enlaces directos a calendario y ficha del espacio.
Enlaces de Videollamada Automáticos: Generación de enlaces seguros (Google Meet / Teams) para acceso instantáneo de docentes y estudiantes.
Filtros en Cartelera: Opciones para filtrar por turno, piso u ocultar aulas virtuales mediante el switch dedicado en /schedule/today_schedule.

⚡ Capacidades Avanzadas de Gestión (Fases 2, 3 y 4 del MVP)

1. Grilla Semanal Interactiva (Drag & Drop) y Validación de Colisiones en Tiempo Real

FullCalendar Interactivo: Arrastre y edición de horarios directo en el calendario general de Bedelía (/schedule/calendar).
Sidebar de Comisiones por Asignar: Panel lateral colapsable con las comisiones sin aula, con arrastre fluido hacia la grilla semanal o diaria.
Detección Automática de Choques (HTTP 409): Validación previa ante cada movimiento (POST /api/v1/reservations/drag-update) verificando colisiones físicas de aula, superposición docente y límite de aforo. Si hay conflicto, el evento se revierte automáticamente (info.revert()) y se notifica al usuario con un Toast explicativo.

Permite al Administrador navegar la plataforma adoptando exactamente la perspectiva y permisos de cualquier docente o estudiante.
Activación con un clic (bi-incognito) desde el catálogo de usuarios (/admin/users_list).
Banner superior permanente de advertencia visual en color ámbar con identificación del usuario adoptado y botón de salida inmediata.
Trazabilidad y auditoría obligatoria inmutable en audit_logs (IMPERSONATE_START e IMPERSONATE_END).

3. Libro de Calificaciones (Gradebook) & Cierre Formal de Actas

Matriz bidimensional interactiva de calificaciones por comisión (/schedule/gradebook/:id) con autoguardado asíncrono debounced (500 ms).
Cálculo en vivo de promedios ponderados y condiciones académicas (Promocionado, Regular, Libre).
Cierre formal de actas con generación de código inmutable (ACTA-YYYY-Sem-ID), auditoría en audit_logs y congelamiento de modificaciones.
Soporte para reapertura excepcional justificada por Bedelía.
Portal del Estudiante (/schedule/my_grades / /mis-materias/mis-notas) para consulta de calificaciones y comprobantes.

4. Co-docencia, Matriz de Conflictos y Regla Diaria

Soporte de cátedras con múltiples docentes por comisión (CommissionTeacher).
Excepción por co-docencia: autoriza superposiciones de horario docente si la cátedra cuenta con un co-docente registrado disponible.
Regla restrictiva de cursada diaria: un alumno no puede cursar dos asignaturas regulares el mismo día, con excepciones automáticas para talleres/cursos cortos (is_short_course) o autorizaciones especiales emitidas por Bedelía.

📅 Ficha de Reserva & Gestión de Comisiones

Ficha de Reserva Detallada (/schedule/view_reservation?id={id}): Información completa del espacio físico o virtual asignado, capacidad y asistencia prevista, comisión académica vinculada, docente a cargo, botones de acción inmediata (Modificar Reserva, Confirmar Reserva, Cancelar Reserva) y acceso con un clic a la sala de videollamada.
Gestión de Comisiones y Vinculación con Asignaturas (/admin/commissions_list):
- Botón y modal interactivo Nueva Comisión (#modalAddCommission) para registrar comisiones y vincularlas directamente a su Asignatura / Materia, indicando cuatrimestre, año, turno, cupo y docente responsable.
- Generación automática de enlace institucional de Google Meet cuando no se especifica un enlace propio.
- Tabla operativa con visualización explícita del código de comisión, nombre de materia, código de asignatura y carrera.

🚀 Instalación y Despliegue Local

Requisitos previos

Node.js (v18 o superior)
Python 3.10+
SQLite / PostgreSQL

1. Iniciar el Backend (Flask)

cd backend
python -m venv venv
# Activar venv (Windows: venv\Scripts\activate, Linux/Mac: source venv/bin/activate)
pip install -r requirements.txt
flask run --port=5000

(El backend quedará escuchando en http://localhost:5000)

2. Iniciar el Frontend (Node/Express)

cd frontend
npm install
npm run dev
# o en su defecto:
node src/app.js

(El frontend quedará escuchando en http://localhost:3000)

🧪 Pruebas Automatizadas

Para ejecutar la suite completa de pruebas unitarias de regresión (Fases 2, 3 y 4):

cd backend
.\venv\Scripts\python.exe -m unittest tests/test_phase2_rules.py tests/test_phase3_gradebook.py tests/test_phase4_interactive_impersonation.py

11 KiB Raw Blame History