# 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](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 ```text 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: ```text / ├── 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: ```text [ 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`): ```text [ 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: ```text [ 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) ```powershell 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) ```powershell 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](install.sh) en la raíz: ```bash # 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): ```powershell cd backend $env:PYTHONPATH="." .\venv\Scripts\pytest tests -v ``` Para ejecutar la auditoría automatizada de seguridad estática y dinámica: ```powershell .\security_audit.bat --no-pause ``` --- ## 📚 Documentación Técnica & Referencias * [Changelog Oficial Completo del Proyecto](CHANGELOG.md) * [Principios de Desarrollo y Constitución del Proyecto](docs/constitution.md) * [Directivas para Agentes de IA y Arquitectura del Sistema](AGENTS.md) * [Especificaciones de Desarrollo Guiado (SDD 001 a 013)](specs/) * [Guía de Replicación Moodle Producción a Local](.agents/skills/moodle-replicator/SKILL.md) * [Procedimiento de Despliegue Continuo en Producción](.agents/skills/deploy/SKILL.md)