admin-edu-space/docs/CHANGELOG_VIRTUAL_CLASSES_AND_DASHBOARDS.md

Changelog: Corrección del Importador de Google Sheets, Clases Virtuales y Dashboards por Rol

Fecha: 18 de Septiembre de 2026
Rama: testing
Autor: Antigravity AI Assistant

---

1. Resumen Ejecutivo

Se investigó y resolvió la causa por la cual el importador de horarios desde Google Sheets no traía la totalidad de las clases virtuales ni se mostraban correctamente en las vistas del sistema (Cartelera de Hoy, Catálogo de Aulas Virtuales, Cronograma y Dashboards), tal como ocurría en la versión legacy.

Causas Raíz Identificadas:

1. Colisión de Horarios en Aulas Virtuales durante el Sync (sheets_importer.py):
   • En la versión original, al buscar una reserva preexistente (Reservation.query.filter_by(classroom_id=classroom.id, start_time=dt_start, end_time=dt_end).first()), todas las clases virtuales apuntaban al mismo espacio (Campus Virtual · VIRTUAL).
   • Cuando múltiples comisiones de diferentes asignaturas cursaban de manera virtual en la misma franja horaria (por ejemplo, jueves de 17:30 a 21:30 hs donde hay 13 comisiones simultáneas), el importador encontraba la primera reserva creada y descartaba las restantes 12 clases simultáneas actualizando únicamente notas/turno. Esto descartaba más del 75% de las clases virtuales de la planilla.
2. Ausencia de Enlace Virtual Automático:
   • Las reservas virtuales se generaban sin enlace de videollamada (virtual_link = None), impidiendo que los botones de acceso directo ("Unirse a Videollamada / Zoom / Meet") se renderizaran en las vistas.
3. Serialización Incompleta en la API Backend (api/v1/reservations):
   • El endpoint /api/v1/reservations retornaba diccionarios planos sin el objeto anidado classroom, omitiendo propiedades críticas como is_virtual, effective_virtual_link, subject_name, subject_code y location_display.
4. Falta de Agregación de Salas Virtuales en el BFF Node.js (classrooms.js):
   • En el catálogo de aulas (/classrooms/list_classrooms?view_mode=virtual), la plantilla esperaba un arreglo virtual_rooms agrupado por comisión con métricas de demanda (today_count, week_count, month_count) y global_virtual_metrics. El controlador Node no las generaba, dejando la vista vacía.
5. Rutas y Vista de Cartelera del Día (schedule.js y app.js):
   • /schedule/today_schedule no estaba mapeado directamente en el enrutador de Express y su redirección descartaba parámetros de búsqueda (hide_virtual, shift, floor).
   • El controlador no calculaba time_blocks (horas 7 a 21), provocando que schedule/today.html cayera en la condición vacía ("No hay reservas programadas para hoy").

---

2. Soluciones Implementadas

A. Backend Python (backend/app/services/sheets_importer.py)

