223 lines
15 KiB
Markdown
223 lines
15 KiB
Markdown
# 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)**.
|
|
|
|
El proyecto se basa en una arquitectura **desacoplada (Frontend / Backend)** en formato monorepo.
|
|
|
|
**Versión Actual:** `2.8.0` (Fases 0 a 4 del Roadmap MVP 100% completadas)
|
|
**Institución:** Universidad de la Ciudad de Buenos Aires (UniCABA)
|
|
|
|
---
|
|
|
|
## 🗺️ Estado del Roadmap MVP
|
|
|
|
```
|
|
Fase 0: Desacople y Arquitectura Base [████████████████████] 100% (Completado)
|
|
Fase 1: Paridad Legacy y Estabilización [████████████████████] 100% (Completado)
|
|
Fase 2: Co-docencia y Matriz Conflictos [████████████████████] 100% (Completado)
|
|
Fase 3: Hitos Evaluativos y Calificaciones[████████████████████] 100% (Completado)
|
|
Fase 4: UI/UX Drag & Drop e Impersonación[████████████████████] 100% (Completado)
|
|
Fase 5: Integración Auth, Email & Moodle [████████████████████] 100% (Completado)
|
|
Fase 6: Despliegue Producción e Integrac.[████░░░░░░░░░░░░░░░░] 25% (En Curso)
|
|
```
|
|
|
|
---
|
|
|
|
## 🏛️ 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$)**.
|
|
|
|
---
|
|
|
|
## 🏗️ Arquitectura del Proyecto (Monorepo)
|
|
|
|
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:
|
|
|
|
```text
|
|
/
|
|
├── backend/ # Capa Core API (Python 3.10+ / Flask / SQLAlchemy)
|
|
│ ├── app/ # Lógica de negocio y arquitectura desacoplada
|
|
│ │ ├── models/ # Modelos ORM (User, Role, Classroom, Reservation, etc.)
|
|
│ │ ├── routes/api/ # Endpoints REST JSON v1 (/auth, /classrooms, /admin, etc.)
|
|
│ │ ├── schemas/ # DTOs y validación de contratos (Pydantic v2)
|
|
│ │ ├── services/ # Servicios de dominio (JWT, Email SMTP, Moodle, Queue)
|
|
│ │ └── security/ # Pipeline de filtros y validación stateless de JWT
|
|
│ ├── tests/ # Suite activa de pruebas unitarias y de integración (pytest)
|
|
│ ├── init_db.py # Inicializador idempotente de esquema, roles RBAC y semillas
|
|
│ ├── backup_db.sh # Generador automatizado de backups para PostgreSQL
|
|
│ ├── classrooms_db.sql # Snapshot integral de base de datos para despliegue
|
|
│ ├── wsgi.py # Entrada WSGI para ejecución con Gunicorn
|
|
│ └── requirements.txt # Dependencias Python auditadas (0 vulnerabilidades / CVEs)
|
|
│
|
|
├── frontend/ # Backend-For-Frontend BFF (Node.js 20 LTS / Express)
|
|
│ ├── src/ # Capa servidora de mediación web
|
|
│ │ ├── app.js # Servidor Express, seguridad Helmet, rate-limiting
|
|
│ │ ├── controllers/ # Controladores de orquestación y mediación
|
|
│ │ ├── middlewares/ # Sesión por Cookie HttpOnly, JWT injection y RBAC
|
|
│ │ ├── routes/ # Enrutamiento web (auth, schedule, classrooms, admin)
|
|
│ │ └── services/ # Cliente Axios centralizado hacia Flask API
|
|
│ ├── views/ # Plantillas y componentes dinámicos en Nunjucks (.html)
|
|
│ │ ├── admin/ # Paneles de gestión institucional y configuración
|
|
│ │ ├── classrooms/ # Catálogo de aulas y visualización de sedes
|
|
│ │ ├── schedule/ # Cronograma de comisiones, reservas y calendario
|
|
│ │ ├── my_subjects/ # Libreta de calificaciones, hitos evaluativos y cursada
|
|
│ │ └── partials/ # Componentes reutilizables, modales y navegación
|
|
│ ├── public/ # Assets estáticos (CSS responsive 720p/1080p, JS cliente)
|
|
│ └── package.json # Dependencias y manifiesto de Node.js
|
|
│
|
|
├── install.sh # Instalador nativo unificado para Linux / Proxmox LXC
|
|
├── security_audit.bat # Suite automatizada de auditoría (SAST, SCA, DAST)
|
|
├── .gitea/workflows/ # Pipelines de integración continua (CI/CD en Gitea)
|
|
├── docs/ # Especificaciones técnicas, auditorías y changelogs
|
|
├── ROADMAP_MVP.md # Plan de evolución, estadios y fases del proyecto
|
|
├── SECURITY_AUDIT_REPORT.md # Informe formal de auditoría y hardening
|
|
└── README.md # Documentación general y guía operativa
|
|
```
|
|
|
|
### 🐍 Backend Core API (Python + Flask)
|
|
- Funciona exclusivamente como una **REST API** que expone endpoints bajo `/api/v1/` retornando **JSON**.
|
|
- 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).
|
|
- **Prohibido** retornar HTML o utilizar Jinja2/`render_template` en este entorno.
|
|
|
|
### 🟢 Frontend BFF (Node.js + Express)
|
|
- Aplicación Backend-For-Frontend que renderiza las vistas para el cliente mediante **Nunjucks**.
|
|
- Gestiona la sesión segura del usuario almacenando el token JWT recibido de Flask en una **Cookie HttpOnly**.
|
|
- Actúa como proxy de conexión con el Backend de Python empleando **Axios** (inyectando el Bearer token interceptado).
|
|
- Blindado con **Helmet** (cabeceras de seguridad HTTP) y **express-rate-limit** para mitigar 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**).
|
|
|
|
---
|
|
|
|
## 🎯 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, tendencias mensuales y panel interactivo de **Estado y Percentiles de Asignación de Aulas Físicas** (asignadas vs disponibles en número y porcentaje).
|
|
* **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.
|
|
* **Docente / Profesor (`/dashboard?role=docente`):** Sesiones del día con accesos directos a videollamadas y gestión de comisiones.
|
|
* **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.
|
|
|
|
---
|
|
|
|
## ☁️ Sincronización Google Sheets, Configuración Global & Purga Académica
|
|
|
|
El sistema incluye sincronización automatizada con las planillas oficiales de cursada de UniCABA:
|
|
* **Configuración Global Dinámica:** Selección y persistencia de la URL de Google Sheets directamente desde la interfaz web (`/admin/google_sheets_import`) sin valores fijos en el código.
|
|
* **Herramienta de Purga y Reinicio (`reset_academic_data`):** Módulo CLI y web para limpiar selectivamente reservas, aulas, asignaturas, comisiones o carreras, garantizando pruebas limpias desde cero y preservando siempre usuarios y credenciales.
|
|
* **Concurrencia Virtual Ilimitada:** Reconocimiento de espacios áulicos remotos (`Campus Virtual · VIRTUAL`), permitiendo la coexistencia de múltiples comisiones en la misma franja horaria sin colisiones de agenda.
|
|
* **Catálogo Presencial con Cursadas Asignadas:** Listado de aulas físicas con cálculo de ocupación real (semana/mes), vista previa de asignaturas y enlaces directos a calendario y ficha del espacio.
|
|
* **Enlaces de Videollamada Automáticos:** Generación de enlaces seguros (Google Meet / Teams) para acceso instantáneo de docentes y estudiantes.
|
|
* **Filtros en Cartelera:** Opciones para filtrar por turno, piso u ocultar aulas virtuales mediante el switch dedicado en `/schedule/today_schedule`.
|
|
|
|
---
|
|
|
|
## ⚡ 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.
|
|
|
|
---
|
|
|
|
## 📅 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
|
|
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)
|
|
```bash
|
|
cd frontend
|
|
npm install
|
|
npm run dev
|
|
# o en su defecto:
|
|
node src/app.js
|
|
```
|
|
*(El frontend quedará escuchando en http://localhost:3000)*
|
|
|
|
---
|
|
|
|
## 📦 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:
|
|
|
|
```bash
|
|
# Despliegue interactivo (pregunta si mantener o restaurar la BD si ya existe):
|
|
sudo bash install.sh
|
|
|
|
# Despliegue desatendido manteniendo la base de datos existente:
|
|
sudo bash install.sh --keep-db
|
|
|
|
# Despliegue desatendido recreando la base de datos desde cero (DROP y restore snapshot):
|
|
sudo bash install.sh --fresh-db
|
|
```
|
|
|
|
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).
|
|
2. Entorno Node.js 20 LTS en `frontend/` con servicio `admin-edu-space-frontend.service` (puerto 3000).
|
|
3. Motor PostgreSQL local con configuración de usuario y opciones seguras para preservar o restaurar la base `classrooms_db`.
|
|
4. Servicio maestro unificado `admin-edu-space.service` gestionable vía `systemctl {status|restart|stop} admin-edu-space`.
|
|
|
|
---
|
|
|
|
## 🧪 Pruebas Automatizadas
|
|
|
|
Para ejecutar la suite completa de pruebas unitarias de regresión (Fases 2, 3 y 4):
|
|
|
|
```bash
|
|
cd backend
|
|
.\venv\Scripts\python.exe -m unittest tests/test_phase2_rules.py tests/test_phase3_gradebook.py tests/test_phase4_interactive_impersonation.py
|
|
```
|
|
|
|
---
|
|
|
|
## 📚 Documentación Técnica & Changelogs
|
|
* [Roadmap MVP: Fases y Estadios del Proyecto](ROADMAP_MVP.md)
|
|
* [Changelog Oficial del Proyecto (v2.8.0)](CHANGELOG.md)
|
|
* [Changelog MVP Consolidado](CHANGELOG_MVP.md)
|
|
* [Estado de la Migración y Arquitectura Objetivo UniCABA](ESTADO_MIGRACION_Y_ARQUITECTURA_OBJETIVO.md)
|
|
* [Changelog Detallado: Clases Virtuales y Dashboards](docs/CHANGELOG_VIRTUAL_CLASSES_AND_DASHBOARDS.md)
|
|
* [Auditoría y Sesión de Reingeniería](docs/CHANGELOG_SESSION.md)
|
|
* [Guía de Integración de Cronograma](docs/SCHEDULE_INTEGRATION_GUIDE.md) |