Files
admin-edu-space/README.md
T

450 lines
34 KiB
Markdown

# 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)