• Se diferenció la comprobación de unicidad para aulas virtuales: al tratarse de espacios con concurrencia ilimitada, la consulta de reserva existente incluye commission_id=commission.id.
• Se implementó la generación automática de enlaces de reunión seguros (https://meet.google.com/edu-{subject_code}-{commission_code}) para todas las clases y comisiones en modalidad virtual.
• Resultado del re-sync: Se procesaron 239 filas de las 6 hojas semanales, añadiendo 280 reservas que antes colisionaban, alcanzando 388 reservas virtuales activas en la base de datos con sus respectivos enlaces de videollamada.

B. Endpoint de Reservas (backend/app/routes/api/reservations.py)

• Se enriqueció la serialización de reservas incorporando:
  • Objeto anidado classroom con code, floor, floor_display, is_virtual y location_display.
  • Objeto commission con code y virtual_link.
  • Propiedades computadas subject_name, subject_code, effective_virtual_link e is_virtual.
• Se añadieron filtros por query params: hide_virtual, floor, shift y search.

C. Catálogo de Aulas Virtuales (frontend/src/routes/classrooms.js)

• Para view_mode === 'virtual', se implementó la agregación de reservas por comisión, calculando:
  • virtual_rooms: Listado con código de comisión, asignatura, enlace de videollamada, cupo, turno y conteos de sesiones (Hoy, Semana, Mes).
  • global_virtual_metrics: Contadores globales de clases remotas de hoy, semana, mes y comisiones con entorno virtual activo.
  • Asignación de virtual_classroom_id para enlaces de gestión.

D. Cartelera del Día (frontend/src/routes/schedule.js y frontend/src/app.js)

• Se unificaron las rutas /today y /today_schedule.
• Se implementó el generador de time_blocks para las franjas horarias de 7:00 a 22:00 hs.
• Se implementó soporte completo para el switch "Ocultar Aulas Virtuales" (hide_virtual=1), filtros por piso y por turno.
• Se preservan los query params en todas las redirecciones de Express.

E. Dashboards Personalizados por Rol (frontend/views/dashboard.html y dashboard.js)

• Habilitación de paneles operativos específicos para Bedelía, Docente / Profesor, Alumno / Estudiante y Administrador, con selector dinámico en el banner superior.

---

3. Pruebas y Verificación

Se ejecutó la suite de verificación automatizada:

1. Catálogo de Aulas Virtuales (/classrooms/list_classrooms?view_mode=virtual):
   • Status: 200 OK.
   • Renderiza tarjetas virtual-room-card con enlaces a Google Meet y badges "Remoto ∞".
2. Cartelera del Día (/schedule/today_schedule):
   • Status: 200 OK.
   • Muestra timeline cronológico por horas con clases presenciales y virtuales.
   • Botón hide_virtual=1 filtra instantáneamente las aulas virtuales.
3. Calendario General (/schedule/calendar_data):
   • 643 eventos en calendario (388 virtuales identificados con #6366F1 y enlaces activos).
4. Vistas Principales:
   • 11/11 rutas pasaron con código 200 sin errores de plantilla ni excepciones de servidor.

---

4. Acople de schedule.view_reservation al BFF Node.js y Gestión de Comisiones

A. Vista Detallada de Reserva (schedule.view_reservation)

• Backend API (/api/v1/reservations/<id>):
  • Enriquecimiento del payload serializado para incluir objetos relacionales completos: classroom (código, edificio, piso, capacidad, descripción, modalidad virtual), commission (código, código compuesto, materia, cuatrimestre, año, cupos), user (docente, nombre, apellido, email), duration, effective_virtual_link y can_be_cancelled.
  • Incorporación de endpoints de acción directa POST /api/v1/reservations/<id>/confirm y POST /api/v1/reservations/<id>/cancel.
• Node.js BFF (frontend/src/routes/schedule.js):
  • Implementación de handleViewReservation con soporte para /view_reservation, /view_reservation/:id, /view/:id, y /reservation/:id/view.
  • Implementación de handleEditReservation (GET & POST), handleConfirmReservation y handleCancelReservation.
  • Actualización de plantillas (view.html, today.html, list.html, dashboard.html) para enlazar directamente las fichas pasando el ID de la reserva.

B. Creación de Comisiones y Asociación con Materias (/admin/commissions_list)

• Modal y Acción en Interfaz:
  • Incorporación de botón destacado + Nueva Comisión en el encabezado y en el estado vacío de la tabla.
  • Implementación de modal interactivo #modalAddCommission:
    • Selector obligatorio de Asignatura / Materia Asociada (subject_id), mostrando código, nombre y carrera.
    • Campos de código de comisión, cuatrimestre, año lectivo, turno, docente a cargo, cupo máximo y días/horarios.
    • Generación y configuración de enlace a aula virtual (Google Meet institucional).
  • Alerta de confirmación visual (?created=1) al registrar y vincular la comisión exitosamente.
• Backend API (POST /api/v1/admin/commissions):
  • Validación de existencia de la asignatura vinculada y resolución inteligente de duplicados (subject_id, code, semester, year).
  • Auto-generación de enlaces seguros de Google Meet en caso de no especificarse enlace personalizado.