Panel de Administración Edu-Space (UniCABA)

Plataforma web integral de gestión de espacios áulicos, orquestación académica, control de accesos físicos, seguimiento pedagógico y asistencia inteligente para la Universidad de la Ciudad de Buenos Aires (UniCABA). Diseñada para reemplazar el uso de planillas Excel en Bedelía, sincronizar calendarios en tiempo real, validar identidades mediante credenciales digitales y hardware serial, y conectarse fluidamente con Moodle 4.1, Google Workspace y servidores de Inteligencia Artificial (LLMs).

El proyecto se basa en una arquitectura desacoplada (Backend Core REST API + Frontend BFF) en formato monorepo de alto rendimiento.

Versión Actual: 3.8.56 (Consolidada — FastAPI ASGI Pura, Control de Acceso QR / DNI, Multi-Serial COM, Asistente RAG UdeCi, Servidor MCP y Beneficios)
Institución: Universidad de la Ciudad de Buenos Aires (UniCABA)
Entorno de Producción: https://eduspace.oemspot.com.ar (Servidor LXC Proxmox 10.0.0.217)
Suite de Pruebas Automatizadas: 131/131 pruebas superadas (100% passed en pytest)


🗺️ Estado del Roadmap & Fases del Sistema

Fase 0: Desacople y Arquitectura Base                  [████████████████████] 100% (Completado)
Fase 1: Paridad Legacy y Estabilización                [████████████████████] 100% (Completado)
Fase 2: Co-docencia y Matriz de Conflictos Integral    [████████████████████] 100% (Completado)
Fase 3: Hitos Evaluativos, Gradebook y Actas           [████████████████████] 100% (Completado)
Fase 4: UI/UX Drag & Drop e Impersonación Segura       [████████████████████] 100% (Completado)
Fase 5: Integración Auth (Google/Moodle/Local/Emerg.)  [████████████████████] 100% (Completado)
Fase 5.1: Bedelía UX, Circuito 9 Pasos y Reset Seguro  [████████████████████] 100% (Completado)
Fase 6: Despliegue Producción Proxmox LXC (Nginx/SSL)  [████████████████████] 100% (Completado v3.5.0)
Fase 7: Asistente IA UdeCi, RAG Embebido y MCP Server  [████████████████████] 100% (Completado v3.8.25-28)
Módulo: Recepción, Multi-Serial COM y DNI Renaper      [████████████████████] 100% (Completado v3.8.50-56)
Módulo: Credencial Digital QR Anti-Captura & Perfil    [████████████████████] 100% (Completado v3.8.45-54)
Módulo: Convenios y Beneficios Institucionales         [████████████████████] 100% (Completado v3.8.39-44)

🏛️ 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 / PB) hasta el 4.° Piso.
  • Campus Virtual: Espacio áulico digital integrado (Google Meet / Microsoft Teams / Moodle) configurado con capacidad ilimitada (\infty) y sin restricciones de colisión física.

🏗️ Arquitectura del Proyecto (Monorepo Desacoplado)

El repositorio implementa un patrón desacoplado en 4 capas estrictas compuesto por la Core REST API (FastAPI ASGI), la capa de mediación y vistas BFF (Node.js / Express), herramientas unificadas de despliegue, scripts de replicación y pipelines de integración continua:

