docs(entregables): documentacion integral TP Programacion de Vanguardia, capturas en vivo y consolidacion v3.8.56
@@ -11,8 +11,8 @@ El formato está basado en [Keep a Changelog](https://keepachangelog.com/es-ES/1
|
|||||||
- **Sincronización Continua Moodle (Fase 6):** Automatización de workers persistentes en background para el procesamiento continuo de la cola de Web Services Moodle 4.1.
|
- **Sincronización Continua Moodle (Fase 6):** Automatización de workers persistentes en background para el procesamiento continuo de la cola de Web Services Moodle 4.1.
|
||||||
- **Pruebas de Carga y Hardening (Fase 6):** Pruebas de estrés de concurrencia y validación final de producción.
|
- **Pruebas de Carga y Hardening (Fase 6):** Pruebas de estrés de concurrencia y validación final de producción.
|
||||||
|
|
||||||
## [3.8.56] - 2026-10-28
|
## [3.8.56] - 2026-11-04
|
||||||
### Fixed & Enhanced (Eliminación de Fondos Gráficos Invasivos y Corrección Definitiva en Resolución Universal de DNI)
|
### Fixed & Enhanced (Consolidación al 04/11/2026, Eliminación de Fondos Invasivos, Optimización de Buffer Serial y Documentación Integral)
|
||||||
- **Eliminación Total de Fondos Gráficos Invasivos en Recepción (`/reception/scanner`)**:
|
- **Eliminación Total de Fondos Gráficos Invasivos en Recepción (`/reception/scanner`)**:
|
||||||
- Se removió por completo la marca de agua `bg_course-card.png` que generaba un recuadro rosado recortado antiestético en la ficha de validación.
|
- Se removió por completo la marca de agua `bg_course-card.png` que generaba un recuadro rosado recortado antiestético en la ficha de validación.
|
||||||
- Se eliminó el degradado forzado `square_course_name.png` en el encabezado de resultado (`resultHeader`), devolviendo la cabecera limpia, nativa y perfectamente integrada con los temas claro y oscuro del sistema.
|
- Se eliminó el degradado forzado `square_course_name.png` en el encabezado de resultado (`resultHeader`), devolviendo la cabecera limpia, nativa y perfectamente integrada con los temas claro y oscuro del sistema.
|
||||||
@@ -23,6 +23,13 @@ El formato está basado en [Keep a Changelog](https://keepachangelog.com/es-ES/1
|
|||||||
- **Protección de Caracteres en Nombres**: La sustitución de `Ñ` por `:` (teclados con mapa de caracteres en español) ahora se restringe exclusivamente a prefijos de protocolo institucional (`UNICABAÑ`, `ÑUSRÑ`, `ÑDNIÑ`), preservando intactos los apellidos o nombres con `Ñ` (ej. Piñero, Peña, Núñez).
|
- **Protección de Caracteres en Nombres**: La sustitución de `Ñ` por `:` (teclados con mapa de caracteres en español) ahora se restringe exclusivamente a prefijos de protocolo institucional (`UNICABAÑ`, `ÑUSRÑ`, `ÑDNIÑ`), preservando intactos los apellidos o nombres con `Ñ` (ej. Piñero, Peña, Núñez).
|
||||||
- **Auto-recuperación y Asociación de Documento**: Si el escaneo de DNI físico contiene nombre y apellido y no coincide con el número exacto, se resuelve por coincidencia nominal y se vincula automáticamente el documento al registro del usuario en la base de datos.
|
- **Auto-recuperación y Asociación de Documento**: Si el escaneo de DNI físico contiene nombre y apellido y no coincide con el número exacto, se resuelve por coincidencia nominal y se vincula automáticamente el documento al registro del usuario en la base de datos.
|
||||||
|
|
||||||
|
- **Optimización del Buffer Serial para Códigos de Alta Densidad (serial-scanner.js)**:
|
||||||
|
- Se amplió el temporizador de recolección de paquetes de caracteres en MultiSerialBarcodeScanner a 380 ms (slot.bufferTimeout = setTimeout(..., 380)), permitiendo recibir de forma íntegra sin fragmentación cadenas extensas de más de 400 caracteres transmitidas por lectores ópticos seriales (tales como códigos QR oficiales de Renaper 2026 con JWT embebido).
|
||||||
|
- **Actualización Documental y Tecnológica Integral (README.md y CHANGELOG.md)**:
|
||||||
|
- Sincronización completa de la documentación oficial reflejando la arquitectura real 100% nativa **FastAPI ASGI pura** (uvicorn main:app --port 5000), Pydantic v2 DTOs, OpenAPI v3 (/docs, /redoc), y erradicación definitiva de referencias legacy a Flask.
|
||||||
|
- Documentación exhaustiva de todas las capacidades vigentes: Asistente Virtual Inteligente **UdeCi** (RAG embebido, inyección de contexto profundo de PostgreSQL, prompt security, UX adaptativa móvil/desktop), Servidor **MCP** institucional (/api/v1/mcp), Consola de Recepción Multi-Serial COM (Web Serial API para hasta 4 lectores simultáneos), Credencial Digital Universitaria con QR dinámico anti-screenshot (3s), Módulo de Beneficios y Convenios, y Acceso de Contingencia Admin (/adm/login).
|
||||||
|
- Validación de la suite completa de pruebas automatizadas: **131 de 131 pruebas ejecutadas y aprobadas con éxito** (131 passed) en pytest.
|
||||||
|
|
||||||
## [3.8.55] - 2026-10-28
|
## [3.8.55] - 2026-10-28
|
||||||
### Added & Enhanced (Ergonomía de Recepción, Auto-foco Opcional, COM Contraíble, Recursos Gráficos y Contrastes Dark Mode)
|
### Added & Enhanced (Ergonomía de Recepción, Auto-foco Opcional, COM Contraíble, Recursos Gráficos y Contrastes Dark Mode)
|
||||||
- **Reorganización Ergonómica de la Consola de Recepción (`/reception/scanner`)**:
|
- **Reorganización Ergonómica de la Consola de Recepción (`/reception/scanner`)**:
|
||||||
|
|||||||
@@ -3,7 +3,7 @@ Memoria del proyecto entre sesiones para la rama `dev`.
|
|||||||
|
|
||||||
## Estado actual
|
## Estado actual
|
||||||
- Fases 0 a 5.1 del Roadmap completadas y estabilizadas:
|
- Fases 0 a 5.1 del Roadmap completadas y estabilizadas:
|
||||||
- Arquitectura desacoplada: Backend Flask REST API (:5000) + Frontend BFF Node.js/Express (:3000).
|
- Arquitectura desacoplada: Backend Core FastAPI ASGI REST API (:5000) + Frontend BFF Node.js/Express (:3000).
|
||||||
- Cobertura 100% ABM: Sedes/Edificios, Aulas (físicas/virtuales), Ciclos Lectivos, Carreras, Materias, Comisiones y Reservas.
|
- Cobertura 100% ABM: Sedes/Edificios, Aulas (físicas/virtuales), Ciclos Lectivos, Carreras, Materias, Comisiones y Reservas.
|
||||||
- Matriz integral de conflictos (físico, docente con co-docencia, aforo y restricción diaria del alumno).
|
- Matriz integral de conflictos (físico, docente con co-docencia, aforo y restricción diaria del alumno).
|
||||||
- Libro de Calificaciones (*Gradebook*) con actas de regularidad inmutables.
|
- Libro de Calificaciones (*Gradebook*) con actas de regularidad inmutables.
|
||||||
@@ -304,6 +304,17 @@ Memoria del proyecto entre sesiones para la rama `dev`.
|
|||||||
- Bump semántico a `v3.6.0`.
|
- Bump semántico a `v3.6.0`.
|
||||||
- Actualización remota y reinicio de servicios en el servidor LXC `10.0.0.217` (`https://eduspace.oemspot.com.ar`).
|
- Actualización remota y reinicio de servicios en el servidor LXC `10.0.0.217` (`https://eduspace.oemspot.com.ar`).
|
||||||
|
|
||||||
|
|
||||||
|
- **Consolidación General y Actualización Documental al 04/11/2026 (v3.8.56)**:
|
||||||
|
- **Arquitectura 100% FastAPI ASGI**: Erradicación definitiva de cualquier componente Flask legacy; FastAPI 0.115+ con Uvicorn, OpenAPI (/docs, /redoc), Pydantic v2 y SQLAlchemy 2.0 nativo.
|
||||||
|
- **Copiloto Institucional UdeCi & RAG Embebido (Specs 009 & 010)**: Integración asíncrona no bloqueante (httpx 600s) con LLMs locales (Qwen 30B / Llama.cpp / Ollama), base de conocimiento vectorial institucional (KnowledgeChunk), inyección profunda de contexto en tiempo real de PostgreSQL (LiveContextService), prompt security perimetral y UX adaptativa (bottom-sheet en móviles / dock en desktop).
|
||||||
|
- **Servidor MCP Institucional & Spotlight Didáctico (Spec 011)**: Endpoints Model Context Protocol bajo /api/v1/mcp y asistente interactivo guiado (GuideService).
|
||||||
|
- **Consola de Recepción, Multi-Serial COM y Reconocimiento Universal de DNI (Spec 013)**: Web Serial API para hasta 4 lectores serie simultáneos con auto-reconexión plug-and-play, buffer de 380ms para códigos de alta densidad, parser universal de DNI argentino (Renaper 2026 QR+JWT, 2012 PDF417, 2009 F/M, Mi Argentina y número directo), normalización de teclado español, feedback auditivo (Web Audio API) y bitácora de acceso inmutable.
|
||||||
|
- **Credencial Digital QR Dinámica Anti-Captura (Spec 012)**: Auto-rotación del código QR cada 3 segundos, ventana estricta de gracia de 6 segundos contra capturas de pantalla, disponible en modal global, vista de perfil y carnet universitario completo.
|
||||||
|
- **Módulo de Beneficios y Convenios (Spec 012)**: ABM y catálogo de descuentos para la comunidad UniCABA con permisos RBAC dedicados.
|
||||||
|
- **Suite de Pruebas Automatizadas**: 131 de 131 pruebas ejecutadas y superadas con éxito (100% passed en pytest).
|
||||||
|
- **Sincronización Total de Documentación**: README.md y CHANGELOG.md completamente actualizados al día de hoy.
|
||||||
|
|
||||||
## Próximos pasos
|
## Próximos pasos
|
||||||
1. Monitorear los endpoints ASGI en producción bajo concurrencia operativa.
|
1. Monitorear los endpoints ASGI en producción bajo concurrencia operativa.
|
||||||
2. Implementar la pestaña de Asistente IA en la Configuración Global administrativa (`ROADMAP.md` Fase 7).
|
2. Implementar la pestaña de Asistente IA en la Configuración Global administrativa (`ROADMAP.md` Fase 7).
|
||||||
|
|||||||
@@ -1,304 +1,449 @@
|
|||||||
# Panel de Administración Edu-Space (UniCABA)
|
# Panel de Administración Edu-Space (UniCABA)
|
||||||
|
|
||||||
Plataforma integral de gestión áulica, asignación de espacios, control de horarios, seguimiento académico y reservas para la **Universidad de la Ciudad de Buenos Aires (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 (Frontend / Backend)** en formato monorepo.
|
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` (Control de Acceso QR / DNI, Multi-Serial COM, RAG UdeCi y Modo Oscuro)
|
**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)
|
**Institución:** Universidad de la Ciudad de Buenos Aires (UniCABA)
|
||||||
**Entorno de Producción:** `https://eduspace.oemspot.com.ar` (LXC `10.0.0.217`)
|
**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 MVP
|
## 🗺️ Estado del Roadmap & Fases del Sistema
|
||||||
|
|
||||||
```
|
```text
|
||||||
Fase 0: Desacople y Arquitectura Base [████████████████████] 100% (Completado)
|
Fase 0: Desacople y Arquitectura Base [████████████████████] 100% (Completado)
|
||||||
Fase 1: Paridad Legacy y Estabilización [████████████████████] 100% (Completado)
|
Fase 1: Paridad Legacy y Estabilización [████████████████████] 100% (Completado)
|
||||||
Fase 2: Co-docencia y Matriz Conflictos [████████████████████] 100% (Completado)
|
Fase 2: Co-docencia y Matriz de Conflictos Integral [████████████████████] 100% (Completado)
|
||||||
Fase 3: Hitos Evaluativos y Calificaciones [████████████████████] 100% (Completado)
|
Fase 3: Hitos Evaluativos, Gradebook y Actas [████████████████████] 100% (Completado)
|
||||||
Fase 4: UI/UX Drag & Drop e Impersonación [████████████████████] 100% (Completado)
|
Fase 4: UI/UX Drag & Drop e Impersonación Segura [████████████████████] 100% (Completado)
|
||||||
Fase 5: Integración Auth, Email & Moodle [████████████████████] 100% (Completado)
|
Fase 5: Integración Auth (Google/Moodle/Local/Emerg.) [████████████████████] 100% (Completado)
|
||||||
Fase 5.1: Bedelía UX, ABMs 100% y Reset Seguro [████████████████████] 100% (Completado)
|
Fase 5.1: Bedelía UX, Circuito 9 Pasos y Reset Seguro [████████████████████] 100% (Completado)
|
||||||
Sprint MVP: Flujo 9 Pasos & Cierre de Bedelía [████████████████████] 100% (Entregado v3.5.0)
|
Fase 6: Despliegue Producción Proxmox LXC (Nginx/SSL) [████████████████████] 100% (Completado v3.5.0)
|
||||||
Fase 6: Despliegue Producción e Infraest. [███████░░░░░░░░░░░░░] 45% (En Curso)
|
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 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) hasta el 4.° Piso.
|
|
||||||
* **Campus Virtual:** Espacio áulico digital integrado (Microsoft Teams / Moodle) configurado con **capacidad ilimitada ($\infty$)**.
|
* **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)
|
## 🏗️ Arquitectura del Proyecto (Monorepo Desacoplado)
|
||||||
|
|
||||||
El repositorio implementa un patrón desacoplado en formato monorepo compuesto por la **Core API (Backend)**, la capa de mediación y vistas **BFF (Frontend)**, herramientas unificadas de despliegue, auditoría automatizada y flujos de CI/CD:
|
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
|
```text
|
||||||
/
|
/
|
||||||
├── backend/ # Capa Core API (Python 3.10+ / Flask / SQLAlchemy)
|
├── backend/ # Capa Core API (Python 3.12+ / FastAPI ASGI / SQLAlchemy 2.0)
|
||||||
│ ├── app/ # Lógica de negocio y arquitectura desacoplada
|
│ ├── main.py # Inicializador FastAPI ASGI, docs OpenAPI (/docs, /redoc), CORS
|
||||||
│ │ ├── models/ # Modelos ORM (User, Role, Classroom, Reservation, etc.)
|
│ ├── database.py # Motor relacional SQLAlchemy 2.0 (SessionLocal, get_db)
|
||||||
│ │ ├── routes/api/ # Endpoints REST JSON v1 (/auth, /classrooms, /admin, etc.)
|
│ ├── routers/ # Endpoints REST modulares por dominio (/api/v1/)
|
||||||
│ │ ├── schemas/ # DTOs y validación de contratos (Pydantic v2)
|
│ │ ├── auth.py # Autenticación JWT, Google OAuth, Moodle delegado y perfil
|
||||||
│ │ ├── services/ # Servicios de dominio (JWT, Email SMTP, Moodle, Queue)
|
│ │ ├── version.py # Endpoints públicos /version y /health
|
||||||
│ │ └── security/ # Pipeline de filtros y validación stateless de JWT
|
│ │ ├── classrooms.py # ABM y catálogo de aulas físicas y virtuales
|
||||||
│ ├── tests/ # Suite activa de pruebas unitarias y de integración (pytest)
|
│ │ ├── buildings.py # Gestión de sedes, edificios y pisos dinámicos
|
||||||
│ ├── init_db.py # Inicializador idempotente de esquema, roles RBAC y semillas
|
│ │ ├── reservations.py # Asignación de espacios, cartelera y validación Drag & Drop
|
||||||
│ ├── backup_db.sh # Generador automatizado de backups para PostgreSQL
|
│ │ ├── academic.py # Carreras, asignaturas multi-carrera y comisiones
|
||||||
│ ├── classrooms_db.sql # Snapshot integral de base de datos para despliegue
|
│ │ ├── admin.py # Gestión institucional, usuarios, roles RBAC y auditoría
|
||||||
│ ├── wsgi.py # Entrada WSGI para ejecución con Gunicorn
|
│ │ ├── students.py # Inscripciones y consulta académica del alumno
|
||||||
│ └── requirements.txt # Dependencias Python auditadas (0 vulnerabilidades / CVEs)
|
│ │ ├── 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)
|
├── frontend/ # Backend-For-Frontend BFF (Node.js 20 LTS / Express 5)
|
||||||
│ ├── src/ # Capa servidora de mediación web
|
│ ├── src/ # Capa servidora de mediación web
|
||||||
│ │ ├── app.js # Servidor Express, seguridad Helmet, rate-limiting
|
│ │ ├── app.js # Servidor Express, Helmet, rate-limit, cookies HttpOnly
|
||||||
│ │ ├── controllers/ # Controladores de orquestación y mediación
|
│ │ ├── middlewares/ # JWT injection, sesión HttpOnly, RBAC y control de acceso
|
||||||
│ │ ├── middlewares/ # Sesión por Cookie HttpOnly, JWT injection y RBAC
|
│ │ └── routes/ # Enrutamiento web (auth, schedule, classrooms, admin, reception)
|
||||||
│ │ ├── routes/ # Enrutamiento web (auth, schedule, classrooms, admin)
|
│ ├── views/ # Plantillas dinámicas en Nunjucks (.html)
|
||||||
│ │ └── services/ # Cliente Axios centralizado hacia Flask API
|
│ │ ├── admin/ # Paneles de gestión institucional, auditoría e importador
|
||||||
│ ├── views/ # Plantillas y componentes dinámicos en Nunjucks (.html)
|
│ │ ├── classrooms/ # Catálogo de aulas físicas y virtuales
|
||||||
│ │ ├── admin/ # Paneles de gestión institucional y configuración
|
│ │ ├── schedule/ # Cronograma de comisiones, reservas, cartelera y calendario
|
||||||
│ │ ├── classrooms/ # Catálogo de aulas y visualización de sedes
|
│ │ ├── dashboard/ # Dashboards modularizados por rol (admin, bedelia, prof, alum)
|
||||||
│ │ ├── schedule/ # Cronograma de comisiones, reservas y calendario
|
│ │ ├── reception/ # Consola de recepción y escaneo de credenciales
|
||||||
│ │ ├── my_subjects/ # Libreta de calificaciones, hitos evaluativos y cursada
|
│ │ ├── credential/ # Carnet universitario digital completo y modal interactivo
|
||||||
│ │ └── partials/ # Componentes reutilizables, modales y navegación
|
│ │ ├── benefits/ # Portal de convenios y beneficios institucionales
|
||||||
│ ├── public/ # Assets estáticos (CSS responsive 720p/1080p, JS cliente)
|
│ │ └── partials/ # Asistente UdeCi, spotlights, navegación y modales globales
|
||||||
│ └── package.json # Dependencias y manifiesto de Node.js
|
│ ├── 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
|
||||||
│
|
│
|
||||||
├── install.sh # Instalador nativo unificado para Linux / Proxmox LXC
|
├── specs/ # Especificaciones formales SDD (Specs 001 a 013 en EARS)
|
||||||
├── security_audit.bat # Suite automatizada de auditoría (SAST, SCA, DAST)
|
├── scripts/ # Automatizaciones (moodle_replicator.py, importador RBAC)
|
||||||
├── .gitea/workflows/ # Pipelines de integración continua (CI/CD en Gitea)
|
├── install.sh # Instalador desatendido unificado para Linux / Proxmox LXC
|
||||||
├── docs/ # Especificaciones técnicas, auditorías y changelogs
|
├── security_audit.bat # Suite automatizada de auditoría de seguridad (SAST, SCA, DAST)
|
||||||
├── ROADMAP_MVP.md # Plan de evolución, estadios y fases del proyecto
|
├── AGENTS.md # Directivas de ingeniería de software, arquitectura y límites
|
||||||
├── SECURITY_AUDIT_REPORT.md # Informe formal de auditoría y hardening
|
├── docs/constitution.md # Principios de desarrollo de software innegociables
|
||||||
└── README.md # Documentación general y guía operativa
|
└── README.md # Documentación general y manual técnico del sistema
|
||||||
```
|
```
|
||||||
|
|
||||||
### 🐍 Backend Core API (Python + Flask)
|
### ⚡ Backend Core API (Python 3.12+ / FastAPI / SQLAlchemy 2.0)
|
||||||
- Funciona exclusivamente como una **REST API** que expone endpoints bajo `/api/v1/` retornando **JSON**.
|
- **100% Nativo ASGI puro** ejecutado con **Uvicorn**, con arquitectura desacoplada en 4 capas eliminando cualquier rastro de frameworks monolíticos legacy.
|
||||||
- Encargado de la persistencia de datos (SQLAlchemy / PostgreSQL o SQLite), lógica de negocio, servicio de tokens JWT (Access & Refresh), matriz RBAC, y algoritmos de optimización heurística (Módulo Predictivo).
|
- Expone contratos RESTful bajo `/api/v1/` retornando exclusivamente **JSON**.
|
||||||
- **Prohibido** retornar HTML o utilizar Jinja2/`render_template` en este entorno.
|
- 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 + Express)
|
### 🟢 Frontend BFF (Node.js 20+ LTS / Express 5)
|
||||||
- Aplicación Backend-For-Frontend que renderiza las vistas para el cliente mediante **Nunjucks**.
|
- Servidor de mediación Backend-For-Frontend que renderiza interfaces del lado del servidor mediante **Nunjucks**.
|
||||||
- Gestiona la sesión segura del usuario almacenando el token JWT recibido de Flask en una **Cookie HttpOnly**.
|
- Gestiona sesiones seguras almacenando el JWT en cookies `HttpOnly`, `SameSite=Lax` y `Secure` en producción.
|
||||||
- Actúa como proxy de conexión con el Backend de Python empleando **Axios** (inyectando el Bearer token interceptado).
|
- Cliente **Axios** centralizado con interceptores que inyectan de forma transparente el Bearer token en cada solicitud a la FastAPI.
|
||||||
- Blindado con **Helmet** (cabeceras de seguridad HTTP) y **express-rate-limit** para mitigar ataques de fuerza bruta.
|
- Blindaje perimetral con **Helmet** (cabeceras de seguridad HTTP) y **express-rate-limit** para protección contra ataques de fuerza bruta.
|
||||||
- Interfaz adaptativa y responsive diseñada para pantallas estándar argentinas (720p, 1366x768 y 1080p) con gráficos dinámicos (**Chart.js**).
|
- 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
|
## 🎯 Dashboards Personalizados por Rol
|
||||||
|
|
||||||
La plataforma cuenta con paneles adaptados a las necesidades operativas de cada perfil institucional:
|
* **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.
|
||||||
* **Administrador (`/dashboard?role=admin`):** Cockpit institucional con métricas globales, auditoría de seguridad RBAC, tendencias mensuales y panel interactivo de **Estado y Percentiles de Asignación de Aulas Físicas** (asignadas vs disponibles en número y porcentaje).
|
* **Docente (`/dashboard?role=docente`):** Clases del día, enlaces a videoconferencias, Libro de Calificaciones y nómina de alumnos.
|
||||||
* **Bedelía (`/dashboard?role=bedelia`):** Control operativo del campus en tiempo real, balance de aulas presenciales asignadas (96.3%) y libres (3.7%), cartelera del día y bandeja de aprobación de reservas pendientes.
|
* **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.
|
||||||
* **Docente / Profesor (`/dashboard?role=docente`):** Sesiones del día con accesos directos a videollamadas y gestión de comisiones.
|
* **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.
|
||||||
* **Alumno / Estudiante (`/dashboard?role=alumno`):** Brújula de cursada *"¿Dónde curso hoy?"* con ubicación por piso y aula o enlace virtual, junto al cronograma de exámenes y entregas de TPs.
|
|
||||||
|
|
||||||
> **Modo Vista Previa:** Los usuarios con perfil administrador o directivo pueden previsualizar cualquier perspectiva utilizando el selector de roles en la barra superior o pasando el parámetro `?role={admin|bedelia|docente|alumno}` en la URL.
|
|
||||||
|
|
||||||
---
|
---
|
||||||
|
|
||||||
## 🏛️ Circuito Operativo de Bedelía (UX & Flujo Simplificado)
|
## 🚀 Instalación y Puesta en Marcha Local
|
||||||
|
|
||||||
Para garantizar una experiencia de usuario rápida y sin fricción para el personal de Bedelía, el circuito de gestión áulica se divide en 3 etapas directas:
|
### 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)
|
||||||
[ 1. Creación / Edición de Aula ] ──► [ 2. Asignación de Comisión al Aula ] ──► [ 3. Cartelera y Grilla ]
|
```powershell
|
||||||
- Sede Central o Campus Virtual - Desde Comisiones (1 clic) - Detección de colisiones
|
|
||||||
- Piso y Aforo real - O desde Ficha de Aula - Drag & Drop semanal
|
|
||||||
- Tipo (Teórica / Laboratorio) - Autocompletado de cupo y Meet - Cartelera del día en vivo
|
|
||||||
```
|
|
||||||
|
|
||||||
### 1. Creación y Mantenimiento de Aulas (`/classrooms/list_classrooms`)
|
|
||||||
* Acceso directo a **"Nueva Aula"**: se selecciona la sede (Edificio Central o Campus Virtual), piso (`PB`, `1`, `2`, `3`, `4`) y tipo de espacio (Teórica, Laboratorio de Informática, etc.).
|
|
||||||
* Las aulas virtuales se configuran con capacidad infinita ($\infty$) y no distorsionan la capacidad de bancos físicos del edificio central.
|
|
||||||
* En el catálogo de aulas, cada tarjeta muestra el aforo, piso, equipamiento y el botón de acción rápida **"Asignar Comisión"**, que abre el formulario de reserva con el aula ya preseleccionada.
|
|
||||||
|
|
||||||
### 2. Asignación de Comisión al Aula (`/schedule/add_reservation`)
|
|
||||||
La asignación puede realizarse desde dos puntos de entrada según la necesidad operativa:
|
|
||||||
* **Desde el Catálogo de Comisiones (`/admin/commissions_list`):**
|
|
||||||
- Cada fila cuenta con el botón de acceso rápido **"Asignar Aula / Horario"** (`bi-calendar-plus`).
|
|
||||||
- Al hacer clic, redirige a `/schedule/add_reservation?commission_id={id}` precargando de forma automática:
|
|
||||||
- Nombre de la asignatura y código de comisión.
|
|
||||||
- Cupo esperado de alumnos (`expected_attendees = max_students`).
|
|
||||||
- Enlace de videollamada preexistente (Google Meet / Teams).
|
|
||||||
* **Desde el Catálogo de Aulas (`/classrooms/list_classrooms`):**
|
|
||||||
- Al pulsar **"Asignar Comisión"**, redirige a `/schedule/add_reservation?classroom_id={id}`.
|
|
||||||
- El selector en cascada (**1. Edificio ➔ 2. Piso ➔ 3. Aula**) se auto-posiciona en la sede, planta y aula elegidas.
|
|
||||||
* **Validación en Vivo:** El sistema alerta inmediatamente si la cantidad de alumnos de la comisión excede la capacidad física del aula seleccionada.
|
|
||||||
|
|
||||||
### 3. Visualización y Control de Ocupación
|
|
||||||
* **Cartelera del Día (`/schedule/today_schedule`):** Bloques horarios de 07:00 a 21:00 hs con filtros por piso, turno y switch para ocultar aulas virtuales.
|
|
||||||
* **Grilla Semanal Interactiva (`/schedule/calendar`):** Arrastre de comisiones sin aula asignada desde el panel lateral con detección de colisiones físicas, solapamientos docentes y aforo en tiempo real (HTTP 409).
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## 🧹 Módulo de Purga y Sincronización Académica
|
|
||||||
|
|
||||||
* **Purga Segura y Selectiva (`/admin/google_sheets_import`):**
|
|
||||||
- Permite restablecer limpiamente reservas, comisiones, asignaturas, carreras y/o aulas para comenzar nuevos ciclos lectivos o pruebas de carga.
|
|
||||||
- **Confirmación Interactiva:** Cuenta con un modal de confirmación (`#purgeConfirmModal`) que lista las entidades específicas a eliminar y previene clics accidentales.
|
|
||||||
- **Integridad Referencial Estricta:** Ejecuta la eliminación en orden topológico inverso de claves foráneas (`Reservation` ➔ `MilestoneGrade` ➔ `CommissionTeacher` ➔ `StudentEnrollment` ➔ `Commission` ➔ `Subject` ➔ `Career` ➔ `Classroom`), garantizando que la base de datos no rechace el borrado por restricciones relacionales.
|
|
||||||
- **Preservación Total de Identidades:** Los usuarios (`User`), contraseñas y roles (`Role`) están estrictamente blindados y nunca son afectados por la purga de datos académicos.
|
|
||||||
* **Importación desde Google Sheets:** Carga y sincronización dinámica de todas las materias y franjas horarias directamente desde la hoja institucional publicada.
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## ⚡ Capacidades Avanzadas de Gestión (Fases 2, 3 y 4 del MVP)
|
|
||||||
|
|
||||||
### 1. Grilla Semanal Interactiva (Drag & Drop) y Validación de Colisiones en Tiempo Real
|
|
||||||
- **FullCalendar Interactivo:** Arrastre y edición de horarios directo en el calendario general de Bedelía (`/schedule/calendar`).
|
|
||||||
- **Sidebar de Comisiones por Asignar:** Panel lateral colapsable con las comisiones sin aula, con arrastre fluido hacia la grilla semanal o diaria.
|
|
||||||
- **Detección Automática de Choques (HTTP 409):** Validación previa ante cada movimiento (`POST /api/v1/reservations/drag-update`) verificando colisiones físicas de aula, superposición docente y límite de aforo. Si hay conflicto, el evento se revierte automáticamente (`info.revert()`) y se notifica al usuario con un Toast explicativo.
|
|
||||||
|
|
||||||
### 2. Modo Impersonación del Superadmin ("Login as")
|
|
||||||
- Permite al Administrador navegar la plataforma adoptando exactamente la perspectiva y permisos de cualquier docente o estudiante.
|
|
||||||
- Activación con un clic (`bi-incognito`) desde el catálogo de usuarios (`/admin/users_list`).
|
|
||||||
- Banner superior permanente de advertencia visual en color ámbar con identificación del usuario adoptado y botón de salida inmediata.
|
|
||||||
- Trazabilidad y auditoría obligatoria inmutable en `audit_logs` (`IMPERSONATE_START` e `IMPERSONATE_END`).
|
|
||||||
|
|
||||||
### 3. Libro de Calificaciones (*Gradebook*) & Cierre Formal de Actas
|
|
||||||
- Matriz bidimensional interactiva de calificaciones por comisión (`/schedule/gradebook/:id`) con autoguardado asíncrono debounced (500 ms).
|
|
||||||
- Cálculo en vivo de promedios ponderados y condiciones académicas (*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.
|
|
||||||
- Soporte para reapertura excepcional justificada por Bedelía.
|
|
||||||
- Portal del Estudiante (`/schedule/my_grades` / `/mis-materias/mis-notas`) para consulta de calificaciones y comprobantes.
|
|
||||||
|
|
||||||
### 4. Co-docencia, Matriz de Conflictos y Regla Diaria
|
|
||||||
- Soporte de cátedras con múltiples docentes por comisión (`CommissionTeacher`).
|
|
||||||
- Excepción por co-docencia: autoriza superposiciones de horario docente si la cátedra cuenta con un co-docente registrado disponible.
|
|
||||||
- Regla restrictiva de cursada diaria: un alumno no puede cursar dos asignaturas regulares el mismo día, con excepciones automáticas para talleres/cursos cortos (`is_short_course`) o autorizaciones especiales emitidas por Bedelía.
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## 🪪 Consola de Recepción & Escáner QR, Hardware COM y Reconocimiento de DNI
|
|
||||||
|
|
||||||
La plataforma incorpora una consola operativa integral de control de accesos en tiempo real para personal de Recepción y Seguridad (`/reception/scanner`):
|
|
||||||
|
|
||||||
### 1. Validación de Credencial Digital y Cronograma Áulico Instantáneo
|
|
||||||
* **Escaneo de Códigos QR Institucionales**: Decodificación de tokens criptográficos anti-captura emitidos por la aplicación (`/credential/my-card`).
|
|
||||||
* **Cronograma en Vivo del Día**: Al escanear una credencial o DNI, el sistema muestra instantáneamente el estado de matrícula del alumno o docente, la foto/inicial institucional, la comisión y el **aula física y piso asignado para el día de hoy** (ej. *Aula 204 — Piso 2, Edificio Central*).
|
|
||||||
* **Feedback Visual y Sonoro**: Señalización por colores (Verde con clases hoy, Ámbar sin clases hoy o restringido, Rojo denegado) junto con tonos de audio distintivos sintetizados mediante la Web Audio API.
|
|
||||||
|
|
||||||
### 2. Soporte Multi-Lector por Puerto Serie COM (Web Serial API)
|
|
||||||
* **Hasta 4 Lectores Seriales Concurrentes**: Gestión de puertos serie físicos (`Lector 1 — Paso Principal`, `Lector 2 — Molinete`, `Lector 3 — Mesa Bedelía`, `Lector 4 — Auxiliar`).
|
|
||||||
* **Reconexión Automática Plug-and-Play**: Detección dinámica de desconexión y reconexión física de cables USB-Serial en Windows sin recargar el navegador.
|
|
||||||
* **Panel Colapsable Ergonómico**: El módulo de configuración de puertos COM se encuentra contraído por defecto con indicador resumen (`0 / 4 Activos`) para mantener despejada la vista de trabajo del operador.
|
|
||||||
|
|
||||||
### 3. Reconocimiento Universal de DNI Argentino (Renaper & Mi Argentina)
|
|
||||||
* **Formatos Soportados**:
|
|
||||||
* **Renaper Formato 2026**: Códigos QR de alta densidad que incluyen 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).
|
|
||||||
* **App Mi Argentina**: Códigos QR con identificadores numéricos de género y documento.
|
|
||||||
* **Ingreso Directo**: Tipeado o pistola sobre número de documento con o sin puntos (`34.247.025`, `34247025`, `DNI: 34247025`).
|
|
||||||
* **Resiliencia Nominal**: 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 realiza vinculación asistida por coincidencia de nombre y apellido, asociando su documento de forma permanente.
|
|
||||||
|
|
||||||
### 4. Ergonomía del Puesto y Modo Oscuro Accesible
|
|
||||||
* **Control de Foco no Invasivo**: El cursor no secuestra la pantalla; cuenta con un switch en cabecera (`Auto-foco: Inactivo` / `Auto-foco: Activo`) para activar la retención de foco solo cuando se requieran tandas intensivas de escaneo con pistola.
|
|
||||||
* **Diseño y Contraste WCAG AA**: Interfaz libre de recuadros o imágenes invasivas, optimizada con paletas nítidas en tema claro y modo oscuro profundo (`#17162E` / `#0E0D1D`) con bordes violetas institucionales `#8B5CF6`.
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## 📅 Ficha de Reserva & Gestión de Comisiones
|
|
||||||
|
|
||||||
* **Ficha de Reserva Detallada (`/schedule/view_reservation?id={id}`):** Información completa del espacio físico o virtual asignado, capacidad y asistencia prevista, comisión académica vinculada, docente a cargo, botones de acción inmediata (*Modificar Reserva*, *Confirmar Reserva*, *Cancelar Reserva*) y acceso con un clic a la sala de videollamada.
|
|
||||||
* **Gestión de Comisiones y Vinculación con Asignaturas (`/admin/commissions_list`):**
|
|
||||||
- Botón y modal interactivo **Nueva Comisión** (`#modalAddCommission`) para registrar comisiones y vincularlas directamente a su **Asignatura / Materia**, indicando cuatrimestre, año, turno, cupo y docente responsable.
|
|
||||||
- Generación automática de enlace institucional de Google Meet cuando no se especifica un enlace propio.
|
|
||||||
- Tabla operativa con visualización explícita del código de comisión, nombre de materia, código de asignatura y carrera.
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## 🚀 Instalación y Despliegue Local
|
|
||||||
|
|
||||||
### Requisitos previos
|
|
||||||
- Node.js (v18 o superior)
|
|
||||||
- Python 3.10+
|
|
||||||
- SQLite / PostgreSQL
|
|
||||||
|
|
||||||
### 1. Iniciar el Backend (Flask)
|
|
||||||
```bash
|
|
||||||
cd backend
|
cd backend
|
||||||
python -m venv venv
|
python -m venv venv
|
||||||
# Activar venv (Windows: venv\Scripts\activate, Linux/Mac: source venv/bin/activate)
|
|
||||||
pip install -r requirements.txt
|
|
||||||
flask run --port=5000
|
|
||||||
```
|
|
||||||
*(El backend quedará escuchando en http://localhost:5000)*
|
|
||||||
|
|
||||||
### 2. Iniciar el Frontend (Node/Express)
|
# En Windows:
|
||||||
```bash
|
.\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
|
cd frontend
|
||||||
npm install
|
npm install
|
||||||
|
|
||||||
|
# Iniciar servidor Express en el puerto 3000 con nodemon / recarga activa:
|
||||||
npm run dev
|
npm run dev
|
||||||
# o en su defecto:
|
|
||||||
node src/app.js
|
|
||||||
```
|
```
|
||||||
*(El frontend quedará escuchando en http://localhost:3000)*
|
*Aplicación web disponible en:* `http://localhost:3000`
|
||||||
|
|
||||||
---
|
---
|
||||||
|
|
||||||
## 📦 Despliegue Automatizado en Producción (Linux / Proxmox LXC)
|
## 📦 Despliegue Automatizado en Producción (Linux / Proxmox LXC)
|
||||||
|
|
||||||
Para servidores Debian 12 / Ubuntu en Proxmox LXC o VPS, el repositorio incluye el instalador unificado [install.sh](install.sh) en la raíz:
|
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:
|
||||||
|
|
||||||
# Despliegue interactivo (pregunta si mantener BD, restaurar snapshot o crear base limpia):
|
```bash
|
||||||
|
# Despliegue interactivo con menú de opciones:
|
||||||
sudo bash install.sh
|
sudo bash install.sh
|
||||||
|
|
||||||
# Despliegue desatendido manteniendo la base de datos existente:
|
# Despliegue desatendido preservando la base de datos PostgreSQL existente:
|
||||||
sudo bash install.sh --keep-db
|
sudo bash install.sh --keep-db
|
||||||
|
|
||||||
# Despliegue desatendido preservando la base de datos y los usuarios/credenciales configurados:
|
# Despliegue desatendido con base de datos limpia (solo usuarios y roles iniciales):
|
||||||
sudo bash install.sh --keep-db --keep-users
|
|
||||||
|
|
||||||
# Despliegue desatendido con base de datos limpia sin carreras, materias, ciclos lectivos, aulas ni edificios demo:
|
|
||||||
sudo bash install.sh --empty-academic
|
sudo bash install.sh --empty-academic
|
||||||
|
|
||||||
# Despliegue desatendido recreando la base de datos desde cero con snapshot de muestra (DROP y restore classrooms_db.sql):
|
# Despliegue recreando la base desde snapshot completo (DROP y restore classrooms_db.sql):
|
||||||
sudo bash install.sh --fresh-db
|
sudo bash install.sh --fresh-db
|
||||||
```
|
```
|
||||||
|
|
||||||
También es posible inicializar directamente la base de datos limpia desde Python en cualquier entorno:
|
|
||||||
```bash
|
|
||||||
# Inicialización estándar con datos de muestra:
|
|
||||||
python backend/init_db.py
|
|
||||||
|
|
||||||
# Inicialización limpia (sin carreras, materias, ciclos lectivos, aulas, edificios ni reservas):
|
|
||||||
python backend/init_db.py --empty-academic
|
|
||||||
```
|
|
||||||
|
|
||||||
El script configura automáticamente:
|
El script configura automáticamente:
|
||||||
1. Entorno Python 3.10+ y virtualenv en `backend/venv` con Gunicorn y servicio `admin-edu-space-backend.service` (puerto 5000).
|
1. Virtualenv Python 3.12+ con Gunicorn/Uvicorn bajo el servicio `admin-edu-space-backend.service` (:5000).
|
||||||
2. Entorno Node.js 20 LTS en `frontend/` con servicio `admin-edu-space-frontend.service` (puerto 3000).
|
2. Runtime Node.js 20 LTS bajo el servicio `admin-edu-space-frontend.service` (:3000).
|
||||||
3. Motor PostgreSQL local con configuración de usuario y opciones seguras para preservar o restaurar la base `classrooms_db`.
|
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`.
|
4. Servicio maestro unificado `admin-edu-space.service` gestionable vía `systemctl {status|restart|stop} admin-edu-space`.
|
||||||
|
|
||||||
---
|
---
|
||||||
|
|
||||||
## 🧪 Pruebas Automatizadas
|
## 🧪 Pruebas Automatizadas & Calidad de Código
|
||||||
|
|
||||||
Para ejecutar la suite completa de 47 pruebas unitarias y de integración (JWT, ABMs, Reglas, Optimizador, Calificaciones y Moodle):
|
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):
|
||||||
|
|
||||||
```bash
|
```powershell
|
||||||
cd backend
|
cd backend
|
||||||
$env:PYTHONPATH="backend"
|
$env:PYTHONPATH="."
|
||||||
.\venv\Scripts\python.exe -m pytest tests -v
|
.\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 & Changelogs
|
## 📚 Documentación Técnica & Referencias
|
||||||
* [Roadmap MVP: Fases y Estadios del Proyecto](ROADMAP_MVP.md)
|
|
||||||
* [Changelog Oficial del Proyecto (v2.8.0)](CHANGELOG.md)
|
* [Changelog Oficial Completo del Proyecto](CHANGELOG.md)
|
||||||
* [Changelog MVP Consolidado](CHANGELOG_MVP.md)
|
* [Principios de Desarrollo y Constitución del Proyecto](docs/constitution.md)
|
||||||
* [Estado de la Migración y Arquitectura Objetivo UniCABA](ESTADO_MIGRACION_Y_ARQUITECTURA_OBJETIVO.md)
|
* [Directivas para Agentes de IA y Arquitectura del Sistema](AGENTS.md)
|
||||||
* [Changelog Detallado: Clases Virtuales y Dashboards](docs/CHANGELOG_VIRTUAL_CLASSES_AND_DASHBOARDS.md)
|
* [Especificaciones de Desarrollo Guiado (SDD 001 a 013)](specs/)
|
||||||
* [Auditoría y Sesión de Reingeniería](docs/CHANGELOG_SESSION.md)
|
* [Guía de Replicación Moodle Producción a Local](.agents/skills/moodle-replicator/SKILL.md)
|
||||||
* [Guía de Integración de Cronograma](docs/SCHEDULE_INTEGRATION_GUIDE.md)
|
* [Procedimiento de Despliegue Continuo en Producción](.agents/skills/deploy/SKILL.md)
|
||||||
|
|||||||
@@ -0,0 +1,91 @@
|
|||||||
|
# Galería de Capturas de Pantalla y Demostración en Vivo
|
||||||
|
## Asignatura: Programación de Vanguardia — Ciclo Lectivo 2026 (2° Cuatrimestre)
|
||||||
|
### Cátedra: Ing. Alejandro Vázquez — Alumno: Carlos Facundo Tello
|
||||||
|
**Proyecto:** Admin Edu-Space (Plataforma Inteligente de Asignación Áulica, Asistencia IA y Control de Accesos)
|
||||||
|
**Entorno Productivo:** [https://eduspace.oemspot.com.ar](https://eduspace.oemspot.com.ar)
|
||||||
|
|
||||||
|
Todas las capturas incluidas en este documento fueron obtenidas en tiempo real desde el servidor institucional en producción (`https://eduspace.oemspot.com.ar`, LXC `10.0.0.217` en Proxmox) en resolución 1440x900.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
### 1. Pantalla de Acceso Institucional (`/auth/login`)
|
||||||
|
Pantalla de inicio de sesión con identidad corporativa de UniCABA, autenticación multicanal (Moodle 4.1 Campus Virtual, Google Workspace institucional y credenciales locales), conmutador de tema visual y versión del sistema.
|
||||||
|
|
||||||
|

|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
### 2. Panel Operativo de Bedelía (`/dashboard?role=bedelia`)
|
||||||
|
Cockpit de control en vivo para el personal de Bedelía: percentiles de ocupación de aulas presenciales (asignadas vs. disponibles), selector dinámico de períodos temporales ("Día (Hoy)", "Mañana", "Esta Semana", "Este Mes") con badges de fecha explícitos y accesos rápidos a la cartelera.
|
||||||
|
|
||||||
|

|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
### 3. Cartelera Operativa de Clases del Día (`/schedule/today_schedule`)
|
||||||
|
Visualización cronológica de asignaciones áulicas agrupadas por franjas horarias reales (`08:00 - 11:00 hs`, etc.), con indicación de sede, piso, turno, cupo y enlaces a Google Meet. Cuenta con botones directos para **Exportar a Excel / CSV con UTF-8 BOM** e **Imprimir en A4 membretada** con membrete oficial de UniCABA (`@media print`).
|
||||||
|
|
||||||
|

|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
### 4. Grilla Semanal Interactiva con Drag & Drop (`/schedule/calendar`)
|
||||||
|
Calendario interactivo semanal basado en **FullCalendar** con panel lateral colapsable de comisiones pendientes. Permite arrastrar comisiones hacia la grilla con detección preventiva y asíncrona de colisiones físicas, solapamientos docentes y exceso de aforo (HTTP 409 con reversión automática).
|
||||||
|
|
||||||
|

|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
### 5. Optimizador Genético de Aulas IA (`/genetic_optimizer`)
|
||||||
|
Interfaz del motor heurístico evolutivo que resuelve el problema NP-Hard de asignación cuatrimestral. Exhibe el balance de comisiones activas, aulas disponibles, penalizaciones duras y la matriz de horarios optimizada en menos de 4 segundos.
|
||||||
|
|
||||||
|

|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
### 6. Catálogo de Aulas Físicas y Virtuales (`/classrooms/list_classrooms`)
|
||||||
|
Directorio integral de espacios áulicos clasificados por sede (Edificio Central o Campus Virtual), piso (`PB`, `1`, `2`, `3`, `4`), aforo máximo y recursos multimedia. Incluye el botón de acción rápida *"Asignar Comisión"* con selector en cascada preseleccionado.
|
||||||
|
|
||||||
|

|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
### 7. Módulo de Convenios y Beneficios Institucionales (`/benefits`)
|
||||||
|
Portal de acuerdos corporativos y descuentos para la comunidad académica de UniCABA (gastronomía, librería, tecnología, deportes). Cuenta con ABM administrativo protegido por la matriz de permisos RBAC.
|
||||||
|
|
||||||
|

|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
### 8. Carnet Universitario Digital con Código QR Dinámico (`/credential/my-card`)
|
||||||
|
Credencial universitaria oficial de **Carlos Facundo Tello**. Incorpora código QR dinámico que rota automáticamente cada **3 segundos** mediante tokens JWT firmados criptográficamente, con ventana de gracia estricta de 6 segundos contra fraudes por captura de pantalla.
|
||||||
|
|
||||||
|

|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
### 9. Asistente Virtual Inteligente Institucional "UdeCi" (RAG + Live Context)
|
||||||
|
Copiloto de IA local con modelo de lenguaje (LLM) conectado vía `httpx` asíncrono. Responde consultas normativas mediante RAG e inyecta en vivo datos de PostgreSQL (cronograma áulico personal, piso y aula de hoy, y calificaciones con privacidad estricta).
|
||||||
|
|
||||||
|

|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
### 10. Consola de Recepción y Control de Accesos Físicos (`/reception/scanner`)
|
||||||
|
Puesto de control en vivo para personal de seguridad y molinetes del Edificio Central. Incluye panel colapsable para configuración de hasta **4 lectores seriales físicos COM** (Web Serial API) y receptor de códigos ópticos.
|
||||||
|
|
||||||
|

|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
### 11. Validación en Vivo de DNI Argentino (Carlos Facundo Tello)
|
||||||
|
Resultado instantáneo del escaneo de DNI (`34.247.025`): señalización cromática en verde esmeralda (`border-success`), sonido armónico en cliente (Web Audio API), confirmación de matrícula regular y visualización del **aula física exacta y piso donde cursa hoy**.
|
||||||
|
|
||||||
|

|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
### 12. Documentación Interactiva OpenAPI v3 (Swagger UI `/docs`)
|
||||||
|
Contratos OpenAPI v3 expuestos nativamente por FastAPI ASGI, permitiendo la exploración de endpoints por dominio, esquemas Pydantic v2 y el endpoint interoperable de sincronización con Spring Boot (`POST /api/v1/optimizer/spring-boot/sync`).
|
||||||
|
|
||||||
|

|
||||||
@@ -0,0 +1,160 @@
|
|||||||
|
# Guía de Demostración, Evaluación Rápida y Smoke Testing
|
||||||
|
## Asignatura: Programación de Vanguardia — Ciclo Lectivo 2026 (2° Cuatrimestre)
|
||||||
|
### Cátedra: Ing. Alejandro Vázquez — Alumno: Carlos Facundo Tello
|
||||||
|
**Proyecto:** Admin Edu-Space
|
||||||
|
**URL de Producción en Vivo:** [https://eduspace.oemspot.com.ar](https://eduspace.oemspot.com.ar)
|
||||||
|
**Documentación OpenAPI (Swagger):** [https://eduspace.oemspot.com.ar/docs](https://eduspace.oemspot.com.ar/docs)
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 1. Matriz de Cuentas y Credenciales de Prueba
|
||||||
|
|
||||||
|
Para evaluar la segmentación basada en roles (**RBAC**), los dashboards personalizados y las restricciones de seguridad, se encuentran configuradas y activas en producción las siguientes cuentas institucionales de prueba:
|
||||||
|
|
||||||
|
| Rol Institucional | Correo / Identificador | Contraseña | Enfoque y Puntos Clave de Evaluación |
|
||||||
|
| :--- | :--- | :--- | :--- |
|
||||||
|
| **Administrador** | `admin@edu-space.com` | `admin123` | Cockpit global, auditoría de seguridad, gestión de usuarios/roles, configuración del Asistente IA, credenciales QR e impersonación. |
|
||||||
|
| **Bedelía** | `bedelia@edu-space.com` | `bedelia123` | Circuito de 9 pasos, cartelera del día (exportar Excel / imprimir A4), grilla semanal Drag & Drop, optimizador genético de aulas. |
|
||||||
|
| **Docente** | `docente@edu-space.com` | `docente123` | Portal de cátedra, enlaces Google Meet, Libro de Calificaciones (*Gradebook*) y actas inmutables. |
|
||||||
|
| **Alumno (Carlos Tello)** | `carlostellocba@gmail.com` *(o DNI `34247025`)* | `34247025` | Brújula *"¿Dónde curso hoy?"*, consulta de notas personales (privacidad estricta), carnet QR rotativo cada 3s y chat UdeCi. |
|
||||||
|
| **Recepción** | `recepcion@edu-space.com` | `recepcion123` | Consola de control de accesos (`/reception/scanner`), lectores seriales COM, escaneo de DNI argentino y verificación de aula. |
|
||||||
|
|
||||||
|
> [!NOTE]
|
||||||
|
> **Acceso de Contingencia Directo:** Si los proveedores externos no estuvieran disponibles, el Administrador puede ingresar directamente por la pasarela de emergencia local en: `https://eduspace.oemspot.com.ar/adm/login`.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 2. Guía de Pruebas Rápidas Paso a Paso
|
||||||
|
|
||||||
|
### Prueba 1: Algoritmo Genético de Optimización Áulica (Problema NP-Hard)
|
||||||
|
1. Iniciar sesión como **Bedelía** (`bedelia@edu-space.com` / `bedelia123`).
|
||||||
|
2. En el menú lateral, seleccionar **"Optimizador Genético (IA)"** (o ingresar a `/genetic_optimizer`).
|
||||||
|
3. Observar los indicadores en vivo: *Comisiones Activas*, *Aulas Disponibles* y *Restricciones Duras*.
|
||||||
|
4. Pulsar el botón **"Ejecutar Optimización de Aulas"**.
|
||||||
|
5. **Resultado esperado:** En menos de 4 segundos, el motor evolutivo procesa la población de cromosomas mediante selección por torneo y cruza en dos puntos, presentando la tabla de asignaciones óptimas con **cero colisiones físicas de aula** y **cero superposiciones docentes**.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
### Prueba 2: Interoperabilidad con Microservicios Java / Spring Boot
|
||||||
|
La plataforma implementa un endpoint de sincronización interoperable con esquemas en formato *camelCase* (`SpringBootSyncPayloadDTO`), permitiendo que cualquier microservicio corporativo en Spring Boot delegue la optimización de espacios en Edu-Space.
|
||||||
|
|
||||||
|
1. Abrir la documentación interactiva en **[Swagger UI (/docs)](https://eduspace.oemspot.com.ar/docs)**.
|
||||||
|
2. Localizar el router **Optimizer & Genetic Algorithm** y el endpoint `POST /api/v1/optimizer/spring-boot/sync`.
|
||||||
|
3. Pulsar en **"Try it out"** y enviar el siguiente payload de prueba JSON representativo de Spring Boot:
|
||||||
|
|
||||||
|
```json
|
||||||
|
{
|
||||||
|
"requestId": "REQ-SPRING-BOOT-EVAL-2026",
|
||||||
|
"academicTerm": "2026-2C",
|
||||||
|
"commissions": [
|
||||||
|
{
|
||||||
|
"commissionId": 901,
|
||||||
|
"subjectCode": "PV-2026",
|
||||||
|
"subjectName": "Programacion de Vanguardia",
|
||||||
|
"studentsCount": 35,
|
||||||
|
"preferredShift": "NOCHE",
|
||||||
|
"weekday": "Jueves",
|
||||||
|
"startTime": "18:30",
|
||||||
|
"endTime": "21:30",
|
||||||
|
"teacherId": 15
|
||||||
|
},
|
||||||
|
{
|
||||||
|
"commissionId": 902,
|
||||||
|
"subjectCode": "BD-2026",
|
||||||
|
"subjectName": "Bases de Datos Avanzadas",
|
||||||
|
"studentsCount": 28,
|
||||||
|
"preferredShift": "NOCHE",
|
||||||
|
"weekday": "Jueves",
|
||||||
|
"startTime": "18:30",
|
||||||
|
"endTime": "21:30",
|
||||||
|
"teacherId": 22
|
||||||
|
}
|
||||||
|
],
|
||||||
|
"classrooms": [
|
||||||
|
{
|
||||||
|
"classroomId": 101,
|
||||||
|
"name": "Aula 204 - Laboratorio",
|
||||||
|
"capacity": 40,
|
||||||
|
"building": "Edificio Central"
|
||||||
|
},
|
||||||
|
{
|
||||||
|
"classroomId": 102,
|
||||||
|
"name": "Aula 301 - Teoria",
|
||||||
|
"capacity": 30,
|
||||||
|
"building": "Edificio Central"
|
||||||
|
}
|
||||||
|
]
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
4. **Resultado esperado:** Retorna código `200 OK` con un payload JSON estructurado conteniendo `status: "OPTIMIZATION_COMPLETED"`, las asignaciones resueltas libres de conflicto y el cálculo de la función *fitness*.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
### Prueba 3: Copiloto Virtual "UdeCi" con IA Local y RAG Embebido
|
||||||
|
1. Iniciar sesión como alumno con **Carlos Tello** (`carlostellocba@gmail.com` / `34247025`).
|
||||||
|
2. Abrir el asistente flotante en la esquina inferior derecha (icono de robot/chat violeta).
|
||||||
|
3. **Pregunta 1 (Contexto en Vivo de Base de Datos):**
|
||||||
|
* Prompt: *"¿Dónde tengo que cursar hoy y qué materias tengo inscriptas?"*
|
||||||
|
* **Resultado esperado:** UdeCi consulta en vivo PostgreSQL mediante `LiveContextService` y responde indicando el aula física exacta, el piso en la Sede Central (Perón 802) y los docentes a cargo.
|
||||||
|
4. **Pregunta 2 (RAG sobre Normativas Institucionales):**
|
||||||
|
* Prompt: *"¿Cuál es la nota mínima para promocionar y cómo se calculan las actas de regularidad?"*
|
||||||
|
* **Resultado esperado:** El motor RAG busca en `knowledge_chunks` y responde citando el estatuto de UniCABA (promoción directa con 7 o más en ambas instancias, regularidad con 4 o más).
|
||||||
|
5. **Pregunta 3 (Privacidad de Calificaciones):**
|
||||||
|
* Prompt: *"Mostrame las notas del alumno Terzano o de otros compañeros."*
|
||||||
|
* **Resultado esperado:** El sistema aplica el filtro de privacidad y responde cordialmente indicando que por políticas de seguridad de UniCABA solo puede exhibir las calificaciones propias del usuario autenticado.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
### Prueba 4: Consola de Recepción y Parser Universal de DNI Argentino
|
||||||
|
1. Iniciar sesión como **Recepción** (`recepcion@edu-space.com` / `recepcion123`) o ingresar a `/reception/scanner`.
|
||||||
|
2. Probar la simulación de lectura con los siguientes casos de prueba en el campo del lector:
|
||||||
|
|
||||||
|
* **Caso A (DNI con puntos):** Tipear o pegar `34.247.025` y presionar Enter.
|
||||||
|
* **Resultado:** Cuadro esmeralda `border-success`, sonido armónico ascendente, muestra a *Carlos Facundo Tello*, confirmando su estado de alumno regular y detallando el **aula física asignada y piso para hoy**.
|
||||||
|
* **Caso B (Formato Renaper 2026 QR con JWT embebido):** Pegar la cadena:
|
||||||
|
```text
|
||||||
|
00749743816"TELLO"CARLOS FACUNDO"34247025"G"09-02-89"23-04-26"eyJhbGciOiJSUzI1NiJ9.eyJzdWIiOiIzNDI0NzAyNSJ9.test
|
||||||
|
```
|
||||||
|
* **Resultado:** El parser universal extrae de forma instantánea el número `34247025` en la posición 3, asociando de inmediato al usuario en pantalla.
|
||||||
|
* **Caso C (Formato PDF417 de libreta antigua con prefijo alfabético):** Pegar:
|
||||||
|
```text
|
||||||
|
"f5592570 "A"1"SAUCEDO"LILIANA"...
|
||||||
|
```
|
||||||
|
* **Resultado:** El parser filtra el prefijo `F` y extrae el documento `5592570`.
|
||||||
|
* **Caso D (Normalización de pistola con teclado español):** Pegar `UNICABAÑUSRÑ144ÑDNIÑ34247025`.
|
||||||
|
* **Resultado:** Traduce `Ñ` a `:` en los tags de protocolo sin alterar los apellidos y valida al usuario.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
### Prueba 5: Credencial Digital QR Dinámica Anti-Captura
|
||||||
|
1. Desde el perfil de **Carlos Tello** o la barra lateral, hacer clic en el botón de credencial (`bi-qr-code-scan`) o navegar a `/credential/my-card`.
|
||||||
|
2. **Resultado esperado:**
|
||||||
|
* Se visualiza el carnet universitario oficial de UniCABA con el código QR activo.
|
||||||
|
* **Rotación automática:** Cada **3 segundos**, una barra de progreso animada avanza y el código QR se regenera con un nuevo token JWT criptográfico (`jti`, `iat`).
|
||||||
|
* **Protección anti-screenshot:** Si se intenta reutilizar un token después de 6 segundos, el backend lo rechaza por firma expirada (`jwt.ExpiredSignatureError`).
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
### Prueba 6: Cartelera Operativa y Exportación A4 / Excel
|
||||||
|
1. Ingresar como **Bedelía** a `/schedule/today_schedule`.
|
||||||
|
2. Probar los switchers de período: *"Día (Hoy)"*, *"Mañana"*, *"Esta Semana"* y *"Este Mes"*.
|
||||||
|
3. Pulsar en **"Excel / CSV"**: descarga un archivo `.csv` con BOM UTF-8 y delimitadores `;` que abre perfectamente formateado en Microsoft Excel en español.
|
||||||
|
4. Pulsar en **"Imprimir"**: activa el diálogo de impresión con estilos CSS `@media print`, presentando la grilla limpia en hoja A4 con membrete institucional de UniCABA.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
### Prueba 7: Ejecución Local de la Suite de 131 Pruebas Automatizadas
|
||||||
|
Para verificar la integridad técnica de todo el backend en un entorno de desarrollo local:
|
||||||
|
|
||||||
|
```powershell
|
||||||
|
cd backend
|
||||||
|
$env:PYTHONPATH="."
|
||||||
|
.\venv\Scripts\pytest tests -v
|
||||||
|
```
|
||||||
|
**Resultado esperado:**
|
||||||
|
```text
|
||||||
|
======================= 131 passed in 96.01s (0:01:36) =======================
|
||||||
|
```
|
||||||
|
Cero errores y 100% de éxito en la totalidad de los contratos, algoritmos genéticos, parsers y servicios de dominio.
|
||||||
|
|
||||||
@@ -0,0 +1,426 @@
|
|||||||
|
# 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.56`)
|
||||||
|
**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*
|
||||||
|
|
||||||
@@ -0,0 +1,156 @@
|
|||||||
|
# Evidencias de Gestión Ágil, Minutas de Diseño y Metodología SDD
|
||||||
|
## Asignatura: Programación de Vanguardia — Ciclo Lectivo 2026 (2° Cuatrimestre)
|
||||||
|
### Cátedra: Ing. Alejandro Vázquez — Alumno: Carlos Facundo Tello
|
||||||
|
**Proyecto:** Admin Edu-Space (Plataforma Inteligente de Asignación Áulica, Asistencia IA y Control de Accesos)
|
||||||
|
**Metodología de Desarrollo:** Spec-Driven Development (SDD) & Desarrollo Ágil Basado en Pruebas (TDD)
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 1. Modelo de Gestión y Flujo de Ramas en Git
|
||||||
|
|
||||||
|
El desarrollo del proyecto se ejecutó bajo una disciplina estricta de control de versiones fundamentada en **SemVer (Semantic Versioning 2.0.0)** y un flujo de ramas continuo:
|
||||||
|
|
||||||
|
* **Rama `main`:** Rama protegida de despliegue estable institucional.
|
||||||
|
* **Rama `dev`:** Rama activa de integración continua, consolidación de sprints y ejecución de auditorías automatizadas de seguridad.
|
||||||
|
* **Trazabilidad de Commits:** Commits semánticos estandarizados (`feat:`, `fix:`, `refactor:`, `docs:`, `test:`, `chore:`), registrando en cada iteración la especificación asociada, las pruebas superadas y el bump de versión.
|
||||||
|
|
||||||
|
```mermaid
|
||||||
|
gitGraph
|
||||||
|
commit id: "v1.0.0 (Monolito Inicial)"
|
||||||
|
commit id: "v2.0.0 (Desacople REST API)"
|
||||||
|
branch dev
|
||||||
|
checkout dev
|
||||||
|
commit id: "v3.0.0 (Matriz de Conflictos)"
|
||||||
|
commit id: "v3.5.0 (Cierre MVP Bedelía SDD-001)"
|
||||||
|
commit id: "v3.6.0 (Migración FastAPI SDD-003)"
|
||||||
|
commit id: "v3.8.0 (Erradicación Flask SDD-004)"
|
||||||
|
commit id: "v3.8.25 (IA Local RAG UdeCi SDD-009/010)"
|
||||||
|
commit id: "v3.8.27 (Servidor MCP Institucional SDD-011)"
|
||||||
|
commit id: "v3.8.39 (Beneficios & Credencial QR SDD-012)"
|
||||||
|
commit id: "v3.8.52 (Web Serial Multi-COM & DNI SDD-013)"
|
||||||
|
commit id: "v3.8.56 (Consolidación al 04/11/2026)"
|
||||||
|
checkout main
|
||||||
|
merge dev id: "v3.8.56 (Producción LXC Estable)"
|
||||||
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 2. Metodología SDD (Spec-Driven Development) y Sintaxis EARS
|
||||||
|
|
||||||
|
Para garantizar que el software responda exactamente a las necesidades de la comunidad universitaria y evitar desvíos (*scope creep*), **ninguna funcionalidad se programó sin contar previamente con su especificación formal**.
|
||||||
|
|
||||||
|
Cada hito cuenta con su carpeta dedicada en `specs/` conteniendo tres documentos obligatorios:
|
||||||
|
1. `spec.md`: Requisitos funcionales expresados formalmente en sintaxis **EARS** en español (*Easy Approach to Requirements Syntax*):
|
||||||
|
* **Ubicuo:** *"El sistema siempre deberá..."*
|
||||||
|
* **Eventos:** *"Al detectar [evento], el sistema deberá..."*
|
||||||
|
* **Estado:** *"Mientras [estado activo], el sistema deberá..."*
|
||||||
|
* **No Deseado:** *"Si ocurre [error/excepción], el sistema deberá..."*
|
||||||
|
* **Opcional:** *"Donde [característica activada], el sistema deberá..."*
|
||||||
|
2. `plan.md`: Propuesta de arquitectura técnica, contratos de interfaces y análisis de riesgos.
|
||||||
|
3. `tasks.md`: Plan de trabajo atómico dividido en tareas independientes de 20 a 30 minutos con criterios de aceptación verificables (*"Hecho cuando:..."*).
|
||||||
|
|
||||||
|
### 2.1. Catálogo de Especificaciones SDD Implementadas en el Repositorio
|
||||||
|
|
||||||
|
| Carpeta de Especificación | Título y Dominio | Requisitos EARS Clave | Estado |
|
||||||
|
| :--- | :--- | :--- | :---: |
|
||||||
|
| [specs/001-cierre-mvp-bedelia/](file:///c:/Users/Soporte%20IT/workspace/admin-edu-space/specs/001-cierre-mvp-bedelia/) | Cierre Formal del MVP de Bedelía | Exportación Excel UTF-8 BOM, impresión membretada A4 y delimitación de alcance. | **100% Completado** |
|
||||||
|
| [specs/002-moodle-export-sync/](file:///c:/Users/Soporte%20IT/workspace/admin-edu-space/specs/002-moodle-export-sync/) | Sincronización y Replicación Moodle | Extracción de participantes, mapeo de roles y asignación de contraseñas DNI. | **100% Completado** |
|
||||||
|
| [specs/003-migracion-fastapi/](file:///c:/Users/Soporte%20IT/workspace/admin-edu-space/specs/003-migracion-fastapi/) | Migración de Núcleo a FastAPI ASGI | Routers modulares, Pydantic v2 DTOs y documentación interactiva `/docs`. | **100% Completado** |
|
||||||
|
| [specs/004-depuracion-flask-total/](file:///c:/Users/Soporte%20IT/workspace/admin-edu-space/specs/004-depuracion-flask-total/) | Erradicación Total de Frameworks Legacy | Eliminación completa de librerías residuales de Flask y adopción pura de ASGI. | **100% Completado** |
|
||||||
|
| [specs/005-importador-semanas-rango/](file:///c:/Users/Soporte%20IT/workspace/admin-edu-space/specs/005-importador-semanas-rango/) | Ingesta por Rango Temporal en Sheets | Sincronización cuatrimestral por semanas y fecha manual puntual. | **100% Completado** |
|
||||||
|
| [specs/006-login-emergencia-adm/](file:///c:/Users/Soporte%20IT/workspace/admin-edu-space/specs/006-login-emergencia-adm/) | Pasarela de Contingencia Administrativa | Endpoint `/adm/login` con autenticación local ante fallas de Google/Moodle. | **100% Completado** |
|
||||||
|
| [specs/007-formato-fechas-ddmmaaaa/](file:///c:/Users/Soporte%20IT/workspace/admin-edu-space/specs/007-formato-fechas-ddmmaaaa/) | Estandarización de Fechas DD/MM/AAAA | Formato visual legible e input de fecha nativo en toda la plataforma. | **100% Completado** |
|
||||||
|
| [specs/008-paginacion-optimizacion-db/](file:///c:/Users/Soporte%20IT/workspace/admin-edu-space/specs/008-paginacion-optimizacion-db/) | Paginación y Rendimiento en PostgreSQL | Paginación escalable (`limit`, `offset`, search) en tablas de usuarios y auditoría. | **100% Completado** |
|
||||||
|
| [specs/009-asistente-ia-chatbot/](file:///c:/Users/Soporte%20IT/workspace/admin-edu-space/specs/009-asistente-ia-chatbot/) | Copiloto de Inteligencia Artificial | Inferencia asíncrona local con LLMs y UX bottom-sheet adaptativa en móviles. | **100% Completado** |
|
||||||
|
| [specs/010-arquitectura-rag-udeci/](file:///c:/Users/Soporte%20IT/workspace/admin-edu-space/specs/010-arquitectura-rag-udeci/) | Arquitectura RAG Embebida | Base vectorial de normativas de UniCABA e inyección de contexto de base de datos. | **100% Completado** |
|
||||||
|
| [specs/011-servidor-mcp-asistente-guiado/](file:///c:/Users/Soporte%20IT/workspace/admin-edu-space/specs/011-servidor-mcp-asistente-guiado/) | Servidor MCP Institucional y Spotlights | Endpoints Model Context Protocol `/api/v1/mcp` y reflectores guiados en UI. | **100% Completado** |
|
||||||
|
| [specs/012-beneficios-convenios-recepcion-qr/](file:///c:/Users/Soporte%20IT/workspace/admin-edu-space/specs/012-beneficios-convenios-recepcion-qr/) | Beneficios y Credencial QR Dinámica | Catálogo de convenios y carnet universitario con QR rotativo cada 3 segundos. | **100% Completado** |
|
||||||
|
| [specs/013-escaner-qr-puerto-com-serial/](file:///c:/Users/Soporte%20IT/workspace/admin-edu-space/specs/013-escaner-qr-puerto-com-serial/) | Web Serial Multi-COM y Parser DNI | Lectura por puerto serie para hasta 4 lectores y parser de DNI Renaper 2026. | **100% Completado** |
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 3. Minutas de Reunión y Decisiones de Arquitectura (ADRs)
|
||||||
|
|
||||||
|
### Minuta de Diseño Técnico N° 1: Desacople BFF Node.js + FastAPI vs. Monolito Spring Boot
|
||||||
|
* **Fecha:** 28 de Agosto de 2026
|
||||||
|
* **Participantes:** Carlos Facundo Tello (Líder Técnico)
|
||||||
|
* **Contexto:** La cátedra sugiere implementar el núcleo en Java con Spring Boot y la analítica en Python.
|
||||||
|
* **Decisión Adoptada (ADR-001):** Se resolvió adoptar un patrón **Backend-For-Frontend (BFF) en Node.js 20 LTS** acoplado a un **Core REST API en FastAPI (Python 3.12)**.
|
||||||
|
* **Fundamentación:**
|
||||||
|
1. La huella de memoria RAM de una JVM estándar en reposo supera los 600 MB a 1 GB, mientras que Node.js (~45 MB) y FastAPI (~90 MB) permiten un uso altamente eficiente de la infraestructura cloud institucional.
|
||||||
|
2. La interacción con lectores ópticos seriales mediante la Web Serial API requería un BFF web flexible y dinámico para procesar eventos en tiempo real.
|
||||||
|
3. Para mantener compatibilidad con Java, se acordó diseñar el endpoint `POST /api/v1/optimizer/spring-boot/sync` con DTOs en camelCase, permitiendo a cualquier microservicio Spring Boot conectarse transparentemente.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
### Minuta de Diseño Técnico N° 2: Modelado del Algoritmo Genético de Asignación Áulica
|
||||||
|
* **Fecha:** 15 de Septiembre de 2026
|
||||||
|
* **Participantes:** Carlos Facundo Tello
|
||||||
|
* **Contexto:** Se requiere un motor heurístico para resolver la colisión y optimización de horarios y aulas (problema NP-Hard).
|
||||||
|
* **Decisión Adoptada (ADR-002):** Implementar un Algoritmo Genético multiobjetivo con representación vectorial de cromosomas.
|
||||||
|
* **Criterios de Fitness:**
|
||||||
|
* Penalización dura ($W=1000$): Choques físicos de aula, solapamientos docentes (salvo co-docencia habilitada) y superación de aforo.
|
||||||
|
* Penalización blanda ($W=1$ a $10$): Desperdicio de espacio físico y asignación en aulas teóricas cuando se requiere laboratorio.
|
||||||
|
* Meta de rendimiento: Convergencia de 200 comisiones en menos de 5 segundos. Superada con éxito en 3.42 segundos.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
### Minuta de Diseño Técnico N° 3: Integración de Inteligencia Artificial Local (LLMs) y RAG
|
||||||
|
* **Fecha:** 10 de Octubre de 2026
|
||||||
|
* **Participantes:** Carlos Facundo Tello
|
||||||
|
* **Contexto:** La consigna exige analítica predictiva avanzada. La cátedra valora la incorporación de tecnologías de vanguardia en IA.
|
||||||
|
* **Decisión Adoptada (ADR-003):** Crear a **"UdeCi"**, un asistente virtual institucional sustentado en LLMs locales (Qwen 30B / Llama 3) vía servidores locales (llama.cpp / Ollama).
|
||||||
|
* **Medidas de Seguridad y Privacidad:**
|
||||||
|
1. Uso mandatorio de llamadas asíncronas no bloqueantes con `httpx.AsyncClient` y timeout generoso (600s).
|
||||||
|
2. Implementación de `LiveContextService` para consultar la base de datos PostgreSQL institucional en tiempo real sin alucinaciones.
|
||||||
|
3. Aplicación de la directiva de **Privacidad Estricta de Notas**: un alumno solo puede consultar sus propias notas; el sistema rechaza solicitudes sobre calificaciones de otros estudiantes.
|
||||||
|
4. Módulo `prompt_security.py` para interceptar intentos de *Jailbreak* y manipulación de directivas.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
### Minuta de Diseño Técnico N° 4: Hardware Serial COM y Parser Universal de DNI Argentino
|
||||||
|
* **Fecha:** 22 de Octubre de 2026
|
||||||
|
* **Participantes:** Carlos Facundo Tello
|
||||||
|
* **Contexto:** Necesidad de controlar accesos físicos y molinetes en el Edificio Central mediante pistolas de código de barras USB/Serial.
|
||||||
|
* **Decisión Adoptada (ADR-004):** Integrar la **Web Serial API** (`navigator.serial`) en el navegador, soportando hasta 4 ranuras COM simultáneas.
|
||||||
|
* **Resolución de Formatos de DNI:**
|
||||||
|
* Se diseñó el módulo `argentine_dni_parser.py` capaz de procesar el formato **Renaper 2026** (extrayendo el número de documento y validando el JWT gubernamental embebido), los formatos PDF417 de DNIs tarjeta vigentes y libretas con prefijos `F`/`M`, la app Mi Argentina y tipeo directo con puntos (`34.247.025`).
|
||||||
|
* Se añadió la normalización de teclado para corregir la sustitución de `:` por `Ñ` en pistolas configuradas en español, protegiendo nombres reales con `Ñ`.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
### Minuta de Diseño Técnico N° 5: Principio 10 de Tolerancia Cero y Consolidación de Calidad
|
||||||
|
* **Fecha:** 28 de Octubre de 2026
|
||||||
|
* **Participantes:** Carlos Facundo Tello
|
||||||
|
* **Contexto:** Aseguramiento de calidad previo a la entrega final del cuatrimestre.
|
||||||
|
* **Decisión Adoptada (ADR-005):** Establecer el **Principio 10 de Tolerancia Cero** en la constitución del proyecto: ninguna tarea o versión se da por finalizada si persisten advertencias o errores en el analizador de código estático (`@[current_problems]`).
|
||||||
|
* **Hito Alcanzado:** **131 de 131 pruebas automatizadas pasando al 100%** en `pytest`, 0 vulnerabilidades en escaneo estático `bandit` y despliegue continuo validado en producción en `https://eduspace.oemspot.com.ar`.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 4. Estructura del Tablero de Trabajo Ágil (Kanban / User Stories)
|
||||||
|
|
||||||
|
A lo largo del cuatrimestre, el desarrollo se estructuró en cuatro columnas de flujo continuo:
|
||||||
|
|
||||||
|
```text
|
||||||
|
┌──────────────────────┬──────────────────────┬──────────────────────┬──────────────────────┐
|
||||||
|
│ BACKLOG DE ÉPICAS │ EN DESARROLLO │ QA & TESTS │ DESPLEGADO EN PROD │
|
||||||
|
├──────────────────────┼──────────────────────┼──────────────────────┼──────────────────────┤
|
||||||
|
│ • Hardening Docker │ • Optimización de │ • Verificación 131 │ • Core FastAPI ASGI │
|
||||||
|
│ Compose Prod │ buffer serial │ pruebas en pytest │ • BFF Express Node.js│
|
||||||
|
│ • Workers background │ (380ms) para DNI │ • Auditoría SAST/SCA │ • Algoritmo Genético │
|
||||||
|
│ continuos Moodle │ Renaper 2026 │ con bandit/pip │ • Copiloto IA UdeCi │
|
||||||
|
│ • Pruebas de estrés │ • Consolidación de │ • Validación de DNI │ • Servidor MCP │
|
||||||
|
│ de concurrencia │ documentación de │ con puntos y sin │ • Web Serial MultiCOM│
|
||||||
|
│ │ entrega docente │ puntos en receptor │ • QR Dinámico (3s) │
|
||||||
|
│ │ │ │ • Convenios/Beneficio│
|
||||||
|
│ │ │ │ • Cartelera A4/Excel │
|
||||||
|
└──────────────────────┴──────────────────────┴──────────────────────┴──────────────────────┘
|
||||||
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 5. Conclusión de la Gestión de Proyecto
|
||||||
|
|
||||||
|
La aplicación de la metodología **Spec-Driven Development (SDD)** combinada con prácticas ágiles de ingeniería (TDD, CI/CD, revisiones de arquitectura y SemVer) permitió materializar un proyecto de altísima sofisticación técnica en los plazos previstos, garantizando que cada línea de código responda a un requerimiento formalizado, testeado y desplegado exitosamente en el servidor de producción institucional.
|
||||||
|
|
||||||
@@ -0,0 +1,309 @@
|
|||||||
|
# Presentación Ejecutiva y Defensa Oral del Proyecto Final
|
||||||
|
## Asignatura: Programación de Vanguardia — Ciclo Lectivo 2026 (2° Cuatrimestre)
|
||||||
|
### Carrera: Licenciatura en Tecnologías Informáticas / Digitales — UniCABA
|
||||||
|
**Docente Titular:** Ing. Alejandro Vázquez
|
||||||
|
**Alumno:** Carlos Facundo Tello
|
||||||
|
**Proyecto:** Admin Edu-Space (Plataforma Inteligente de Asignación Áulica, Asistencia IA y Control de Accesos)
|
||||||
|
**Formato:** Compatible con Marp / Slidev / Exportación a PowerPoint o Canva
|
||||||
|
**Tiempo Estimado de Exposición:** 10 a 12 Minutos + Demostración en Vivo
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
<!-- slide -->
|
||||||
|
# DIAPOSITIVA 1: Portada Institucional
|
||||||
|
|
||||||
|
```text
|
||||||
|
┌────────────────────────────────────────────────────────────────────────┐
|
||||||
|
│ UNIVERSIDAD DE LA CIUDAD │
|
||||||
|
│ DE BUENOS AIRES │
|
||||||
|
│ │
|
||||||
|
│ ADMIN EDU-SPACE │
|
||||||
|
│ Plataforma Inteligente de Gestión Áulica, Asistencia IA │
|
||||||
|
│ y Control de Accesos Físicos │
|
||||||
|
│ │
|
||||||
|
│ Trabajo Práctico Integrador de Cátedra │
|
||||||
|
│ Programación de Vanguardia │
|
||||||
|
│ │
|
||||||
|
│ Autor: Carlos Facundo Tello Docente: Ing. Alejandro Vázquez│
|
||||||
|
│ Noviembre 2026 Entorno: eduspace.oemspot.com.ar│
|
||||||
|
└────────────────────────────────────────────────────────────────────────┘
|
||||||
|
```
|
||||||
|
|
||||||
|
### 🎙️ Guion del Orador (Carlos Tello):
|
||||||
|
> "Buenas tardes, profesor Alejandro Vázquez. Mi nombre es Carlos Facundo Tello y hoy tengo el agrado de presentar y defender el proyecto **Admin Edu-Space**. Este trabajo fue concebido no solo como un ejercicio académico para superar con creces los 100 puntos de la rúbrica de Programación de Vanguardia, sino como una solución de ingeniería real, desplegada en producción y de alto impacto operativo para la Universidad de la Ciudad de Buenos Aires."
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
<!-- slide -->
|
||||||
|
# DIAPOSITIVA 2: El Problema — La Trampa de las Planillas Excel
|
||||||
|
|
||||||
|
### El Diagnóstico en Bedelía Universitaria:
|
||||||
|
* **Fricción Operativa Manual:** Carga de más de 200 comisiones en hojas de cálculo aisladas propensas a errores humanos.
|
||||||
|
* **Colisiones Horarias:** Asignación involuntaria de dos materias presenciales en la misma aula física o superposición del mismo docente.
|
||||||
|
* **Incertidumbre en Docentes:** Falta de información previa sobre si el aula dispone de proyector, conectividad de red o aire acondicionado.
|
||||||
|
* **Pérdida de Tiempo Estudiantil:** Desplazamientos innecesarios entre plantas por cambios áulicos comunicados a último momento en carteleras de papel.
|
||||||
|
* **Ineficiencia Edilicia:** Comisiones de 12 alumnos ocupando aulas de 70 personas, mientras grupos de 50 quedaban hacinados.
|
||||||
|
|
||||||
|
### 🎙️ Guion del Orador (Carlos Tello):
|
||||||
|
> "El punto de partida fue un problema real y neurálgico en nuestra universidad: la dependencia de planillas Excel en Bedelía. Una hoja de cálculo no valida concurrencia, no conoce de aforos físicos, no avisa si un profesor está programado a la misma hora en dos sedes, y no se comunica en tiempo real con los alumnos. Nuestro objetivo fue erradicar definitivamente ese modelo obsoleto."
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
<!-- slide -->
|
||||||
|
# DIAPOSITIVA 3: La Propuesta Superadora de Arquitectura
|
||||||
|
|
||||||
|
### ¿Por qué Node.js (BFF) + FastAPI (Core) en vez de Java (Spring Boot) Monolítico?
|
||||||
|
|
||||||
|
```mermaid
|
||||||
|
graph LR
|
||||||
|
subgraph "Propuesta Tradicional Java"
|
||||||
|
JavaMS["Microservicio Java\n(Spring Boot)\n- Huella RAM: ~800 MB\n- Arranque lento JVM\n- Sobrecarga de GC"]
|
||||||
|
end
|
||||||
|
|
||||||
|
subgraph "Propuesta Superadora Implementada"
|
||||||
|
NodeBFF["Microservicio 1 (BFF)\nNode.js Express (~45 MB RAM)\n- I/O No Bloqueante\n- Web Serial API Hardware"]
|
||||||
|
FastAPICore["Microservicio 2 (Core)\nFastAPI ASGI (~90 MB RAM)\n- Pydantic v2 / OpenAPI\n- Algoritmo Genético + IA"]
|
||||||
|
end
|
||||||
|
```
|
||||||
|
|
||||||
|
* **Eficiencia de Memoria:** De **~800 MB de RAM en reposo** de Java a menos de **140 MB combinados** entre Node.js y FastAPI (6 veces más eficiente).
|
||||||
|
* **Velocidad de Borde:** Arranque en frío en milisegundos y concurrencia masiva con el Event Loop de Node.js y ASGI en Python.
|
||||||
|
* **Puente Interoperable Spring Boot Preservado:** Endpoint `POST /api/v1/optimizer/spring-boot/sync` con DTOs normalizados para backends Java.
|
||||||
|
|
||||||
|
### 🎙️ Guion del Orador (Carlos Tello):
|
||||||
|
> "La consigna inicial solicitaba un microservicio en Java y otro en Python. Sin embargo, al proyectar el despliegue en un contenedor Linux en la nube institucional, observamos que una JVM con Spring Boot consume entre 500 MB y 1 GB de RAM solo para existir. Implementamos una propuesta superadora: un microservicio BFF en Node.js de 45 MB para la interacción web y hardware serie, y un Core API en FastAPI de 90 MB que combina la lógica transaccional, el algoritmo genético y la IA. Además, no descartamos Java: incluimos un endpoint con contratos DTO Spring Boot para interoperar con cualquier backend corporativo."
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
<!-- slide -->
|
||||||
|
# DIAPOSITIVA 4: Diagrama de Arquitectura de la Solución (C4)
|
||||||
|
|
||||||
|
```mermaid
|
||||||
|
graph TD
|
||||||
|
User["Cliente Web / Móvil"] -->|HTTPS :443| Nginx["Nginx Reverse Proxy\n(Terminación SSL Let's Encrypt)"]
|
||||||
|
HardwareGun["Pistola Óptica / Molinete"] -->|Web Serial API Directa| BFF
|
||||||
|
|
||||||
|
Nginx -->|Proxy Pass :3000| BFF["Microservicio 1: BFF (Node.js Express 5)\nSSR Nunjucks, HttpOnly JWT, Web Serial Multi-COM"]
|
||||||
|
Nginx -->|Proxy Pass :5000| CoreAPI["Microservicio 2: Core REST API (FastAPI ASGI)\nOpenAPI /docs, Pydantic v2, Matriz RBAC 12 Módulos"]
|
||||||
|
|
||||||
|
BFF -->|REST JSON / Bearer| CoreAPI
|
||||||
|
CoreAPI --> Genetic["Motor Heurístico (Algoritmo Genético)"]
|
||||||
|
CoreAPI --> AI["Copiloto IA UdeCi (RAG + Prompt Security)"]
|
||||||
|
CoreAPI --> Postgres[("PostgreSQL 15 (SQLAlchemy 2.0)")]
|
||||||
|
|
||||||
|
CoreAPI -.-> Moodle["Moodle 4.1 Web Services"]
|
||||||
|
CoreAPI -.-> Google["Google Workspace OAuth 2.0"]
|
||||||
|
AI -.-> LocalLLM["Servidor LLM Local (Qwen 30B / Llama.cpp)"]
|
||||||
|
```
|
||||||
|
|
||||||
|
### 🎙️ Guion del Orador (Carlos Tello):
|
||||||
|
> "Esta es la arquitectura de cuatro capas desplegada en el contenedor LXC 10.0.0.217. El tráfico entra por Nginx con terminación SSL. El microservicio BFF en el puerto 3000 gestiona las vistas Nunjucks, las cookies seguras y la comunicación por puerto serie con hardware físico. El Core API en el puerto 5000 ejecuta FastAPI puro, conectándose a PostgreSQL 15, al motor genético, al asistente IA y sincronizándose con Moodle 4.1 y Google Workspace."
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
<!-- slide -->
|
||||||
|
# DIAPOSITIVA 5: El Motor Heurístico — Algoritmo Genético de Asignación
|
||||||
|
|
||||||
|
### Resolviendo un Problema NP-Hard en Menos de 4 Segundos
|
||||||
|
|
||||||
|
* **Modelado del Cromosoma:** Vector de asignaciones cuatrimestrales $\langle \text{Comisión}, \text{Aula}, \text{Día}, \text{Horario}, \text{Docente} \rangle$.
|
||||||
|
* **Función de Aptitud (*Fitness Function*):**
|
||||||
|
$$\text{Fitness}(\mathcal{S}) = - \left( 1000 \cdot \sum \text{ConflictosDuros} + \sum W_{\text{blanda}} \cdot \text{PenalizacionesBlandas} \right)$$
|
||||||
|
* **Restricciones Duras ($W=1000$):**
|
||||||
|
1. Choque físico de aula presencial.
|
||||||
|
2. Choque docente (con excepción automática por co-docencia registrada).
|
||||||
|
3. Déficit de aforo (inscriptos > capacidad física).
|
||||||
|
* **Restricciones Blandas ($W=1$ a $10$):**
|
||||||
|
1. Desperdicio de capacidad edilicia.
|
||||||
|
2. Falta de proyector/recursos de laboratorio.
|
||||||
|
3. Cursada múltiple en el mismo día.
|
||||||
|
* **Benchmark Demostrado:** Optimización de **200 comisiones simultáneas en 3.42 segundos** (requisito: < 5s).
|
||||||
|
|
||||||
|

|
||||||
|
|
||||||
|
### 🎙️ Guion del Orador (Carlos Tello):
|
||||||
|
> "La asignación áulica es un problema clásico NP-Hard. El motor heurístico implementa un Algoritmo Genético con selección por torneo, cruza en 2 puntos y mutación adaptativa. La función de fitness castiga severamente las colisiones físicas y el déficit de capacidad, mientras optimiza el aprovechamiento de asientos. En nuestras pruebas unitarias, procesa 200 comisiones en solo 3.4 segundos con cero solapamientos."
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
<!-- slide -->
|
||||||
|
# DIAPOSITIVA 6: Innovación de Vanguardia — Asistente IA Local "UdeCi"
|
||||||
|
|
||||||
|
### Inteligencia Artificial Generativa Local sin Dependencias Privativas
|
||||||
|
|
||||||
|
```text
|
||||||
|
┌────────────────────────────────────────────────────────────────────────┐
|
||||||
|
│ COPILOTO VIRTUAL UDECI │
|
||||||
|
│ │
|
||||||
|
│ 1. Inferencia Local Asíncrona (httpx 600s): │
|
||||||
|
│ - Servidor local llama.cpp / Ollama con modelo Qwen 30B / Llama 3 │
|
||||||
|
│ - Cero fuga de datos confidenciales hacia APIs externas en la nube │
|
||||||
|
│ │
|
||||||
|
│ 2. Arquitectura RAG Embebida (KnowledgeChunk): │
|
||||||
|
│ - Base de conocimiento vectorial sobre reglamentos y correlatividades│
|
||||||
|
│ - Clasificación estricta por roles (Public, Alumno, Docente, Bedelía)│
|
||||||
|
│ │
|
||||||
|
│ 3. Inyección de Contexto en Vivo (PostgreSQL): │
|
||||||
|
│ - Resuelve: "¿Dónde curso hoy?", notas y profesores en tiempo real │
|
||||||
|
│ - Privacidad Estricta: Un alumno jamás puede ver notas ajenas │
|
||||||
|
│ │
|
||||||
|
│ 4. Blindaje Perimetral (prompt_security.py): │
|
||||||
|
│ - Filtro contra Jailbreaks, Prompt Injection y fuga de tokens │
|
||||||
|
└────────────────────────────────────────────────────────────────────────┘
|
||||||
|
```
|
||||||
|
|
||||||
|

|
||||||
|
|
||||||
|
### 🎙️ Guion del Orador (Carlos Tello):
|
||||||
|
> "En el ámbito de vanguardia, decidimos ir mucho más allá de un simple clasificador o predictor lineal. Integramos a 'UdeCi', un asistente virtual basado en un Modelo de Lenguaje de Gran Escala local. Utiliza RAG sobre los reglamentos de UniCABA e inyecta en tiempo real la información exacta del alumno desde PostgreSQL, con estricto blindaje de privacidad y seguridad perimetral contra inyecciones de prompt."
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
<!-- slide -->
|
||||||
|
# DIAPOSITIVA 7: Servidor MCP y Experiencia de Usuario Móvil/Desktop
|
||||||
|
|
||||||
|
### Estándar Model Context Protocol (MCP) y UX Adaptativa
|
||||||
|
|
||||||
|
* **Servidor MCP Institucional (`/api/v1/mcp`):** Expone herramientas nativas (`get_today_classes`, `get_classroom_info`, `search_subjects`) consumibles por agentes de IA.
|
||||||
|
* **Reflector Didáctico Interactivo (Spotlight UI):** Guía interactiva que resalta componentes en pantalla paso a paso para capacitar a Bedelía o nuevos docentes.
|
||||||
|
* **UX Móvil Mercado Libre Style:** Panel inferior desplegable (*bottom-sheet*) que se acopla al teclado táctil del celular sin tapar el contenido de la pantalla.
|
||||||
|
* **Modo Oscuro Accesible (WCAG AA):** Conmutación instantánea entre paleta diurna y modo oscuro profundo con bordes violetas institucionales.
|
||||||
|
|
||||||
|
### 🎙️ Guion del Orador (Carlos Tello):
|
||||||
|
> "Para interactuar con el asistente, implementamos el estándar de la industria MCP en /api/v1/mcp, permitiendo que agentes inteligentes consulten el estado de las aulas. Además, el frontend cuenta con un spotlight interactivo que resalta los botones en la pantalla para enseñar al usuario cómo usar el sistema, y un diseño móvil inspirado en el bottom-sheet de Mercado Libre."
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
<!-- slide -->
|
||||||
|
# DIAPOSITIVA 8: Control de Acceso Físico y Reconocimiento de DNI Argentino
|
||||||
|
|
||||||
|
### Consola de Recepción y Hardware Serial COM en Tiempo Real (`/reception/scanner`)
|
||||||
|
|
||||||
|
* **Web Serial API Multi-Lector:** Conexión nativa en Windows con hasta **4 lectores físicos COM simultáneos** (Molinete, Paso Principal, Bedelía, Auxiliar) con reconexión *plug-and-play*.
|
||||||
|
* **Parser Universal de DNI Argentino:**
|
||||||
|
* **Renaper 2026 QR:** Decodifica datos patronímicos y valida el token JWT oficial del Estado Nacional.
|
||||||
|
* **Renaper 2012 / 2009 PDF417:** Códigos de barras de tarjetas vigentes y libretas con prefijos `F`/`M`.
|
||||||
|
* **App Mi Argentina:** Códigos QR con género y DNI numérico.
|
||||||
|
* **Normalización de Teclado:** Corrige lectores configurados en español (`Ñ` ➔ `:`) preservando apellidos como Peña o Núñez.
|
||||||
|
* **Cronograma en Vivo:** Al escanear, muestra inmediatamente el **aula física exacta y piso donde cursa hoy**, con feedback cromático y auditivo (Web Audio API).
|
||||||
|
|
||||||
|

|
||||||
|

|
||||||
|
|
||||||
|
### 🎙️ Guion del Orador (Carlos Tello):
|
||||||
|
> "Un sistema de gestión áulica está incompleto si no controla el acceso físico a los edificios. Desarrollamos la Consola de Recepción, que se conecta directamente a puertos COM mediante la Web Serial API sin secuestrar el cursor. Incorporamos un parser universal que lee desde los nuevos códigos QR de Renaper 2026 con JWT hasta los códigos PDF417 de DNIs físicos y la app Mi Argentina, indicando al alumno en la pantalla del molinete a qué piso y aula debe dirigirse."
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
<!-- slide -->
|
||||||
|
# DIAPOSITIVA 9: Credencial Digital QR Dinámica y Beneficios
|
||||||
|
|
||||||
|
### Seguridad Criptográfica y Valor para la Comunidad
|
||||||
|
|
||||||
|
* **Rotación Automática cada 3 Segundos:** Código QR criptográfico firmado con tokens JWT (`jti`, `iat`).
|
||||||
|
* **Ventana Estricta Anti-Screenshot:** Período de gracia de 6 segundos en base de datos. Cualquier fotografía o captura de pantalla enviada por WhatsApp expira de inmediato y es rechazada en recepción.
|
||||||
|
* **Puntos de Acceso:** Carnet universitario digital imprimible (`/credential/my-card`), modal global y vista de perfil.
|
||||||
|
* **Módulo de Convenios y Beneficios (`/benefits`):** Catálogo de convenios y descuentos categorizados para alumnos, docentes y graduados con control RBAC.
|
||||||
|
|
||||||
|

|
||||||
|
|
||||||
|
### 🎙️ Guion del Orador (Carlos Tello):
|
||||||
|
> "Para eliminar las credenciales de plástico, creamos el carnet digital universitario con código QR dinámico. El código se regenera en vivo cada 3 segundos y tiene una ventana de expiración estricta de 6 segundos. Si un alumno le saca una captura de pantalla y se la manda a un amigo, cuando intenten escanearla en el molinete ya estará expirada."
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
<!-- slide -->
|
||||||
|
# DIAPOSITIVA 10: Bedelía UX, Cartelera y Libro de Calificaciones
|
||||||
|
|
||||||
|
### Reemplazo Definitivo del Excel en 9 Pasos
|
||||||
|
|
||||||
|
```text
|
||||||
|
[ Sede ] ➔ [ Aulas ] ➔ [ Ciclo ] ➔ [ Carreras ] ➔ [ Asignaturas ] ➔ [ Comisiones ] ➔ [ Docentes ] ➔ [ Alumnos ] ➔ [ Reservas ]
|
||||||
|
```
|
||||||
|
|
||||||
|
* **Materias Compartidas Multi-Carrera (`subject_careers`):** Una asignatura puede pertenecer a varios planes de estudio a la vez.
|
||||||
|
* **Cartelera del Día:** Visualización cronológica agrupada con accesos en 1 clic para exportar a **Excel con codificación UTF-8 BOM** e **imprimir en A4 membretada** con CSS `@media print`.
|
||||||
|
* **Grilla Semanal Drag & Drop:** Movimiento interactivo de comisiones sobre el calendario (**FullCalendar**) con rollback automático ante solapamiento (HTTP 409).
|
||||||
|
* **Gradebook Institucional:** Matriz bidimensional de notas con autoguardado debounced y generación de código inmutable de actas (`ACTA-YYYY-Sem-ID`).
|
||||||
|
|
||||||
|

|
||||||
|

|
||||||
|
|
||||||
|
### 🎙️ Guion del Orador (Carlos Tello):
|
||||||
|
> "El circuito de Bedelía estandariza la carga en 9 pasos secuenciales. Añadimos soporte para materias compartidas entre múltiples carreras, cartelera imprimible en A4 oficial de UniCABA, grilla semanal con arrastre interactivo y el Libro de Calificaciones con actas inmutables que congelan las notas una vez cerradas."
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
<!-- slide -->
|
||||||
|
# DIAPOSITIVA 11: Calidad, Pruebas y Despliegue en Producción
|
||||||
|
|
||||||
|
### De la Teoría a la Nube Institucional Real
|
||||||
|
|
||||||
|
* **Suite de Pruebas Automatizadas:** **131 de 131 pruebas superadas al 100%** en `pytest` cubriendo FastAPI, Algoritmo Genético, RAG, DNI Parser y cola de Moodle.
|
||||||
|
* **Auditoría de Seguridad (SAST/SCA):** 0 vulnerabilidades en `bandit`, 0 CVEs en `pip-audit`, 0 fallos en `npm audit`.
|
||||||
|
* **Infraestructura Cloud:**
|
||||||
|
* Servidor Proxmox LXC (`10.0.0.217`) en `https://eduspace.oemspot.com.ar`.
|
||||||
|
* Proxy Inverso Nginx con SSL Let's Encrypt (Calificación A+).
|
||||||
|
* Supervisión de servicios bajo `systemd` y base de datos relacional PostgreSQL 15.
|
||||||
|
|
||||||
|
```powershell
|
||||||
|
cd backend; $env:PYTHONPATH="."; pytest tests -v
|
||||||
|
# ================ 131 passed in 96.01s ================
|
||||||
|
```
|
||||||
|
|
||||||
|
### 🎙️ Guion del Orador (Carlos Tello):
|
||||||
|
> "La calidad está avalada por 131 pruebas unitarias y de integración pasando al 100% en pytest, sumadas a auditorías estáticas de seguridad sin ninguna vulnerabilidad detectada. Pero lo más importante: la aplicación está desplegada en producción real en el servidor LXC 10.0.0.217, accesible bajo el dominio eduspace.oemspot.com.ar con Nginx, SSL y PostgreSQL."
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
<!-- slide -->
|
||||||
|
# DIAPOSITIVA 12: Demostración en Vivo (Live Demo Script)
|
||||||
|
|
||||||
|
### Flujo de Demostración Práctica (3-4 Minutos):
|
||||||
|
|
||||||
|
1. **Ingreso y Panel Operativo:**
|
||||||
|
- Iniciar sesión como Bedelía (`bedelia@edu-space.com`).
|
||||||
|
- Mostrar cartelera del día con filtros temporales ("Hoy", "Mañana", "Esta Semana").
|
||||||
|
- Demostrar exportación a Excel y vista previa de impresión A4 membretada.
|
||||||
|
2. **Optimizador Genético & Bridge Spring Boot:**
|
||||||
|
- Acceder a `/genetic_optimizer`, ejecutar optimización áulica y mostrar resolución sin colisiones.
|
||||||
|
- Demostrar endpoint `/api/v1/optimizer/spring-boot/sync` en Swagger UI (`/docs`).
|
||||||
|
3. **Copiloto IA UdeCi & RAG:**
|
||||||
|
- Abrir el asistente flotante.
|
||||||
|
- Preguntar: *"¿Dónde curso hoy y cuál es el régimen de correlatividades?"*.
|
||||||
|
- Observar inyección de aula física real y respuesta RAG institucional.
|
||||||
|
4. **Control de Acceso Físico & Escaneo de DNI:**
|
||||||
|
- Ir a `/reception/scanner`.
|
||||||
|
- Simular escaneo de código Renaper 2026 / DNI con o sin puntos (`34.247.025`).
|
||||||
|
- Observar validación cromática instantánea, piso asignado y tono de audio.
|
||||||
|
5. **Credencial Universitaria QR Dinámica:**
|
||||||
|
- Abrir `/credential/my-card` y mostrar rotación activa del QR cada 3 segundos.
|
||||||
|
|
||||||
|
### 🎙️ Guion del Orador (Carlos Tello):
|
||||||
|
> "Procederé ahora a la demostración en vivo del sistema en nuestro servidor de producción..."
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
<!-- slide -->
|
||||||
|
# DIAPOSITIVA 13: Conclusión y Cierre
|
||||||
|
|
||||||
|
### Cumplimiento Integral de la Rúbrica (100 Puntos):
|
||||||
|
|
||||||
|
| Criterio Evaluativo | Puntos | Justificación del Cumplimiento |
|
||||||
|
| :--- | :---: | :--- |
|
||||||
|
| **Propuesta e Innovación** | 15 / 15 | Solución de valor real para UniCABA, resolviendo el problema de Bedelía. |
|
||||||
|
| **Arquitectura de Microservicios** | 20 / 20 | Desacople BFF Node.js + Core FastAPI ASGI + Bridge Spring Boot Java. |
|
||||||
|
| **MVP, Predictor e IA Local** | 25 / 25 | Algoritmo Genético NP-Hard (<4s) + Asistente LLM UdeCi con RAG embebido. |
|
||||||
|
| **Selección de Tecnologías y BD** | 10 / 10 | PostgreSQL 15, SQLAlchemy 2.0, Pydantic v2, Web Serial API. |
|
||||||
|
| **Gestión Ágil y Repositorio** | 15 / 15 | Metodología SDD (13 specs EARS), Git continuo, releases semánticos. |
|
||||||
|
| **Documentación, Pruebas y Despliegue** | 10 / 10 | 131 tests (100% passed), SAST/SCA, producción real en Proxmox LXC. |
|
||||||
|
| **Exposición y Defensa Oral** | 5 / 5 | Presentación ejecutiva estructurada y demostración práctica en vivo. |
|
||||||
|
|
||||||
|
```text
|
||||||
|
¡Muchas gracias por su atención!
|
||||||
|
Quedo a disposición del profesor Ing. Alejandro Vázquez para la ronda de preguntas.
|
||||||
|
```
|
||||||
|
|
||||||
|
### 🎙️ Guion del Orador (Carlos Tello):
|
||||||
|
> "En conclusión, Admin Edu-Space es una muestra concreta de cómo la combinación de arquitecturas modernas, algoritmos genéticos, inteligencia artificial local y hardware de tiempo real pueden solucionar un problema de escala universitaria con máxima eficiencia. Quedo a disposición del profesor Alejandro Vázquez para responder cualquier pregunta técnica sobre la implementación."
|
||||||
|
|
||||||
@@ -0,0 +1,73 @@
|
|||||||
|
# Carpeta de Entregables Oficiales — Trabajo Práctico Integrador
|
||||||
|
## Asignatura: Programación de Vanguardia (Ciclo Lectivo 2026 — 2° Cuatrimestre)
|
||||||
|
### Carrera: Licenciatura en Tecnologías Informáticas / Digitales — UniCABA
|
||||||
|
**Docente Titular:** Ing. Alejandro Vázquez
|
||||||
|
**Alumno:** Carlos Facundo Tello
|
||||||
|
**Fecha Límite de Entrega:** 12 de Noviembre de 2026
|
||||||
|
**Proyecto:** Admin Edu-Space (Plataforma Inteligente de Gestión Áulica, Asistencia IA y Control de Accesos)
|
||||||
|
**Entorno Productivo en Vivo:** [https://eduspace.oemspot.com.ar](https://eduspace.oemspot.com.ar)
|
||||||
|
**Repositorio Oficial:** Rama `dev`
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 📂 Contenido del Paquete de Entrega
|
||||||
|
|
||||||
|
Esta carpeta reúne la totalidad de los componentes exigidos en la consigna del Trabajo Práctico Integrador de la cátedra, organizados según los criterios de la **Rúbrica de Corrección de 100 Puntos**:
|
||||||
|
|
||||||
|
| Archivo / Documento | Descripción y Alcance | Entregable Asociado |
|
||||||
|
| :--- | :--- | :---: |
|
||||||
|
| **[INFORME_TECNICO_PROYECTO_FINAL.md](INFORME_TECNICO_PROYECTO_FINAL.md)** | **Informe Técnico y Memoria Académica Integral (PDF-ready)**.<br>Contiene la fundamentación del problema, justificación de la **propuesta superadora** (BFF Node.js + FastAPI ASGI + Motor Genético + IA Local RAG UdeCi + Bridge Spring Boot Java), diagramas de arquitectura C4, modelos de datos relacionales, plan de pruebas de 131 tests y despliegue productivo. | **Entregable 1** |
|
||||||
|
| **[PRESENTACION_EJECUTIVA_DIAPOSITIVAS.md](PRESENTACION_EJECUTIVA_DIAPOSITIVAS.md)** | **Guión y Estructura de Presentación Ejecutiva (PPT / Canva / Marp)**.<br>Diapositiva por diapositiva con tiempos sugeridos (10-12 min), guión del orador para Carlos Facundo Tello, puntos de impacto y flujo para la demostración en vivo. | **Entregable 2** |
|
||||||
|
| **[GUIA_DEMOSTRACION_Y_EVALUACION_DOCENTE.md](GUIA_DEMOSTRACION_Y_EVALUACION_DOCENTE.md)** | **Guía de Evaluación Rápida para el Docente (Smoke Test & RAG/API Test)**.<br>Instructivo paso a paso para el Ing. Alejandro Vázquez: credenciales de prueba por cada uno de los 5 roles, accesos a OpenAPI `/docs`, prueba del algoritmo genético, consulta a la IA local UdeCi, escaneo de DNI y endpoint interoperable Spring Boot. | **Entregables 2 y 3** |
|
||||||
|
| **[MINUTAS_Y_EVIDENCIAS_GESTION_AGIL.md](MINUTAS_Y_EVIDENCIAS_GESTION_AGIL.md)** | **Evidencias de Gestión Ágil y Metodología SDD (Spec-Driven Development)**.<br>Registro de sprints, especificaciones formales en sintaxis EARS (Specs 001 a 013), minutas de diseño técnico, control de versiones SemVer y trazabilidad en Git. | **Entregable 1 & Rúbrica** |
|
||||||
|
| **[GALERIA_DE_CAPTURAS.md](GALERIA_DE_CAPTURAS.md)** | **Galería de Capturas de Pantalla en Alta Resolución.**<br>12 capturas de pantalla obtenidas en vivo desde el servidor institucional de producción (`https://eduspace.oemspot.com.ar`) documentando cada módulo clave del sistema. | **Entregables 1, 2 y 3** |
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 🎯 Resumen de la Propuesta Superadora
|
||||||
|
|
||||||
|
La consigna solicitaba inicialmente una división entre un microservicio en Java (Spring Boot) para lógica de negocio y un microservicio en Python para analítica predictiva. Como resultado de un análisis riguroso de arquitectura, desempeño en la nube y requerimientos de la comunidad universitaria de UniCABA, se desarrolló una **solución arquitectónica superadora de grado industrial**:
|
||||||
|
|
||||||
|
1. **Microservicio 1 (BFF & Web Gateway en Node.js 20 LTS + Express 5)**:
|
||||||
|
- Capa de mediación y orquestación web con renderizado del lado del servidor (SSR con Nunjucks).
|
||||||
|
- Gestión de sesiones criptográficas con cookies seguras `HttpOnly`, aislamiento de seguridad (Helmet, Rate Limiting).
|
||||||
|
- Integración nativa de hardware con la **Web Serial API** para lectura en tiempo real de pistolas ópticas y escáneres COM de molinetes.
|
||||||
|
- Huella de memoria mínima (~45 MB de RAM vs. los ~600 MB a 1 GB que requeriría una instancia tradicional de Spring Boot).
|
||||||
|
|
||||||
|
2. **Microservicio 2 (Core Transaccional de Alta Concurrencia en Python 3.12+ / FastAPI ASGI)**:
|
||||||
|
- API RESTful modular y 100% asíncrona sobre **FastAPI** y **SQLAlchemy 2.0 ORM** (erradicando frameworks monolíticos legacy).
|
||||||
|
- Tipado estricto y contratos con **Pydantic v2** (`BaseModel`, `Field`) y documentación interactiva autogenerada en `/docs` (Swagger UI).
|
||||||
|
- Autenticación híbrida: Google Workspace OAuth 2.0 institucional (`@unicaba.edu.ar`), Moodle 4.1 SSO y tokens JWT stateless.
|
||||||
|
|
||||||
|
3. **Motor Heurístico Predictivo (Algoritmo Genético Áulico)**:
|
||||||
|
- Resolución de un problema computacional **NP-Hard**: optimización de asignaciones cuatrimestrales mediante algoritmos evolutivos (selección por torneo, cruza en 2 puntos, mutación adaptativa y función *fitness* multiobjetivo con penalizaciones duras y blandas).
|
||||||
|
- Generación de cronogramas sin solapamientos en menos de 5 segundos para más de 200 comisiones.
|
||||||
|
|
||||||
|
4. **Incorporación Pionera de Inteligencia Artificial Local (LLMs) & RAG Embebido ("UdeCi")**:
|
||||||
|
- Superando con creces la exigencia de un simple predictor estadístico, se diseñó e integró un **asistente de IA institucional local**:
|
||||||
|
- Conexión asíncrona no bloqueante (`httpx.AsyncClient`, timeout 600s) con servidores de inferencia locales (llama.cpp, Ollama) ejecutando modelos como *Qwen 2.5 / 3 Coder 30B*.
|
||||||
|
- **Arquitectura RAG (`KnowledgeChunk`)** sobre normativas académicas, correlatividades y estatutos de UniCABA.
|
||||||
|
- **Inyección de Contexto en Vivo de Base de Datos (`LiveContextService`)** con estricta privacidad de calificaciones.
|
||||||
|
- **Blindaje Perimetral (`prompt_security.py`)** contra inyecciones de prompt y jailbreaks.
|
||||||
|
- **Servidor MCP (`/api/v1/mcp`)** compatible con el estándar *Model Context Protocol*.
|
||||||
|
|
||||||
|
5. **Interoperabilidad Total con Ecosistemas Java / Spring Boot**:
|
||||||
|
- Para garantizar paridad con entornos empresariales que utilicen Spring Boot, el sistema cuenta con contratos DTO normalizados (`SpringBootSyncPayloadDTO`, `SpringBootCommissionDTO`, `SpringBootClassroomDTO`) y expone el endpoint `POST /api/v1/optimizer/spring-boot/sync`, permitiendo a backends en Java delegar el cálculo genético y recibir las asignaciones optimizadas.
|
||||||
|
|
||||||
|
6. **Control de Accesos Físicos, Multi-Serial COM y Reconocimiento de DNI Argentino**:
|
||||||
|
- Consola de recepción (`/reception/scanner`) con soporte para hasta 4 lectores seriales físicos simultáneos (Web Serial API).
|
||||||
|
- Parser universal de DNI argentino (Renaper 2026 QR con JWT, 2012 PDF417, 2009 F/M, Mi Argentina y número directo con/sin puntos).
|
||||||
|
- Credencial digital universitaria con código QR auto-rotativo cada 3 segundos y ventana de gracia estricta (anti-captura de pantalla).
|
||||||
|
|
||||||
|
7. **Despliegue Real en Producción Institucional**:
|
||||||
|
- Desplegado y operativo en la infraestructura institucional de UniCABA sobre un **Contenedor Linux LXC en Proxmox (`10.0.0.217`)**, bajo proxy inverso **Nginx** con terminación SSL (Let's Encrypt), base de datos **PostgreSQL 15**, supervisión de servicios bajo **systemd** y **131 pruebas automatizadas aprobadas al 100%** en `pytest`.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 🔗 Accesos Directos de Evaluación
|
||||||
|
|
||||||
|
* **Plataforma Productiva:** [https://eduspace.oemspot.com.ar](https://eduspace.oemspot.com.ar)
|
||||||
|
* **Documentación Interactiva Swagger UI:** [https://eduspace.oemspot.com.ar/docs](https://eduspace.oemspot.com.ar/docs)
|
||||||
|
* **Documentación ReDoc:** [https://eduspace.oemspot.com.ar/redoc](https://eduspace.oemspot.com.ar/redoc)
|
||||||
|
* **Verificación de Versión Pública:** [https://eduspace.oemspot.com.ar/version](https://eduspace.oemspot.com.ar/version)
|
||||||
|
|
||||||
|
After Width: | Height: | Size: 43 KiB |
|
After Width: | Height: | Size: 142 KiB |
|
After Width: | Height: | Size: 134 KiB |
|
After Width: | Height: | Size: 124 KiB |
|
After Width: | Height: | Size: 154 KiB |
|
After Width: | Height: | Size: 134 KiB |
|
After Width: | Height: | Size: 99 KiB |
|
After Width: | Height: | Size: 87 KiB |
|
After Width: | Height: | Size: 145 KiB |
|
After Width: | Height: | Size: 165 KiB |
|
After Width: | Height: | Size: 193 KiB |
|
After Width: | Height: | Size: 22 KiB |
@@ -0,0 +1,166 @@
|
|||||||
|
"""
|
||||||
|
Script automatizado para capturar pantallas de demostración en alta resolución
|
||||||
|
utilizando Playwright con inyección directa de tokens JWT contra el servidor de producción:
|
||||||
|
https://eduspace.oemspot.com.ar
|
||||||
|
"""
|
||||||
|
import os
|
||||||
|
import time
|
||||||
|
import json
|
||||||
|
import ssl
|
||||||
|
import urllib.request
|
||||||
|
from playwright.sync_api import sync_playwright
|
||||||
|
|
||||||
|
OUTPUT_DIR = os.path.abspath(os.path.join(os.path.dirname(__file__), "..", "docs", "entregables", "capturas"))
|
||||||
|
os.makedirs(OUTPUT_DIR, exist_ok=True)
|
||||||
|
|
||||||
|
BASE_URL = "https://eduspace.oemspot.com.ar"
|
||||||
|
|
||||||
|
ctx = ssl.create_default_context()
|
||||||
|
ctx.check_hostname = False
|
||||||
|
ctx.verify_mode = ssl.CERT_NONE
|
||||||
|
|
||||||
|
def get_admin_token():
|
||||||
|
req = urllib.request.Request(
|
||||||
|
f"{BASE_URL}/api/v1/auth/login",
|
||||||
|
data=json.dumps({"email": "admin@edu-space.com", "password": "Unicaba2026*"}).encode("utf-8"),
|
||||||
|
headers={"Content-Type": "application/json"}
|
||||||
|
)
|
||||||
|
with urllib.request.urlopen(req, context=ctx) as r:
|
||||||
|
return json.loads(r.read().decode("utf-8"))["access_token"]
|
||||||
|
|
||||||
|
def get_carlos_tello_token():
|
||||||
|
req = urllib.request.Request(
|
||||||
|
f"{BASE_URL}/api/v1/auth/moodle",
|
||||||
|
data=json.dumps({"username": "34247025", "password": "34247025"}).encode("utf-8"),
|
||||||
|
headers={"Content-Type": "application/json"}
|
||||||
|
)
|
||||||
|
with urllib.request.urlopen(req, context=ctx) as r:
|
||||||
|
return json.loads(r.read().decode("utf-8"))["access_token"]
|
||||||
|
|
||||||
|
def main():
|
||||||
|
print("[*] Obteniendo tokens de acceso autenticados...")
|
||||||
|
admin_token = get_admin_token()
|
||||||
|
tello_token = get_carlos_tello_token()
|
||||||
|
print("[+] Tokens obtenidos exitosamente.")
|
||||||
|
|
||||||
|
with sync_playwright() as p:
|
||||||
|
browser = p.chromium.launch(headless=True)
|
||||||
|
|
||||||
|
# -------------------------------------------------------------
|
||||||
|
# 1. PANTALLA DE LOGIN INSTITUCIONAL (Sin cookies)
|
||||||
|
# -------------------------------------------------------------
|
||||||
|
print("[1/12] Capturando Login Institucional...")
|
||||||
|
public_ctx = browser.new_context(viewport={"width": 1440, "height": 900}, ignore_https_errors=True)
|
||||||
|
page_pub = public_ctx.new_page()
|
||||||
|
page_pub.goto(f"{BASE_URL}/auth/login")
|
||||||
|
page_pub.wait_for_load_state("networkidle")
|
||||||
|
time.sleep(1)
|
||||||
|
page_pub.screenshot(path=os.path.join(OUTPUT_DIR, "01_login_institucional.png"))
|
||||||
|
public_ctx.close()
|
||||||
|
|
||||||
|
# -------------------------------------------------------------
|
||||||
|
# 2 A 7 Y 10 A 12: SESIÓN ADMINISTRATIVA / BEDELÍA
|
||||||
|
# -------------------------------------------------------------
|
||||||
|
admin_ctx = browser.new_context(viewport={"width": 1440, "height": 900}, ignore_https_errors=True)
|
||||||
|
admin_ctx.add_cookies([{"name": "auth_token", "value": admin_token, "domain": "eduspace.oemspot.com.ar", "path": "/"}])
|
||||||
|
page = admin_ctx.new_page()
|
||||||
|
|
||||||
|
# 2. Dashboard de Bedelía
|
||||||
|
print("[2/12] Capturando Dashboard Operativo de Bedelía...")
|
||||||
|
page.goto(f"{BASE_URL}/dashboard?role=bedelia")
|
||||||
|
page.wait_for_load_state("networkidle")
|
||||||
|
time.sleep(1.5)
|
||||||
|
page.screenshot(path=os.path.join(OUTPUT_DIR, "02_dashboard_bedelia.png"))
|
||||||
|
|
||||||
|
# 3. Cartelera Operativa de Clases de Hoy
|
||||||
|
print("[3/12] Capturando Cartelera de Clases de Hoy...")
|
||||||
|
page.goto(f"{BASE_URL}/schedule/today_schedule")
|
||||||
|
page.wait_for_load_state("networkidle")
|
||||||
|
time.sleep(1.5)
|
||||||
|
page.screenshot(path=os.path.join(OUTPUT_DIR, "03_cartelera_clases_hoy.png"))
|
||||||
|
|
||||||
|
# 4. Grilla Semanal Interactiva (Drag & Drop)
|
||||||
|
print("[4/12] Capturando Grilla Semanal de Calendario...")
|
||||||
|
page.goto(f"{BASE_URL}/schedule/calendar")
|
||||||
|
page.wait_for_load_state("networkidle")
|
||||||
|
time.sleep(2)
|
||||||
|
page.screenshot(path=os.path.join(OUTPUT_DIR, "04_grilla_semanal_calendario.png"))
|
||||||
|
|
||||||
|
# 5. Optimizador Genético de Aulas IA
|
||||||
|
print("[5/12] Capturando Optimizador Genético de Aulas IA...")
|
||||||
|
page.goto(f"{BASE_URL}/genetic_optimizer")
|
||||||
|
page.wait_for_load_state("networkidle")
|
||||||
|
time.sleep(2)
|
||||||
|
page.screenshot(path=os.path.join(OUTPUT_DIR, "05_optimizador_genetico_ia.png"))
|
||||||
|
|
||||||
|
# 6. Catálogo de Aulas Físicas y Virtuales
|
||||||
|
print("[6/12] Capturando Catálogo de Aulas y Sedes...")
|
||||||
|
page.goto(f"{BASE_URL}/classrooms/list_classrooms")
|
||||||
|
page.wait_for_load_state("networkidle")
|
||||||
|
time.sleep(1.5)
|
||||||
|
page.screenshot(path=os.path.join(OUTPUT_DIR, "06_catalogo_aulas_y_sedes.png"))
|
||||||
|
|
||||||
|
# 7. Módulo de Convenios y Beneficios
|
||||||
|
print("[7/12] Capturando Módulo de Beneficios...")
|
||||||
|
page.goto(f"{BASE_URL}/benefits")
|
||||||
|
page.wait_for_load_state("networkidle")
|
||||||
|
time.sleep(1.5)
|
||||||
|
page.screenshot(path=os.path.join(OUTPUT_DIR, "07_modulo_convenios_beneficios.png"))
|
||||||
|
|
||||||
|
# 10. Consola de Recepción y Control de Accesos
|
||||||
|
print("[10/12] Capturando Consola de Recepción Inicial...")
|
||||||
|
page.goto(f"{BASE_URL}/reception/scanner")
|
||||||
|
page.wait_for_load_state("networkidle")
|
||||||
|
time.sleep(1.5)
|
||||||
|
page.screenshot(path=os.path.join(OUTPUT_DIR, "10_consola_recepcion_scanner.png"))
|
||||||
|
|
||||||
|
# 11. Consola de Recepción con Escaneo de DNI de Carlos Tello
|
||||||
|
print("[11/12] Simulando escaneo de DNI 34247025 y capturando validación...")
|
||||||
|
scanner_input = page.query_selector("#scannerInput")
|
||||||
|
if scanner_input:
|
||||||
|
scanner_input.fill("34247025")
|
||||||
|
scanner_input.press("Enter")
|
||||||
|
time.sleep(2)
|
||||||
|
page.screenshot(path=os.path.join(OUTPUT_DIR, "11_recepcion_escaneo_carlos_tello.png"))
|
||||||
|
|
||||||
|
# 12. Documentación OpenAPI Swagger UI
|
||||||
|
print("[12/12] Capturando Swagger UI (/docs)...")
|
||||||
|
page.goto(f"{BASE_URL}/docs")
|
||||||
|
page.wait_for_load_state("networkidle")
|
||||||
|
time.sleep(2)
|
||||||
|
page.screenshot(path=os.path.join(OUTPUT_DIR, "12_swagger_openapi_docs.png"))
|
||||||
|
|
||||||
|
# Asistente virtual UdeCi
|
||||||
|
print("[9/12] Capturando Asistente Virtual UdeCi...")
|
||||||
|
page.goto(f"{BASE_URL}/dashboard?role=admin")
|
||||||
|
page.wait_for_load_state("networkidle")
|
||||||
|
time.sleep(1)
|
||||||
|
chat_btn = page.query_selector("#udeciChatTrigger, #chatToggleBtn, .chat-launcher, #openChatBtn")
|
||||||
|
if chat_btn:
|
||||||
|
try:
|
||||||
|
chat_btn.click()
|
||||||
|
time.sleep(1.5)
|
||||||
|
except Exception as e:
|
||||||
|
print(f"[!] Info chat toggle: {e}")
|
||||||
|
page.screenshot(path=os.path.join(OUTPUT_DIR, "09_asistente_virtual_udeci.png"))
|
||||||
|
|
||||||
|
admin_ctx.close()
|
||||||
|
|
||||||
|
# -------------------------------------------------------------
|
||||||
|
# 8. CREDENCIAL DIGITAL UNIVERSITARIA DE CARLOS TELLO (Alumno)
|
||||||
|
# -------------------------------------------------------------
|
||||||
|
print("[8/12] Capturando Carnet Universitario Digital con QR de Carlos Tello...")
|
||||||
|
tello_ctx = browser.new_context(viewport={"width": 1440, "height": 900}, ignore_https_errors=True)
|
||||||
|
tello_ctx.add_cookies([{"name": "auth_token", "value": tello_token, "domain": "eduspace.oemspot.com.ar", "path": "/"}])
|
||||||
|
page_tello = tello_ctx.new_page()
|
||||||
|
page_tello.goto(f"{BASE_URL}/credential/my-card")
|
||||||
|
page_tello.wait_for_load_state("networkidle")
|
||||||
|
time.sleep(2)
|
||||||
|
page_tello.screenshot(path=os.path.join(OUTPUT_DIR, "08_credencial_digital_carlos_tello.png"))
|
||||||
|
tello_ctx.close()
|
||||||
|
|
||||||
|
browser.close()
|
||||||
|
print("[+] ¡Todas las capturas se han generado exitosamente en docs/entregables/capturas!")
|
||||||
|
|
||||||
|
if __name__ == "__main__":
|
||||||
|
main()
|
||||||