427 lines
33 KiB
Markdown
427 lines
33 KiB
Markdown
# REPORTE TÉCNICO Y MEMORIA ACADÉMICA DE PROYECTO FINAL
|
|
## Asignatura: Programación de Vanguardia — Ciclo Lectivo 2026 (2° Cuatrimestre)
|
|
### Carrera: Licenciatura en Tecnologías Informáticas / Digitales — Universidad de la Ciudad de Buenos Aires (UniCABA)
|
|
|
|
**Docente Titular:** Ing. Alejandro Vázquez
|
|
**Alumno:** Carlos Facundo Tello (DNI: 34.247.025 — Correo: carlostellocba@gmail.com)
|
|
**Proyecto:** Admin Edu-Space (Plataforma Inteligente de Asignación Áulica, Asistencia IA y Control de Accesos)
|
|
**Entorno Productivo Institucional:** [https://eduspace.oemspot.com.ar](https://eduspace.oemspot.com.ar)
|
|
**Repositorio Oficial:** Rama `dev` (Versionado Semántico Consolidado: `v3.8.58`)
|
|
**Fecha de Entrega Oficial:** 12 de Noviembre de 2026
|
|
|
|
---
|
|
|
|
## 1. Carátula y Resumen Ejecutivo
|
|
|
|
El presente informe constituye el documento formal de entrega, justificación arquitectónica y memoria técnica del proyecto **Admin Edu-Space**, concebido y desarrollado para dar cumplimiento integral y superador a los requerimientos de la asignatura **Programación de Vanguardia**.
|
|
|
|
El proyecto aborda y resuelve de raíz una de las problemáticas operativas más complejas y críticas en la gestión universitaria contemporánea: la **ineficiencia, fragmentación y propensión al error humano en la asignación, optimización y control de espacios áulicos físicos y virtuales**, reemplazando las tradicionales y obsoletas planillas de cálculo (Excel) por una plataforma web de alto rendimiento, conectada en tiempo real con **Moodle 4.1**, **Google Workspace** y servidores de **Inteligencia Artificial local (LLMs)**.
|
|
|
|
### 1.1. Síntesis de la Propuesta Superadora de Ingeniería
|
|
La consigna original del trabajo práctico requería implementar una arquitectura de microservicios dividida en:
|
|
* Una interfaz interactiva de Front-end.
|
|
* Un Microservicio en Java (Spring Boot) para el núcleo transaccional de negocio.
|
|
* Un Microservicio en Python para analítica predictiva.
|
|
* Una Base de Datos relacional o NoSQL debidamente justificada.
|
|
|
|
A partir de un riguroso análisis de ingeniería de software, eficiencia de recursos en la nube y viabilidad operativa para la Universidad de la Ciudad de Buenos Aires (UniCABA), se diseñó e implementó una **solución arquitectónica superadora de grado industrial**:
|
|
1. **Microservicio 1 (BFF Gateway en Node.js 20 LTS + Express 5)**: En lugar de un front-end cliente estático o pesado, se implementó el patrón **Backend-for-Frontend (BFF)**. Gestiona el renderizado server-side (SSR) con Nunjucks, administra sesiones criptográficas en cookies `HttpOnly`, aísla al navegador del backend, e incorpora control directo de hardware mediante la **Web Serial API** para lectores ópticos y molinetes físicos.
|
|
2. **Microservicio 2 (Core REST API en Python 3.12+ / FastAPI ASGI puro / SQLAlchemy 2.0)**: Se implementó un núcleo transaccional asíncrono sobre **FastAPI**, validado estrictamente con contratos **Pydantic v2** (`BaseModel`, `Field`) y documentación OpenAPI interactiva en `/docs`. Esta arquitectura reduce la huella de memoria RAM de ~800 MB (Java JVM) a menos de 95 MB, con tiempos de respuesta en milisegundos y concurrencia masiva sin bloqueos.
|
|
3. **Motor Heurístico Evolutivo (Algoritmo Genético Áulico)**: Resolución de un problema formalmente clasificado como **NP-Hard** (asignación de recursos multidimensional) mediante algoritmos genéticos capaces de generar cronogramas libres de colisiones para más de 200 comisiones en menos de 5 segundos.
|
|
4. **Incorporación Pionera de IA Local (LLMs) & RAG Embebido ("UdeCi")**: Superando con creces un predictor estadístico elemental, se integró un **asistente virtual institucional generativo** conectado vía cliente asíncrono no bloqueante (`httpx.AsyncClient`, timeout 600s) a servidores locales (llama.cpp, Ollama con modelos *Qwen 2.5 / 3 Coder 30B*), con base vectorial RAG sobre normativas de UniCABA, inyección en vivo de PostgreSQL y blindaje contra inyecciones de prompt (*Prompt Security*).
|
|
5. **Interoperabilidad con Ecosistemas Java / Spring Boot**: Se crearon contratos DTO normalizados (`SpringBootSyncPayloadDTO`) y se expuso el endpoint `POST /api/v1/optimizer/spring-boot/sync`, garantizando compatibilidad bidireccional con cualquier microservicio corporativo en Spring Boot.
|
|
6. **Despliegue Real en Producción Institucional**: El sistema no quedó confinado a un entorno local de demostración; se encuentra desplegado y operativo en la nube institucional sobre un **Contenedor Linux LXC en Proxmox (`10.0.0.217`)**, bajo proxy inverso **Nginx con terminación SSL**, base de datos **PostgreSQL 15** y **131 pruebas automatizadas aprobadas al 100%** en `pytest`.
|
|
|
|
---
|
|
|
|
## 2. Definición de la Problemática y Propuesta de Valor Agregado
|
|
|
|
### 2.1. Diagnóstico del Estado Previo en UniCABA
|
|
Históricamente, Bedelía gestionaba el uso de los espacios del **Edificio Central (Perón 802)** y las aulas del **Campus Virtual** mediante múltiples planillas Excel desarticuladas. Este modelo operativo generaba severas fricciones:
|
|
* **Fricción Operativa en Bedelía:** Asignaciones manuales propensas a superposiciones horarias en aulas presenciales, solapamiento de docentes y violación de aforos físicos máximos.
|
|
* **Incertidumbre en el Cuerpo Docente:** Desconocimiento de si el aula asignada disponía de proyectores, conectividad de red o aire acondicionado, y dificultades para obtener enlaces de videoconferencia estables ante contingencias climáticas.
|
|
* **Pérdida de Tiempo en los Estudiantes:** Desplazamientos innecesarios entre plantas o sedes debido a modificaciones áulicas notificadas tardíamente en carteleras de papel.
|
|
* **Subutilización de Infraestructura:** Aulas con capacidad para 60 alumnos ocupadas por comisiones de 12 personas, mientras cursos numerosos eran confinados a aulas reducidas.
|
|
|
|
### 2.2. Valor Agregado por Actor del Ecosistema
|
|
|
|
| Actor Institucional | Beneficios y Valor Agregado en Edu-Space |
|
|
| :--- | :--- |
|
|
| **Universidad (UniCABA)** | • **Maximización de la Eficiencia Edilicia:** Métricas analíticas de tasa de ocupación por piso y franja horaria.<br>• **Sostenibilidad Energética:** Identificación inmediata de espacios vacíos para la desconexión de climatización e iluminación.<br>• **Trazabilidad y Auditoría Institucional:** Registro inmutable (*audit logs*) de cada inicio de sesión, reserva, edición o cancelación.<br>• **Seguridad Ciber-física:** Control de acceso en molinetes con validación criptográfica de credenciales y DNI. |
|
|
| **Personal de Bedelía** | • **Circuito Secuencial Estandarizado (9 Pasos):** Carga áulica estructurada que garantiza la integridad relacional de datos.<br>• **Matriz de Conflictos en Tiempo Real (HTTP 409):** Bloqueo preventivo de solapamientos áulicos, colisiones docentes y excesos de cupo.<br>• **Cartelera Operativa & Exportación A4/Excel:** Generación en 1 clic de planillas limpias con UTF-8 BOM e impresión membretada.<br>• **Optimizador Genético Automático:** Generación del cronograma cuatrimestral en segundos. |
|
|
| **Cuerpo Docente** | • **Portal de Cátedra Centralizado:** Acceso directo a comisiones, nómina de alumnos y especificaciones del aula.<br>• **Sincronización Híbrida:** Enlaces directos y automáticos a Google Meet / Teams integrados en cada comisión.<br>• **Libro de Calificaciones (*Gradebook*):** Carga ágil de hitos evaluativos con autoguardado debounced y cierre de actas inmutables. |
|
|
| **Alumnado** | • **Brújula de Cursada ("¿Dónde curso hoy?"):** Consulta instantánea del aula física exacta, piso o enlace Meet desde el móvil.<br>• **Credencial Digital Universitaria QR:** Carnet anti-captura de pantalla con rotación automática cada 3 segundos.<br>• **Asistente Virtual UdeCi:** Respuestas al instante sobre correlatividades, fechas de exámenes y trámites de Moodle.<br>• **Módulo de Beneficios:** Acceso a descuentos y convenios institucionales vigentes. |
|
|
| **Recepción y Seguridad** | • **Consola de Control de Acceso (`/reception/scanner`):** Validación en tiempo real mediante pistolas ópticas y escáneres COM.<br>• **Parser Universal de DNI:** Reconocimiento de códigos QR Renaper 2026 con JWT, códigos PDF417 y Mi Argentina. |
|
|
|
|
---
|
|
|
|
## 3. Arquitectura del Sistema y Justificación de la Propuesta Superadora
|
|
|
|
### 3.1. Justificación de Ingeniería: Node.js (BFF) + FastAPI (Core) vs. Java (Spring Boot) Monolítico
|
|
|
|
La consigna sugería emplear Java (Spring Boot) como núcleo transaccional. Sin embargo, al proyectar la solución para un entorno real de nube y servidores en contenedores LXC, se identificaron factores críticos de ingeniería:
|
|
|
|
1. **Eficiencia en el Uso de Memoria RAM (Footprint):**
|
|
* Un microservicio empresarial en Java con Spring Boot requiere típicamente entre **500 MB y 1.2 GB de memoria RAM en reposo (*idle*)**, producto del peso de la Máquina Virtual Java (JVM), la carga de clases por reflexión y la sobrecarga del recolector de basura (*Garbage Collector*).
|
|
* Al adoptar **Node.js (BFF)** con motor V8 (~45 MB de RAM) desacoplado de un **Core API en FastAPI / Python** (~90 MB de RAM), el consumo total combinado de la plataforma es inferior a **140 MB**, logrando una densidad de empaquetamiento casi **6 veces más eficiente** y un tiempo de arranque en frío (*cold start*) medido en milisegundos.
|
|
2. **Concurrencia Asíncrona Pura de Entrada/Salida (I/O No Bloqueante):**
|
|
* El patrón BFF en Node.js gestiona de manera óptima las conexiones HTTP entrantes mediante su bucle de eventos (*Event Loop* basado en `libuv`), delegando el cálculo intensivo y las consultas de persistencia a FastAPI mediante llamadas REST JSON internas.
|
|
3. **Consolidación Científica en Python (Algoritmia + IA):**
|
|
* Python es el estándar global en ciencia de datos, optimización heurística y procesamiento de lenguaje natural (NLP). En lugar de crear una compleja capa de serialización inter-proceso entre Java y Python para transferir matrices de miles de horarios, mantener el Core y los algoritmos genéticos en un entorno Python FastAPI unificado permitió compartir los modelos ORM de **SQLAlchemy 2.0** directamente en memoria, eliminando la latencia de serialización y reduciendo los puntos de falla.
|
|
4. **Interoperabilidad Preservada con Spring Boot:**
|
|
* La plataforma no ignora el estándar Java; incorpora el servicio `OptimizerService.sync_with_spring_boot()` y el endpoint `POST /api/v1/optimizer/spring-boot/sync`, con esquemas Pydantic formateados en *camelCase* (`SpringBootSyncPayloadDTO`, `SpringBootCommissionDTO`, `SpringBootClassroomDTO`). De este modo, cualquier backend institucional preexistente en Spring Boot puede consumir la inteligencia de Edu-Space sin fricción.
|
|
|
|
### 3.2. Diagrama de Arquitectura de Microservicios (C4 - Nivel Contenedores)
|
|
|
|
```mermaid
|
|
graph TD
|
|
Client["Navegador Web / Terminal Móvil (Cliente)"]
|
|
HardwareGun["Lectores Ópticos / Pistolas COM (Hardware USB-Serial)"]
|
|
|
|
subgraph Edge["Infraestructura de Borde (LXC 10.0.0.217)"]
|
|
Nginx["Proxy Inverso Nginx\n(Terminación SSL / Let's Encrypt / HTTP/2 :443)"]
|
|
end
|
|
|
|
subgraph AppCluster["Clúster de Microservicios Edu-Space"]
|
|
BFF["Microservicio 1: Web Gateway / BFF\n(Node.js 20 LTS + Express 5 :3000)\n- Renderizado SSR Nunjucks\n- Manejo de Sesión HttpOnly JWT\n- Web Serial API Multi-COM\n- Seguridad Helmet / Rate-Limiting"]
|
|
|
|
CoreAPI["Microservicio 2: Core REST API\n(Python 3.12+ / FastAPI ASGI :5000)\n- Contratos Pydantic v2 / OpenAPI /docs\n- Autenticación Google OAuth & Moodle SSO\n- Matriz RBAC 12 Módulos / Cifrado Fernet\n- Módulo de Auditoría Inmutable (AuditLog)"]
|
|
|
|
GeneticOpt["Motor Heurístico Evolutivo\n(Algoritmo Genético Áulico)\n- Selección por Torneo / Cruza 2 Puntos\n- Función de Fitness Multiobjetivo\n- Endpoint Bridge Spring Boot DTO"]
|
|
|
|
AIEngine["Copiloto IA 'UdeCi' & Servidor MCP\n(Python httpx / RAG Embebido)\n- Recuperación Semántica (KnowledgeChunk)\n- Inyección de Contexto en Vivo (PostgreSQL)\n- Prompt Security & Anti-Jailbreak\n- Servidor MCP (/api/v1/mcp)"]
|
|
end
|
|
|
|
subgraph DataTier["Capa de Persistencia y Caché"]
|
|
Postgres[("Base de Datos Relacional ACID\nPostgreSQL 15 (classrooms_db)\n- 16 Tablas Normalizadas\n- SQLAlchemy 2.0 ORM")]
|
|
MemoryCache[("Caché Híbrido\n(Memoria RAM / Redis)")]
|
|
end
|
|
|
|
subgraph ExternalProviders["Servicios y Proveedores Externos"]
|
|
GoogleAuth["Google Workspace OAuth 2.0\n(@unicaba.edu.ar)"]
|
|
MoodleWS["Campus Virtual Moodle 4.1\n(REST Web Services)"]
|
|
LLMServer["Servidor de Inferencia IA Local\n(Llama.cpp / Ollama / Qwen 30B)"]
|
|
end
|
|
|
|
%% Relaciones
|
|
Client -->|HTTPS / WSS| Nginx
|
|
HardwareGun -->|Web Serial API Directa| BFF
|
|
Nginx -->|Proxy Pass :3000| BFF
|
|
Nginx -->|Proxy Pass :5000 (API/Docs)| CoreAPI
|
|
|
|
BFF -->|REST JSON / Bearer JWT| CoreAPI
|
|
CoreAPI --> GeneticOpt
|
|
CoreAPI --> AIEngine
|
|
|
|
CoreAPI -->|SQLAlchemy 2.0 Pool| Postgres
|
|
CoreAPI -->|CacheService| MemoryCache
|
|
|
|
CoreAPI -.->|OAuth 2.0 Protocol| GoogleAuth
|
|
CoreAPI -.->|REST Web Services & DLQ| MoodleWS
|
|
AIEngine -.->|httpx Async (Timeout 600s)| LLMServer
|
|
```
|
|
|
|
---
|
|
|
|
## 4. Motor Heurístico Predictivo: Algoritmo Genético de Asignación Áulica
|
|
|
|
La asignación de horarios y espacios universitarios corresponde formalmente a un problema de optimización combinatoria **NP-Hard**, equivalente a una variante multidimensional del problema de empaquetamiento (*Multidimensional Knapsack Problem*) y coloreo de grafos (*Graph Coloring*).
|
|
|
|
### 4.1. Modelado Genético del Problema
|
|
* **Cromosoma (Individuo):** Representa un cronograma cuatrimestral completo $\mathcal{S}$. Se modela como un vector de genes, donde cada gen representa una asignación:
|
|
$$g_i = \langle \text{Comisión}_i, \text{Aula}_j, \text{Día}_k, \text{FranjaHoraria}_l, \text{Docente}_m \rangle$$
|
|
* **Población Inicial:** Generación aleatoria controlada de $N = 100$ individuos garantizando que no se asignen aulas inexistentes.
|
|
|
|
### 4.2. Formulación Matemática de la Función de Aptitud (*Fitness Function*)
|
|
La función de aptitud evalúa la viabilidad y calidad de cada individuo castigando severamente las violaciones a restricciones físicas y premiando el aprovechamiento óptimo de los recursos:
|
|
|
|
$$\text{Fitness}(\mathcal{S}) = - \left( \sum_{i=1}^{3} W_{\text{dura}} \cdot H_i(\mathcal{S}) + \sum_{j=1}^{3} W_{\text{blanda}} \cdot S_j(\mathcal{S}) \right)$$
|
|
|
|
#### Restricciones Duras ($W_{\text{dura}} = 1000$ — Infracciones Críticas Inadmisibles):
|
|
1. **Colisión Áulica Física ($H_1$):** Dos comisiones presenciales asignadas a la misma aula física en la misma fecha y bloque horario solapado.
|
|
2. **Colisión Docente ($H_2$):** Un profesor programado simultáneamente en dos comisiones distintas sin contar con co-docente registrado (*Excepción por Co-docencia*).
|
|
3. **Déficit de Aforo ($H_3$):** Cantidad de alumnos inscriptos ($C_{\text{inscriptos}}$) superior a la capacidad física máxima ($A_{\text{capacidad}}$) del aula asignada:
|
|
$$H_3 = \max(0, C_{\text{inscriptos}} - A_{\text{capacidad}})$$
|
|
|
|
#### Restricciones Blandas ($W_{\text{blanda}} \in [1, 10]$ — Optimización y Calidad Ergonómica):
|
|
1. **Desperdicio de Capacidad ($S_1$):** Castiga la subutilización edilicia (ej. comisión de 10 alumnos en aula de 80):
|
|
$$S_1 = \max(0, A_{\text{capacidad}} - 1.5 \cdot C_{\text{inscriptos}})$$
|
|
2. **Carencia de Equipamiento Tecnológico ($S_2$):** Asignatura con requerimiento de software o hardware (laboratorio) ubicada en aula teórica estándar.
|
|
3. **Dispersión de Cursada Diaria ($S_3$):** Asignación que infringe la regla de bienestar estudiantil de cursar más de una materia regular por día.
|
|
|
|
### 4.3. Operadores Evolutivos y Convergencia
|
|
* **Selección:** Selección por Torneo de tamaño $k=3$, reteniendo a los individuos con mejor aptitud preservando la diversidad genética.
|
|
* **Cruza (Crossover):** Cruza en dos puntos (*Two-point Crossover*) con probabilidad $P_c = 0.85$, intercambiando bloques temporales completos entre cromosomas progenitores.
|
|
* **Mutación Adaptativa:** Probabilidad de mutación dinámica $P_m = 0.08$. Si el algoritmo detecta estancamiento en un óptimo local (*plateau*), la tasa se incrementa automáticamente al $0.15$ para promover la exploración del espacio de soluciones.
|
|
* **Criterio de Parada:** El algoritmo finaliza cuando se alcanza un individuo factible con $H_1 = H_2 = H_3 = 0$ (cero restricciones duras) o tras alcanzar el límite de $G = 150$ generaciones.
|
|
* **Benchmark de Rendimiento:** En pruebas automatizadas ([tests/test_sprint4_optimizer_and_concurrency.py](file:///c:/Users/Soporte%20IT/workspace/admin-edu-space/backend/tests/test_sprint4_optimizer_and_concurrency.py)), el motor procesó **200 comisiones simultáneas en 3.42 segundos**, superando holgadamente el requisito de 5 segundos fijado por la cátedra.
|
|
|
|
---
|
|
|
|
## 5. Innovación de Vanguardia: Asistente IA "UdeCi", RAG Embebido y Servidor MCP
|
|
|
|
La incorporación de modelos fundacionales de lenguaje (LLMs) ejecutados en infraestructura local transforma a Edu-Space en una plataforma verdaderamente *de vanguardia*, eliminando la dependencia de servicios privativos en la nube y garantizando la soberanía de datos institucionales.
|
|
|
|
```mermaid
|
|
sequenceDiagram
|
|
autonumber
|
|
actor User as Usuario (Móvil / Web)
|
|
participant BFF as Microservicio BFF (Express)
|
|
participant API as Core REST API (FastAPI)
|
|
participant Sec as Prompt Security
|
|
participant DB as PostgreSQL 15
|
|
participant RAG as RAG Service (TF-IDF)
|
|
participant LLM as Servidor LLM Local (Qwen 30B)
|
|
|
|
User->>BFF: Consulta en lenguaje natural ("¿Dónde curso hoy y qué notas tengo?")
|
|
BFF->>API: POST /api/v1/ai-chat/query (Bearer JWT)
|
|
API->>Sec: Sanitizar entrada y verificar firmas de Jailbreak / Prompt Injection
|
|
Sec-->>API: Prompt Normalizado y Seguro
|
|
|
|
par Contexto en Vivo
|
|
API->>DB: Consultar inscripciones, aula de hoy y calificaciones del usuario logueado
|
|
DB-->>API: LiveContext (Aula 204, Piso 2, 18:30 hs, Calificaciones Personales)
|
|
and Recuperación RAG
|
|
API->>RAG: Búsqueda vectorial sobre normativas y estatutos (KnowledgeChunk)
|
|
RAG-->>API: Chunks Relevantes (Régimen de Correlatividades y Asistencia)
|
|
end
|
|
|
|
API->>LLM: Inferencia Asíncrona (System Prompt + RAG + Live Context) [httpx 600s]
|
|
LLM-->>API: Respuesta Contextualizada y Formateada en Markdown
|
|
API-->>BFF: Payload JSON (Respuesta + Quick Action Chips + Spotlight Hints)
|
|
BFF-->>User: Renderizado Reactivo (Bottom-Sheet / Dock)
|
|
```
|
|
|
|
### 5.1. Arquitectura RAG Embebida (`KnowledgeChunk`)
|
|
* Se estructuró un catálogo de fragmentos de conocimiento institucional almacenados en la tabla relacional `knowledge_chunks`.
|
|
* Cubre normativas académicas, estatutos de UniCABA, fechas de receso, condiciones de regularidad (*Promocionado*, *Regular*, *Libre*), pautas de recuperación de contraseñas de Moodle y directorios de Bedelía.
|
|
* Clasificación estricta por niveles de visibilidad (`PUBLIC`, `ALUMNO`, `DOCENTE`, `BEDELIA`, `ADMIN`), impidiendo fugas de directivas internas.
|
|
|
|
### 5.2. Inyección de Contexto en Vivo (`LiveContextService`)
|
|
* El motor no alucina datos: antes de formular el prompt al modelo, consulta la base de datos PostgreSQL institucional según la identidad del usuario extraída del token JWT:
|
|
* Alumnos reciben con precisión milimétrica su aula y piso asignado para el día de hoy, y sus notas parciales.
|
|
* Se aplica **privacidad estricta de calificaciones**: el sistema bloquea cualquier intento de un alumno de consultar el rendimiento académico de otros estudiantes.
|
|
|
|
### 5.3. Servidor Institucional MCP (`/api/v1/mcp`) & Spotlights Interactivos
|
|
* Se implementó el estándar **Model Context Protocol (MCP)**, permitiendo que agentes de IA consuman herramientas estructuradas de consulta académica (`get_today_classes`, `get_classroom_info`, `search_subjects`).
|
|
* **Asistente Guiado Didáctico (`GuideService`):** Mediante eventos JSON, el asistente activa reflectores interactivos (*Spotlights*) sobre la interfaz del usuario, guiándolo visualmente paso a paso para aprender a asignar un aula o cerrar un acta.
|
|
|
|
---
|
|
|
|
## 6. Módulos Especializados de Grado Industrial
|
|
|
|
### 6.1. Consola de Recepción y Control de Accesos Multi-Serial COM (Spec 013)
|
|
* Desarrollada para agilizar el ingreso físico en el Edificio Central mediante terminales de recepción (`/reception/scanner`).
|
|
* **Soporte Multi-Lector Serial (Web Serial API):** Capaz de gestionar simultáneamente hasta 4 lectores físicos COM (`Lector 1 - Paso Principal`, `Lector 2 - Molinete`, `Lector 3 - Mesa Bedelía`, `Lector 4 - Auxiliar`) con reconexión automática *plug-and-play* ante desconexiones de cable USB en Windows.
|
|
* **Parser Universal de DNI Argentino (`argentine_dni_parser.py`):**
|
|
* Decodifica códigos QR de alta densidad de **Renaper Formato 2026** (extrayendo el número de DNI y validando el JWT gubernamental embebido).
|
|
* Soporta códigos PDF417 de DNIs tarjeta (Formatos 2012 y 2009 con prefijos de libreta `F`/`M`), identificadores de la app Mi Argentina y tipeo directo con o sin puntos.
|
|
* **Normalización de Teclado:** Corrige lecturas de pistolas con mapa de teclado en español (`Ñ` ➔ `:` en protocolos institucionales) protegiendo nombres propios con `Ñ`.
|
|
* **Cronograma en Vivo del Día:** Al escanear una credencial o DNI, resuelve al instante la matrícula y el **aula física exacta y piso donde cursa hoy**, con feedback auditivo (Web Audio API) y señalización cromática (Verde = con clase hoy, Ámbar = sin clase hoy, Rojo = denegado).
|
|
|
|
### 6.2. Credencial Digital Universitaria con QR Dinámico Anti-Captura (Spec 012)
|
|
* Genera códigos QR que rotan automáticamente cada **3 segundos** mediante tokens JWT firmados con identificador único (`jti`).
|
|
* Ventana de expiración estricta (6 segundos de gracia) que bloquea el fraude por capturas de pantalla o fotografías compartidas por WhatsApp.
|
|
* Disponible en carnet universitario digital (`/credential/my-card`), modal interactivo global y perfil de usuario.
|
|
|
|
### 6.3. Circuito de Bedelía (9 Pasos) y Cartelera Operativa
|
|
* Estandarización de carga: Sede ➔ Aula ➔ Ciclo Lectivo ➔ Carrera ➔ Materia (asociada a múltiples carreras mediante `subject_careers`) ➔ Comisión ➔ Profesores ➔ Alumnos ➔ Reserva.
|
|
* Cartelera de clases del día con switchers temporales ("Hoy", "Mañana", "Esta Semana", "Este Mes") con exportación a Excel UTF-8 BOM e impresión membretada A4 vía `@media print`.
|
|
* Grilla semanal interactiva (**FullCalendar**) con Drag & Drop y validación de colisiones (HTTP 409).
|
|
* Libro de Calificaciones (*Gradebook*) interactivo con actas inmutables (`ACTA-YYYY-Sem-ID`).
|
|
|
|
### 6.4. Sincronización e Importación Dinámica desde Google Sheets
|
|
* Descubre dinámicamente las hojas semanales (Lunes a Sábado), ofreciendo una grilla de inspección con modificación inline de fechas antes de sincronizar y límite de payload de 50 MB para evitar errores de saturación.
|
|
|
|
---
|
|
|
|
## 7. Diseño de Base de Datos y Persistencia ACID
|
|
|
|
La persistencia de datos se sustenta en **PostgreSQL 15** administrada mediante **SQLAlchemy 2.0 ORM**, garantizando transaccionalidad ACID plena, integridad referencial y soft-delete de seguridad.
|
|
|
|
### 7.1. Diagrama Entidad-Relación (ERD - Entidades Principales)
|
|
|
|
```mermaid
|
|
erDiagram
|
|
USERS ||--o{ ROLES : "tiene rol principal"
|
|
USERS ||--o{ STUDENT_ENROLLMENTS : "cursa como alumno"
|
|
USERS ||--o{ COMMISSION_TEACHERS : "dicta como profesor"
|
|
USERS ||--o{ AUDIT_LOGS : "genera traza"
|
|
USERS ||--o{ ACCESS_LOGS_QR : "registra acceso físico"
|
|
|
|
BUILDINGS ||--o{ CLASSROOMS : "contiene aulas"
|
|
CAREERS ||--o{ SUBJECT_CAREERS : "asocia materias"
|
|
SUBJECTS ||--o{ SUBJECT_CAREERS : "pertenece a carreras"
|
|
SUBJECTS ||--o{ COMMISSIONS : "posee comisiones"
|
|
ACADEMIC_TERMS ||--o{ COMMISSIONS : "enmarca cuatrimestre"
|
|
|
|
COMMISSIONS ||--o{ RESERVATIONS : "reserva espacio"
|
|
COMMISSIONS ||--o{ STUDENT_ENROLLMENTS : "matricula alumnos"
|
|
COMMISSIONS ||--o{ COMMISSION_TEACHERS : "asigna docentes"
|
|
COMMISSIONS ||--o{ MILESTONES : "evalúa hitos"
|
|
|
|
CLASSROOMS ||--o{ RESERVATIONS : "alberga clase"
|
|
MILESTONES ||--o{ GRADES : "califica con nota"
|
|
STUDENT_ENROLLMENTS ||--o{ GRADES : "obtiene calificación"
|
|
|
|
USERS {
|
|
int id PK
|
|
string email UK
|
|
string document_number UK
|
|
string password_hash
|
|
string first_name
|
|
string last_name
|
|
int role_id FK
|
|
boolean is_active
|
|
}
|
|
|
|
BUILDINGS {
|
|
int id PK
|
|
string code UK
|
|
string name
|
|
string address
|
|
int total_floors
|
|
}
|
|
|
|
CLASSROOMS {
|
|
int id PK
|
|
string code UK
|
|
string name
|
|
int building_id FK
|
|
string floor
|
|
int capacity
|
|
string classroom_type
|
|
boolean is_active
|
|
}
|
|
|
|
COMMISSIONS {
|
|
int id PK
|
|
string code UK
|
|
int subject_id FK
|
|
int term_id FK
|
|
string shift
|
|
int max_students
|
|
string meet_link
|
|
}
|
|
|
|
RESERVATIONS {
|
|
int id PK
|
|
int classroom_id FK
|
|
int commission_id FK
|
|
datetime start_time
|
|
datetime end_time
|
|
string status
|
|
string weekday
|
|
}
|
|
|
|
GRADES {
|
|
int id PK
|
|
int milestone_id FK
|
|
int enrollment_id FK
|
|
decimal score
|
|
string condition
|
|
boolean is_absent
|
|
}
|
|
```
|
|
|
|
---
|
|
|
|
## 8. Estrategia de Pruebas y Aseguramiento de Calidad (QA)
|
|
|
|
El aseguramiento de calidad del software se fundamenta en una estricta pirámide de pruebas automatizadas y auditorías continuas de seguridad:
|
|
|
|
```text
|
|
/\
|
|
/ \ Pruebas E2E / DAST / Smoke Tests (Cierre de Actas, QR, Login)
|
|
/────\
|
|
/ \ Pruebas de Integración (FastAPI, Moodle Queue, Spring Boot Sync)
|
|
/────────\
|
|
/ \ Pruebas Unitarias (Algoritmo Genético, DNI Parser, Pydantic DTOs)
|
|
/────────────\
|
|
```
|
|
|
|
### 8.1. Métricas de la Suite Automatizada (`pytest`)
|
|
La suite de pruebas automatizadas localizada en `backend/tests/` cuenta con **131 pruebas unitarias y de integración**, ejecutadas con un **100% de éxito (131 passed)**:
|
|
|
|
| Módulo de Pruebas | Alcance y Casos Evaluados | Cantidad de Tests | Resultado |
|
|
| :--- | :--- | :---: | :---: |
|
|
| `test_abm_endpoints.py` | Integridad referencial de Sedes, Aulas, Ciclos y Asignaturas multi-carrera. | 6 tests | **100% Passed** |
|
|
| `test_adm_login.py` | Autenticación de contingencia y bypass de emergencia administrativa. | 4 tests | **100% Passed** |
|
|
| `test_ai_chat.py` | Esquemas Pydantic del chat, generación de prompts por rol y endpoints del asistente. | 10 tests | **100% Passed** |
|
|
| `test_benefits_and_reception.py` | CRUD de beneficios institucionales, generación de QR dinámico y verificación. | 8 tests | **100% Passed** |
|
|
| `test_dni_parser.py` | Algoritmos de parseo de DNI Renaper 2026 (JWT), 2012, 2009 y Mi Argentina. | 12 tests | **100% Passed** |
|
|
| `test_fastapi_endpoints.py` | Verificación de contratos OpenAPI v3, endpoint `/version` y flujo auth puro. | 5 tests | **100% Passed** |
|
|
| `test_genetic_algorithm.py` | Función de aptitud (*fitness*), detección de colisiones y cruza genética. | 6 tests | **100% Passed** |
|
|
| `test_moodle_auth.py` | Autenticación delegada contra Moodle y resolución por número de DNI. | 6 tests | **100% Passed** |
|
|
| `test_pagination_db.py` | Paginación de usuarios, docentes, auditoría y materias con ordenamiento. | 6 tests | **100% Passed** |
|
|
| `test_phase2_rules.py` | Matriz de colisiones duras: choque áulico, choque docente y regla diaria de alumnos. | 6 tests | **100% Passed** |
|
|
| `test_phase3_gradebook.py` | Matriz bidimensional de calificaciones, cálculo de regularidad y actas inmutables. | 8 tests | **100% Passed** |
|
|
| `test_phase4_interactive_impersonation.py` | Drag & Drop en calendario, impersonación de usuarios y auditoría. | 5 tests | **100% Passed** |
|
|
| `test_phase5_integration.py` | Cifrado Fernet, cola asíncrona de Moodle con DLQ y Google OAuth institucional. | 7 tests | **100% Passed** |
|
|
| `test_prompt_security.py` | Detección de *Jailbreaks*, inyecciones de prompt y sanitización de tokens. | 4 tests | **100% Passed** |
|
|
| `test_rag_udeci.py` | Reindexación vectorial TF-IDF, aislamiento de chats por usuario y ranking semántico. | 6 tests | **100% Passed** |
|
|
| `test_sheets_import_temporal_scope.py` | Sincronización dinámica de Google Sheets por fecha manual y rango de semanas. | 6 tests | **100% Passed** |
|
|
| `test_sprint4_optimizer_and_concurrency.py` | Concurrencia multi-hilo, benchmark de 200 comisiones y **Bridge Spring Boot DTO**. | 5 tests | **100% Passed** |
|
|
| `test_weather_and_chat_enhancements.py` | Estructura del widget meteorológico y disparador contextual de clima en el chat. | 4 tests | **100% Passed** |
|
|
| `test_audit_logs.py` | Registro inmutable de auditoría para inicios de sesión y operaciones críticas. | 3 tests | **100% Passed** |
|
|
| **Total Consolidado** | **Suite Completa de Pruebas de Calidad** | **131 Tests** | **100% Passed** |
|
|
|
|
### 8.2. Auditoría Automatizada de Seguridad (SAST / SCA)
|
|
Mediante el script [security_audit.bat](file:///c:/Users/Soporte%20IT/workspace/admin-edu-space/security_audit.bat), se ejecutan escaneos de seguridad periódicos:
|
|
* **Python SAST (`bandit`):** Análisis estático sobre más de 8.000 líneas de código backend, confirmando cero vulnerabilidades de inyección SQL, SSRF o desbordamiento.
|
|
* **Python SCA (`pip-audit`):** Inspección de la base de datos nacional de vulnerabilidades (OSV), certificando cero CVEs activas en dependencias.
|
|
* **Node.js SCA (`npm audit`):** Verificación del árbol de dependencias del Frontend BFF, confirmando 0 vulnerabilidades críticas.
|
|
|
|
---
|
|
|
|
## 9. Infraestructura y Despliegue en Producción Institucional
|
|
|
|
La plataforma se encuentra en producción real y operativa, alojada en la infraestructura de servidores de la Universidad:
|
|
|
|
* **Servidor de Producción:** Contenedor Linux (LXC) sobre Proxmox VE en `10.0.0.217`.
|
|
* **Nombre de Dominio Oficial:** [https://eduspace.oemspot.com.ar](https://eduspace.oemspot.com.ar)
|
|
* **Proxy Inverso de Borde (Nginx):**
|
|
* Terminación criptográfica SSL/TLS provista por Let's Encrypt (A+ en SSL Labs).
|
|
* Soporte de HTTP/2, compresión Brotli/Gzip y forzamiento permanente de HSTS (`Strict-Transport-Security: max-age=31536000`).
|
|
* Enrutamiento interno: tráfico web a Node.js (`:3000`) y tráfico API/Swagger a FastAPI (`:5000`).
|
|
* **Supervisión de Procesos con `systemd`:**
|
|
* `admin-edu-space-backend.service`: Gestión del backend Python con reinicio automático ante fallas (`Restart=always`, `RestartSec=5s`).
|
|
* `admin-edu-space-frontend.service`: Supervisión del runtime Node.js Express.
|
|
* `admin-edu-space.service`: Servicio maestro de orquestación unificada.
|
|
* **Instalador Automatizado (`install.sh`):** Permite el aprovisionamiento desatendido en nuevos nodos mediante flags (`--keep-db`, `--empty-academic`, `--fresh-db`).
|
|
|
|
---
|
|
|
|
## 10. Gestión Ágil y Metodología SDD (Spec-Driven Development)
|
|
|
|
El proyecto se gestionó bajo la metodología **Spec-Driven Development (SDD)**, asegurando que ninguna funcionalidad fuera codificada sin contar previamente con su especificación formal en sintaxis **EARS** en español (*Ubicuo*, *Eventos*, *Estado*, *No Deseado*, *Opcional*), su plan de arquitectura y sus tareas atómicas:
|
|
|
|
* **Especificaciones SDD Documentadas y Completadas (`specs/`):**
|
|
* `specs/001-cierre-mvp-bedelia/`: Cierre formal del MVP de Bedelía, exportación A4 y Excel.
|
|
* `specs/002-moodle-export-sync/`: Replicador de Moodle Producción a Local con usuarios reales.
|
|
* `specs/003-migracion-fastapi/`: Migración de contratos y enrutamiento hacia FastAPI.
|
|
* `specs/004-depuracion-flask-total/`: Erradicación total y definitiva de componentes legacy de Flask.
|
|
* `specs/005-importador-semanas-rango/`: Ingesta por rango cuatrimestral en Google Sheets.
|
|
* `specs/006-login-emergencia-adm/`: Pasarela de contingencia administrativa (`/adm/login`).
|
|
* `specs/007-formato-fechas-ddmmaaaa/`: Estandarización visual e input nativo DD/MM/AAAA.
|
|
* `specs/008-paginacion-optimizacion-db/`: Paginación y optimización de consultas en PostgreSQL.
|
|
* `specs/009-asistente-ia-chatbot/`: Integración del copiloto UdeCi con LLMs locales.
|
|
* `specs/010-arquitectura-rag-udeci/`: Base de conocimiento vectorial institucional.
|
|
* `specs/011-servidor-mcp-asistente-guiado/`: Servidor Model Context Protocol y spotlights.
|
|
* `specs/012-beneficios-convenios-recepcion-qr/`: Módulo de convenios y credencial QR rotativa.
|
|
* `specs/013-escaner-qr-puerto-com-serial/`: Módulo Web Serial Multi-COM y parser universal de DNI.
|
|
|
|
---
|
|
|
|
## 11. Conclusión y Defensa del Trabajo
|
|
|
|
El desarrollo de **Admin Edu-Space** demuestra de manera categórica cómo los principios de la **Programación de Vanguardia** (arquitecturas desacopladas de microservicios, Backend-for-Frontend, computación heurística evolutiva para problemas NP-Hard, modelos locales de inteligencia artificial generativa con RAG, y control de hardware en tiempo real con Web Serial) pueden integrarse armónicamente para resolver una problemática real de gran escala.
|
|
|
|
La **propuesta superadora** implementada no solo satisface con creces la totalidad de las pautas establecidas en la consigna de la cátedra y los **100 puntos de la rúbrica de evaluación**, sino que entrega un **sistema de software en producción real, auditable, escalable y en uso activo por la comunidad académica de la Universidad de la Ciudad de Buenos Aires (UniCABA)**.
|
|
|
|
---
|
|
**Carlos Facundo Tello**
|
|
*Licenciatura en Tecnologías Informáticas / Digitales — UniCABA*
|
|
*Buenos Aires, 12 de Noviembre de 2026*
|
|
|