/
├── backend/                       # Capa Core API (Python 3.12+ / FastAPI ASGI / SQLAlchemy 2.0)
│   ├── main.py                   # Inicializador FastAPI ASGI, docs OpenAPI (/docs, /redoc), CORS
│   ├── database.py               # Motor relacional SQLAlchemy 2.0 (SessionLocal, get_db)
│   ├── routers/                  # Endpoints REST modulares por dominio (/api/v1/)
│   │   ├── auth.py               # Autenticación JWT, Google OAuth, Moodle delegado y perfil
│   │   ├── version.py            # Endpoints públicos /version y /health
│   │   ├── classrooms.py         # ABM y catálogo de aulas físicas y virtuales
│   │   ├── buildings.py          # Gestión de sedes, edificios y pisos dinámicos
│   │   ├── reservations.py       # Asignación de espacios, cartelera y validación Drag & Drop
│   │   ├── academic.py           # Carreras, asignaturas multi-carrera y comisiones
│   │   ├── admin.py              # Gestión institucional, usuarios, roles RBAC y auditoría
│   │   ├── students.py           # Inscripciones y consulta académica del alumno
│   │   ├── dashboard.py          # Agregaciones, percentiles y sincronización Sheets
│   │   ├── optimizer.py          # Algoritmo genético predictivo de optimización áulica
│   │   ├── ai_chat.py            # Endpoints del asistente UdeCi, inferencia y contexto en vivo
│   │   ├── mcp.py                # Servidor Model Context Protocol institucional
│   │   ├── benefits.py           # Catálogo y ABM de convenios y beneficios
│   │   └── reception.py          # Consola de recepción, escaneo QR y validación de DNI
│   ├── schemas/                  # DTOs y validación de contratos (Pydantic v2 BaseModel)
│   ├── app/                      # Lógica de dominio y persistencia
│   │   ├── models/               # Modelos ORM puros SQLAlchemy 2.0 (User, Role, Reservation, etc.)
│   │   └── services/             # Servicios de dominio especializados:
│   │       ├── argentine_dni_parser.py   # Parser universal de DNI (Renaper 2026/2012/2009/MiArg)
│   │       ├── qr_security_service.py    # Generación y validación de QR dinámico anti-captura
│   │       ├── live_context_service.py   # Inyección de contexto real de BD en prompts IA
│   │       ├── rag_service.py            # Recuperación semántica sobre normativas de UniCABA
│   │       ├── prompt_security.py        # Blindaje anti-jailbreak e inyecciones de prompt
│   │       ├── guide_service.py          # Asistencia interactiva guiada (Spotlights en UI)
│   │       ├── sheets_importer.py        # Importador multi-carrera y por rango de Google Sheets
│   │       ├── moodle_client.py          # Cliente HTTP REST para Moodle 4.1 Web Services
│   │       ├── moodle_queue_service.py   # Cola asíncrona resiliente y Dead Letter Queue (DLQ)
│   │       ├── email_service.py          # Notificaciones SMTP con credenciales cifradas (Fernet)
│   │       ├── gradebook_service.py      # Matriz de calificaciones y actas inmutables
│   │       ├── optimizer_service.py      # Optimizador heurístico basado en algoritmo genético
│   │       ├── weather_service.py        # Widget meteorológico del campus en CABA
│   │       └── audit_service.py          # Trazabilidad y registro inmutable de auditoría
│   ├── tests/                    # Suite de 131 pruebas automatizadas unitarias y de integración
│   ├── init_db.py                # Inicializador idempotente de esquema, roles RBAC y semillas
│   ├── classrooms_db.sql         # Snapshot integral de base de datos para despliegue
│   └── requirements.txt          # Dependencias auditadas (FastAPI, Uvicorn, SQLAlchemy 2.0, Pydantic)
│
├── frontend/                      # Backend-For-Frontend BFF (Node.js 20 LTS / Express 5)
│   ├── src/                      # Capa servidora de mediación web
│   │   ├── app.js                # Servidor Express, Helmet, rate-limit, cookies HttpOnly
│   │   ├── middlewares/          # JWT injection, sesión HttpOnly, RBAC y control de acceso
│   │   └── routes/               # Enrutamiento web (auth, schedule, classrooms, admin, reception)
│   ├── views/                    # Plantillas dinámicas en Nunjucks (.html)
│   │   ├── admin/                # Paneles de gestión institucional, auditoría e importador
│   │   ├── classrooms/           # Catálogo de aulas físicas y virtuales
│   │   ├── schedule/             # Cronograma de comisiones, reservas, cartelera y calendario
│   │   ├── dashboard/            # Dashboards modularizados por rol (admin, bedelia, prof, alum)
│   │   ├── reception/            # Consola de recepción y escaneo de credenciales
│   │   ├── credential/           # Carnet universitario digital completo y modal interactivo
│   │   ├── benefits/             # Portal de convenios y beneficios institucionales
│   │   └── partials/             # Asistente UdeCi, spotlights, navegación y modales globales
│   ├── public/                   # Assets estáticos (Bootstrap 5, Vanilla CSS, JS cliente)
│   │   ├── js/serial-scanner.js  # Módulo Web Serial API para hasta 4 lectores COM concurrentes
│   │   ├── js/qrcode.min.js      # Generador local autónomo de códigos QR
│   │   └── css/                  # Temas Claro / Oscuro de alto contraste (WCAG AA)
│   └── package.json              # Dependencias y manifiesto de Node.js
│
├── specs/                        # Especificaciones formales SDD (Specs 001 a 013 en EARS)
├── scripts/                      # Automatizaciones (moodle_replicator.py, importador RBAC)
├── install.sh                    # Instalador desatendido unificado para Linux / Proxmox LXC
├── security_audit.bat            # Suite automatizada de auditoría de seguridad (SAST, SCA, DAST)
├── AGENTS.md                     # Directivas de ingeniería de software, arquitectura y límites
├── docs/constitution.md          # Principios de desarrollo de software innegociables
└── README.md                     # Documentación general y manual técnico del sistema

⚡ Backend Core API (Python 3.12+ / FastAPI / SQLAlchemy 2.0)

  • 100% Nativo ASGI puro ejecutado con Uvicorn, con arquitectura desacoplada en 4 capas eliminando cualquier rastro de frameworks monolíticos legacy.
  • Expone contratos RESTful bajo /api/v1/ retornando exclusivamente JSON.
  • Validación estricta de payloads con Pydantic v2 (BaseModel, Field) respondiendo automáticamente con códigos 422 Unprocessable Entity detallando campos exactos.
  • Documentación interactiva autogenerada en vivo en /docs (Swagger UI), /redoc y contratos OpenAPI v3 en /openapi.json.
  • Persistencia optimizada con SQLAlchemy 2.0 sobre PostgreSQL 15 (en producción) y SQLite (en suites de pruebas).
  • Autenticación mediante tokens PyJWT (HS256) stateless con Access Tokens, Refresh Tokens y tokens dinámicos anti-captura.
  • Cifrado simétrico de datos sensibles en reposo mediante Fernet (cryptography).
  • Inferencia asíncrona no bloqueante hacia servidores de IA locales o remotos empleando httpx.AsyncClient con timeouts generosos (600 segundos).

🟢 Frontend BFF (Node.js 20+ LTS / Express 5)

  • Servidor de mediación Backend-For-Frontend que renderiza interfaces del lado del servidor mediante Nunjucks.
  • Gestiona sesiones seguras almacenando el JWT en cookies HttpOnly, SameSite=Lax y Secure en producción.
  • Cliente Axios centralizado con interceptores que inyectan de forma transparente el Bearer token en cada solicitud a la FastAPI.
  • Blindaje perimetral con Helmet (cabeceras de seguridad HTTP) y express-rate-limit para protección contra ataques de fuerza bruta.
  • Soporte para hardware local en navegadores Chromium mediante la Web Serial API (navigator.serial) para control de accesos sin depender del foco del cursor.
  • Interfaz adaptativa diseñada para pantallas estándar argentinas (720p, 1366x768, 1080p y móviles) con soporte integral de Modo Oscuro / Alto Contraste (WCAG AA) y componentes reactivos en Chart.js y FullCalendar.

🤖 Asistente Virtual Inteligente "UdeCi" & RAG Embebido (Specs 009 & 010)

La plataforma cuenta con un copiloto de inteligencia artificial institucional integrado denominado UdeCi (Universidad de la Ciudad), accesible desde cualquier punto de la aplicación:

[ Usuario / Pregunta ] ──► [ Prompt Security & Anti-Jailbreak ] ──► [ Live Context DB (PostgreSQL) ]
                                                                             │
[ Inferencia Asíncrona (httpx 600s) ] ◄── [ RAG Vectorial (Normativas) ] ◄────┘
  (Llama.cpp / Ollama / Qwen)
        │
        ▼
[ Respuesta Estructurada ] ──► [ UI Móvil (Bottom-Sheet) / Desktop Dock ] ──► [ Acciones & Quick Chips ]

1. Inferencia Asíncrona no Bloqueante con Modelos de IA Locales

  • Integración nativa con servidores de inferencia OpenAI-compatibles (tales como llama.cpp, Ollama o vLLM) ejecutando modelos como Qwen 2.5 / 3 Coder 30B.
  • Peticiones ejecutadas de forma 100% asíncrona (async def con httpx.AsyncClient) con timeout de 600 segundos para permitir la carga fluida de tensores en VRAM e inferencias de prompts extensos sin degradar la concurrencia del servidor.
  • Pestaña dedicada en la Configuración Global (/admin/settings -> Asistente IA) para parametrizar URL del servidor, modelo, temperatura, max tokens y botón para verificar conexión en caliente.

2. Arquitectura RAG Embebida (KnowledgeChunk)

  • Almacena normativas institucionales, estatutos de UniCABA, reglamentos de correlatividades, calendarios académicos, regímenes de regularidad y contactos oficiales en la tabla relacional knowledge_chunks.
  • Motor semántico con ranking de relevancia basado en frecuencia inversa de documentos (TF-IDF) y filtrado estricto por roles (ADMIN, BEDELIA, DOCENTE, ALUMNO, PUBLIC).
  • Respuestas precisas sobre dónde recuperar contraseñas de Moodle (https://campus.udelaciudad.edu.ar/login/forgot_password.php), cómo ingresar con Google Workspace o cómo tramitar equivalencias.

3. Inyección de Contexto en Vivo Profundo (LiveContextService)

  • Consulta la base de datos PostgreSQL en tiempo real según la identidad y rol del usuario autenticado:
    • Alumnos: Aula física y piso asignado para el día de hoy, materias en las que está inscripto, docentes de su comisión, porcentaje de asistencia y calificaciones con estricta privacidad (un alumno jamás puede consultar notas de otros pares).
    • Docentes: Comisiones asignadas a su cargo, aulas donde dicta clase hoy, cantidad de alumnos inscriptos y estado de cierre de actas de su cátedra.
    • Bedelía / Admin: Aulas libres hoy por piso, comisiones pendientes de asignación de aula física y porcentaje global de ocupación de la sede.

4. Seguridad de Prompts y Blindaje Perimetral (prompt_security.py)

  • Filtro declarativo contra técnicas de Jailbreak, inyecciones de prompt (Prompt Injection), bypass de roles y extracción de directivas de sistema.
  • Neutralización automática de tokens especiales de inferencia (<|im_start|>, <|system|>, etc.) y prohibición explícita de revelar credenciales de base de datos o secretos de API.

5. Experiencia de Usuario Adaptativa y Ergonómica

  • Móviles: Ventana desplegable estilo bottom-sheet (inspirada en la UX de Mercado Libre) con acople automático al teclado virtual en pantalla, backdrop con aislamiento de scroll y botón de repliegue rápido.
  • Escritorio: Widget flotante dockeable con selector de tamaño, sugerencias rápidas contextuales (Quick Chips) y renderizado de texto enriquecido en Markdown.

🔌 Servidor MCP Institucional & Asistencia Guiada (Spec 011)

Edu-Space implementa el estándar Model Context Protocol (MCP) bajo /api/v1/mcp:

  • Herramientas Expuestas para Agentes de IA:
    • get_today_classes: Consulta del cronograma áulico del día por sede.
    • get_classroom_info: Inspección de aforo, piso, equipamiento y disponibilidad de aulas.
    • search_subjects: Búsqueda de materias por carrera o código.
    • guide_navigation: Disparador de tutoriales guiados en la plataforma.
  • Reflector Didáctico Interactivo (Spotlight UI): Motor en cliente (GuideService) capaz de resaltar elementos del DOM paso a paso con recuadros iluminados, tooltips explicativos y avance guiado para capacitar a nuevos operadores de Bedelía o docentes.

🪪 Consola de Recepción, Multi-Serial COM y Reconocimiento de DNI (Spec 013)

La plataforma incorpora una consola operativa integral de control de accesos físicos en tiempo real para personal de Recepción y Seguridad (/reception/scanner):

[ Lector COM 1 (Molinete) ] ──┐
[ Lector COM 2 (Paso Princ) ] ─┼──► [ MultiSerialScanner (Web Serial API) ] ──► [ Argentine DNI Parser ]
[ Lector COM 3 (Bedelía) ] ───┤                                                         │
[ Lector COM 4 (Auxiliar) ] ──┘                                                         ▼
                                                                             [ QRSecurityService ]
                                                                                        │
[ Feedback Audio (Web Audio) ] ◄── [ Cronograma de Hoy (Aula/Piso) ] ◄──────────────────┘

1. Soporte Multi-Lector por Puerto Serie COM (Web Serial API)

  • Hasta 4 Lectores Seriales Concurrentes: Control simultáneo de ranuras físicas (Lector 1 — Paso Principal, Lector 2 — Molinete, Lector 3 — Mesa Bedelía, Lector 4 — Auxiliar).
  • Reconexión Automática Plug-and-Play: Detección de eventos nativos del sistema operativo en Windows (navigator.serial.addEventListener('connect' / 'disconnect')), re-enlazando lectores USB desenchufados sin recargar la página.
  • Buffer de Seguridad de Chunks (380 ms): Permite procesar de forma íntegra códigos densos de más de 400 caracteres transmitidos por escáneres ópticos.
  • Panel Colapsable Ergonómico: Bloque de puertos COM contraído por defecto con indicador resumen (0 / 4 Activos) para despejar el puesto operativo.

2. Reconocimiento Universal de DNI Argentino (Renaper & Mi Argentina)

  • Algoritmo de Extracción Multiformato (argentine_dni_parser.py):
    • Renaper Formato 2026: Códigos QR de alta densidad con datos patronímicos seguidos del JWT oficial de Renaper (00749743816"TELLO"CARLOS FACUNDO"34247025"G"09-02-89"23-04-26"eyJ...).
    • Renaper Formato 2012: Códigos de barras PDF417 de DNIs tarjeta vigentes.
    • Renaper Formato 2009: DNI libreta celeste o tarjeta inicial con prefijos alfabéticos F / M (Libreta Cívica / Enrolamiento) o comillas iniciales.
    • App Mi Argentina: Códigos QR con identificadores numéricos de género y documento.
    • Ingreso Directo: Tipeado manual o pistola USB HID sobre documento con o sin puntos (34.247.025, 34247025, DNI: 34247025).
  • Normalización de Teclado en Español: Corrige la traducción errónea de : a Ñ en lectores configurados con mapa de teclado US en Windows (UNICABAÑUSRÑ144 ➔ UNICABA:USR:144), preservando intactos los nombres y apellidos que contengan Ñ (ej. Peña, Núñez, Piñero).
  • Auto-vinculación Asistida: Si un DNI físico es escaneado por primera vez y el usuario no tenía el número cargado en la base de datos, el sistema asocia de forma permanente el documento mediante coincidencia nominal de nombre y apellido.

3. Validación y Cronograma Áulico Instantáneo

  • Al escanear una credencial o DNI, el sistema muestra en pantalla:
    • Datos personales, rol institucional y fotografía/iniciales.
    • Estado de matrícula (Activo / Regular).
    • Aula física exacta y piso donde cursa o dicta clase hoy (ej. Aula 204 — Piso 2, Edificio Central).
  • Señalización Cromática Tristado:
    • Verde Esmeralda (border-success): Alumno o docente con cursada presencial hoy en la sede.
    • Ámbar de Advertencia (border-warning): Alumno regular activo pero sin clases programadas para hoy.
    • Rojo Denegado (border-danger): Usuario inactivo, credencial vencida o persona no registrada en UniCABA.
  • Feedback Auditivo Sintetizado (Web Audio API):
    • Tono Armónico Ascendente (587Hz ➔ 880Hz): Acceso con aula y clase hoy.
    • Tono Suave Medio (440Hz ➔ 554Hz): Acceso válido sin clase hoy.
    • Tono Grave de Alerta (220Hz): Acceso denegado o error.
  • Bitácora Inmutable (access_logs_qr): Registro de cada ingreso con timestamp en hora local argentina (America/Argentina/Buenos_Aires).

💳 Credencial Digital Universitaria con QR Dinámico Anti-Captura (Spec 012)

Cada integrante de la comunidad de UniCABA dispone de una credencial digital infalsificable:

  • Auto-Rotación Dinámica Criptográfica (3 Segundos): El código QR se regenera automáticamente cada 3 segundos mediante tokens JWT firmados con identificador único (jti) y marca de tiempo (iat).
  • Ventana Estricta Anti-Screenshot: Período de gracia ultra-corto (6 segundos) configurado en SystemSetting. Cualquier fotografía previa o captura de pantalla enviada por mensajería expira a los pocos segundos y es rechazada por la consola de recepción (jwt.ExpiredSignatureError).
  • Puntos de Acceso:
    • Carnet Universitario Completo (/credential/my-card): Ficha institucional imprimible con datos de carrera, DNI, foto, QR en vivo y condiciones de regularidad.
    • Modal Global Rápido (#userQrCredentialModal): Botón con icono bi-qr-code-scan en la barra lateral y cabecera móvil que despliega el código QR con barra de progreso interactiva sin salir de la página activa.
    • Perfil de Usuario (/auth/profile): Exhibición de credencial y vías habilitadas de acceso.

🎁 Módulo de Convenios y Beneficios Institucionales (Spec 012)

Portal de descuentos y acuerdos corporativos para la comunidad académica (/benefits):

  • Catálogo Categorizado: Beneficios en gastronomía, librerías, tecnología, deportes y capacitaciones.
  • ABM Administrativo: Gestión de beneficios con título, descripción, porcentaje de descuento, fechas de validez, cupón promocional e imagen de marca.
  • Control de Acceso RBAC: Módulo benefits administrable con permisos segmentados (none, read, read_write) en la matriz de roles institucional.

🏛️ Circuito Operativo Secuencial de Bedelía (9 Pasos)

Para garantizar la integridad referencial y erradicar las planillas Excel, la administración áulica sigue un flujo estandarizado:

[ 1. Sede / Edificio ] ──► [ 2. Aulas (Físicas / Virtuales) ] ──► [ 3. Ciclo Lectivo ]
                                                                           │
[ 6. Comisiones ] ◄────── [ 5. Asignaturas (Multi-carrera) ] ◄── [ 4. Carreras ]
       │
       ▼
[ 7. Profesores ] ───────► [ 8. Alumnos / Matrícula ] ────────► [ 9. Reserva de Espacio ]

1. Asignaturas Compartidas entre Múltiples Carreras

  • Implementación de la tabla asociativa subject_careers (relación Many-to-Many), permitiendo que una materia (ej. IoT, Seguridad de la Información, Sistemas Operativos) pertenezca simultáneamente a múltiples planes de estudio preservando career_id principal por compatibilidad.
  • Comisiones y grillas exponen todas las carreras vinculadas para facilitar búsquedas y filtros.

2. Matriz Integral de Conflictos (HTTP 409)

  • Solapamiento Físico de Aula: Impide asignar dos clases presenciales en la misma aula y franja horaria.
  • Aforo de Capacidad Máxima: Alerta y bloquea si el cupo de alumnos inscriptos supera la capacidad de bancos del aula física.
  • Solapamiento Docente: Controla la disponibilidad horaria del profesor, autorizando la superposición únicamente si la cátedra cuenta con un co-docente registrado disponible (Excepción por Co-docencia).
  • Restricción Diaria del Alumno: Un estudiante no puede cursar dos asignaturas regulares el mismo día, salvo en cursos cortos/talleres (is_short_course) o con autorización expresa de Bedelía (allow_same_day_exception).

3. Cartelera Operativa & Exportación A4 / Excel

  • Cartelera del Día (/schedule/today_schedule): Franjas horarias agrupadas cronológicamente (grouped_slots, ej. 08:00 - 11:00 hs), turnos, aulas físicas, docentes y enlaces directos a Google Meet / Teams.
  • Filtros Temporales Explícitos: Switcher para alternar entre "Día (Hoy)", "Mañana", "Esta Semana" y "Este Mes" con badges de fecha en español.
  • Exportación Excel / CSV: Descarga directa con codificación UTF-8 BOM (\uFEFF) y delimitadores ; para apertura perfecta en Excel.
  • Impresión A4 Institucional: Estilos dedicados @media print que formatean la cartelera en hoja limpia con membrete oficial de UniCABA.

4. Grilla Semanal Interactiva (Drag & Drop)

  • Calendario semanal interactivo (FullCalendar) en /schedule/calendar con panel lateral de comisiones sin aula.
  • Arrastre de eventos con validación asíncrona previa (POST /api/v1/reservations/drag-update); ante colisión horaria se revierte automáticamente el evento (info.revert()) y se notifica al usuario con un Toast descriptivo.

5. Libro de Calificaciones (Gradebook) & Cierre de Actas

  • Matriz bidimensional interactiva de calificaciones por comisión (/schedule/gradebook/:id) con autoguardado asíncrono debounced (500 ms).
  • Cálculo dinámico de promedios ponderados y condiciones (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.

6. Modo Impersonación del Superadmin ("Login as")

  • Permite a un administrador auditar el sistema adoptando exactamente la perspectiva y permisos de cualquier docente o estudiante.
  • Activación en 1 clic (bi-incognito) desde el catálogo de usuarios (/admin/users_list), con banner ámbar permanente de advertencia visual y trazabilidad estricta en auditoría (IMPERSONATE_START / IMPERSONATE_END).

🧹 Importador Dinámico de Google Sheets & Purga Selectiva

El importador oficial de Google Sheets (sheets_importer.py) permite la ingesta masiva inicial y sincronización continua:

  • Inspección en Vivo del Sheet Online: Descarga y analiza las 6 hojas semanales (Lunes a Sábado), descubriendo dinámicamente carreras y materias.
  • Grilla Interactiva de Previsualización: Muestra las filas detectadas con buscador en vivo, paginación fluida y datepicker editable por fila para corregir fechas de cursada antes de sincronizar.
  • Selección Granular de Entidades: Toggles independientes para decidir si importar Reservas, Aulas físicas/virtuales, Comisiones, Asignaturas o Carreras.
  • Alcance Temporal Flexible: Soporte de rangos personalizados de fechas (semanas del cuatrimestre) o fecha puntual única.
  • Tolerancia de Carga Masiva: Servidor Express configurado con límite de payload de 50 MB ({ limit: '50mb' }) para procesar matrices completas de sincronización sin errores de PayloadTooLargeError.
  • Purga Segura y Selectiva: Herramienta para vaciar ordenadamente entidades académicas en orden topológico inverso de claves foráneas, preservando intactos a los usuarios, contraseñas y roles.

🔄 Integraciones del Sistema

1. Google Workspace OAuth 2.0

  • Autenticación institucional restringida al dominio @unicaba.edu.ar.
  • Asociación automática de perfil y generación de enlaces de Google Meet para comisiones virtuales.

2. Moodle 4.1 REST API & Replicador Institucional

  • Conexión con los Web Services oficiales de Moodle (core_webservice_*, enrol_*, core_user_*).
  • Autenticación delegada permitiendo a los alumnos ingresar a Edu-Space con sus credenciales de Moodle.
  • Cola de sincronización asíncrona resiliente (MoodleSyncTask) con reintentos exponenciales y Dead Letter Queue (DLQ).
  • Capa de caché híbrida (CacheService en Redis o memoria) para lecturas de alto rendimiento.
  • Replicador institucional (scripts/moodle_replicator.py & .agents/skills/moodle-replicator) para sincronizar masivamente nóminas de participantes, cursos y categorías entre entornos.

3. Servicio de Correo Electrónico SMTP Dinámico (EmailService)

  • Envío de notificaciones y confirmaciones con credenciales de servidor SMTP configuradas en base de datos y cifradas en reposo con Fernet.

4. Clima del Campus en Vivo (WeatherService)

  • Consulta meteorológica en tiempo real para la Ciudad de Buenos Aires desplegada en el pie de la barra lateral.

5. Acceso de Contingencia para Administradores (/adm/login, Spec 006)

  • Pasarela de autenticación de emergencia aislada que permite a los administradores ingresar mediante credenciales maestras locales ante caídas de proveedores de identidad externos (Google o Moodle).

🔐 Seguridad, RBAC y Auditoría Institucional

  • Matriz de Permisos RBAC en 12 Módulos: Control segmentado (none, read, read_write) sobre classrooms, reservations, schedule, academic, users, roles, reports, optimizer, system, settings, benefits y reception.
  • Roles del Sistema: Admin, Bedelia, Docente, Alumno y Recepcion.
  • Registro de Auditoría Inmutable (AuditLog): Monitoreo continuo de eventos críticos (inicios y fallos de sesión, altas/bajas de aulas y reservas, ejecuciones del optimizador genético e impersonaciones).
  • Gestión Transparente de Incidentes: Pantalla de diagnóstico técnico estructurada con ticket único (INC-YYYYMMDD-XXXX), traza de error colapsable y botón para copiar informe al equipo de soporte IT.

🎯 Dashboards Personalizados por Rol

  • Administrador (/dashboard?role=admin): Cockpit institucional con métricas globales, auditoría de seguridad RBAC, percentiles de ocupación y acceso a la configuración del Asistente IA y credenciales QR.
  • Bedelía (/dashboard?role=bedelia): Control operativo en vivo, balance de aulas presenciales asignadas y libres, cartelera del día con accesos de impresión en 1 clic y bandeja de aprobación de reservas.
  • Docente (/dashboard?role=docente): Clases del día, enlaces a videoconferencias, Libro de Calificaciones y nómina de alumnos.
  • Alumno (/dashboard?role=alumno): Brújula de cursada "¿Dónde curso hoy?" con aula física, piso o enlace Meet, libreta de calificaciones y acceso instantáneo a su carnet universitario QR.
  • Recepción (/reception/scanner): Consola de control de acceso físico con lectores seriales COM, validación de DNI argentino y verificación instantánea de aula asignada para el día.

🚀 Instalación y Puesta en Marcha Local

Requisitos Previos

  • Node.js: v20.x LTS o superior
  • Python: 3.12+ (compatible con Python 3.14)
  • Base de Datos: PostgreSQL 15+ (recomendado) o SQLite (desarrollo rápido)

1. Iniciar el Backend (FastAPI ASGI Core API)

cd backend
python -m venv venv

# En Windows:
.\venv\Scripts\activate
# En Linux / macOS:
# source venv/bin/activate

pip install -r requirements.txt

# Inicializar base de datos con roles y usuarios esenciales:
python init_db.py

# Levantar servidor ASGI Uvicorn en el puerto 5000 con recarga en caliente:
uvicorn main:app --host 0.0.0.0 --port 5000 --reload

API disponible en: http://localhost:5000
Documentación interactiva Swagger UI: http://localhost:5000/docs
Documentación interactiva ReDoc: http://localhost:5000/redoc

2. Iniciar el Frontend (Node.js / Express BFF)

cd frontend
npm install

# Iniciar servidor Express en el puerto 3000 con nodemon / recarga activa:
npm run dev

Aplicación web disponible en: http://localhost:3000


📦 Despliegue Automatizado en Producción (Linux / Proxmox LXC)

Para servidores institucionales Debian 12 / Ubuntu en Proxmox LXC (entorno productivo 10.0.0.217 / eduspace.oemspot.com.ar), el repositorio incluye el instalador desatendido install.sh en la raíz:

# Despliegue interactivo con menú de opciones:
sudo bash install.sh

# Despliegue desatendido preservando la base de datos PostgreSQL existente:
sudo bash install.sh --keep-db

# Despliegue desatendido con base de datos limpia (solo usuarios y roles iniciales):
sudo bash install.sh --empty-academic

# Despliegue recreando la base desde snapshot completo (DROP y restore classrooms_db.sql):
sudo bash install.sh --fresh-db

El script configura automáticamente:

  1. Virtualenv Python 3.12+ con Gunicorn/Uvicorn bajo el servicio admin-edu-space-backend.service (:5000).
  2. Runtime Node.js 20 LTS bajo el servicio admin-edu-space-frontend.service (:3000).
  3. Motor PostgreSQL local con credenciales seguras para classrooms_db.
  4. Servicio maestro unificado admin-edu-space.service gestionable vía systemctl {status|restart|stop} admin-edu-space.

🧪 Pruebas Automatizadas & Calidad de Código

Para ejecutar la suite completa de 131 pruebas unitarias y de integración (validando contratos FastAPI, DTOs Pydantic, algoritmos genéticos, RAG UdeCi, parsers de DNI, cola Moodle, RBAC y matriz de colisiones):

cd backend
$env:PYTHONPATH="."
.\venv\Scripts\pytest tests -v

Para ejecutar la auditoría automatizada de seguridad estática y dinámica:

.\security_audit.bat --no-pause

📚 Documentación Técnica & Referencias

S
Description
No description provided
Readme
21 MiB
Languages
HTML 53%
Python 33.3%
JavaScript 10.9%
Shell 1.4%
CSS 1.2%
Other 0.2%