306 lines
17 KiB
Markdown
306 lines
17 KiB
Markdown
# Panel de Administración Edu-Space (UniCABA)
|
|
|
|
Plataforma integral de gestión áulica, asignación de espacios, control de horarios y reservas académicas para la **Universidad de la Ciudad de Buenos Aires (UniCABA)**, desarrollada con **Python / Flask**, **SQLAlchemy**, **PostgreSQL** y **Bootstrap 5**.
|
|
|
|
---
|
|
|
|
## 🏛️ 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$)**.
|
|
|
|
---
|
|
|
|
## ✨ Características Principales
|
|
|
|
### 🛡️ 1. Control de Accesos RBAC Granular (Matriz estilo FortiGate)
|
|
* **Gestión por Módulos:** Permisos independientes por cada área del sistema:
|
|
1. **Aulas y Espacios:** Creación, edición, capacidad y estado de aulas físicas y virtuales.
|
|
2. **Edificios y Sedes:** Administración de sedes, pisos y arquitectura edilicia.
|
|
3. **Reservas de Aulas:** Solicitud, aprobación, confirmación y cancelación.
|
|
4. **Cartelera y Cronograma:** Calendario interactivo, visualización diaria y comisiones.
|
|
5. **Gestión Académica:** Carreras, asignaturas, códigos y comisiones.
|
|
6. **Sincronización Sheets:** Importador y sincronizador de Google Sheets.
|
|
7. **Optimizador IA:** Algoritmo genético de distribución y resolución de conflictos.
|
|
8. **Usuarios y Accesos RBAC:** Cuentas, roles y matriz de permisos.
|
|
* **Niveles de Permiso Granulares:** `Ninguno`, `Solo Lectura` o `Lectura y Escritura`.
|
|
* **Controles Rápidos:** Botón *"Establecer Todos"* para configuración masiva inmediata.
|
|
* **Roles Predefinidos:** `Admin` (control total), `Docente`, `Operador` y `Consulta`.
|
|
|
|
### 📊 2. Sincronización e Importación desde Google Sheets
|
|
* Integración directa con la cartelera académica de UniCABA en Google Sheets.
|
|
* Extracción e importación normalizada de los 5 campos clave:
|
|
* **Código Académico:** Códigos reales de asignatura (ej. `INGA0003`, `ASIG00165`).
|
|
* **Asignatura:** Nombre oficial de la materia.
|
|
* **Aula:** Mapeo a aulas físicas (PB a 4.° piso) o aula `VIRTUAL` ($\infty$).
|
|
* **Carrera:** Normalización y vinculación relacional con entidades de carrera.
|
|
* **Horarios y Turnos:** Detección automática de franjas horarias y delimitadores de bloque (`Turno Mañana` y `Turno Tarde / Vespertino`).
|
|
|
|
### 📅 3. Calendario Interactivo de Reservas (FullCalendar)
|
|
* **Visualización Semanal, Mensual y Diaria:** Grilla ágil de alta legibilidad con jerarquía visual:
|
|
* Asignatura destacada en tipografía grande y negrita.
|
|
* Badges con código de materia, aula asignada, turno y franja horaria.
|
|
* **Filtros Dinámicos Combinables:**
|
|
* Filtrar por **Aula**.
|
|
* Filtrar por **Materia / Asignatura**.
|
|
* Filtrar por **Carrera**.
|
|
* Filtrar por **Turno** (`Turno Mañana` / `Turno Tarde`).
|
|
* Filtrar por **Piso / Planta** (`Planta Baja`, `Piso 1`, `Piso 2`, `Piso 3`, `Piso 4`).
|
|
* **Switch "Ocultar Aulas Virtuales":** Aísla la ocupación física real en el edificio central excluyendo los eventos virtuales de capacidad infinita.
|
|
* **Ficha Modal Instantánea:** Vista previa detallada al hacer clic en cualquier evento.
|
|
|
|
### 📋 4. Cartelera del Día y Listado de Reservas
|
|
* **Cartelera del Día (`/schedule/today`):**
|
|
* **Vista Cronológica (Timeline):** Bloques horarios de 07:00 a 22:00 hs con indicador de ocupación.
|
|
* **Vista en Tabla:** Lista ordenada con acciones rápidas y detalles de comisión.
|
|
* Filtros directos por piso, turno y switch para ocultar virtuales.
|
|
* **Listado Paginado de Reservas (`/schedule/list`):**
|
|
* Paginación de 20 registros por página preservando filtros aplicados.
|
|
* Búsqueda por texto, estado (`Confirmada`, `Pendiente`, `Cancelada`), rango de fechas y piso.
|
|
|
|
### 🏫 5. Gestión de Aulas con Capacidad Infinita ($\infty$)
|
|
* Soporte nativo para el símbolo **`∞`** o `0` para designar aulas virtuales o espacios sin aforo restringido.
|
|
* Botón de un solo clic `Ilimitada (∞)` en formularios de alta y edición con leyendas explicativas.
|
|
* Badges distintivos `∞ Ilimitada` en listados, tarjetas y fichas técnicas.
|
|
|
|
### 🤖 6. Optimizador Inteligente de Aulas (Algoritmo Genético)
|
|
* Motor de optimización heurística para asignación automática de aulas a comisiones.
|
|
* Pondera capacidad requerida vs. capacidad de aula, equipamiento tecnológico y minimización de desplazamientos entre pisos.
|
|
|
|
### 🎨 7. Experiencia de Usuario, Temas y Localización
|
|
* **Tema Oscuro / Claro:** Alternador con botón flotante y persistencia en `localStorage` y perfil de usuario.
|
|
* **Soporte Multilingüe:** Internacionalización integral (Español e Inglés) compilada con GNU gettext (`pybabel`).
|
|
* **Tarjetas Estadísticas Interactivas:** Accesos directos rápidos desde el panel general hacia las distintas secciones operativas.
|
|
|
|
### 🏛️ 8. Sistema Integral de Gestión Institucional (8 Módulos)
|
|
El menú desplegable **Gestión** en la barra de navegación organiza las áreas operativas de la universidad:
|
|
* **Espacios e Infraestructura:**
|
|
* **Edificios y Sedes (`/buildings/list`):** Administración de edificios físicos, arquitectura y estado edilicio.
|
|
* **Aulas Presenciales (`/classrooms/list?view_mode=physical`):** Catálogo de aulas físicas por piso, capacidades y zócalos compactos con métricas de ocupación en tiempo real (día, semana, mes).
|
|
* **Aulas Virtuales con Reunión (`/classrooms/list?view_mode=virtual`):** Campus Virtual con salas a demanda agrupadas por comisión, capacidad ilimitada ($\infty$) y enlaces directos de acceso a videollamadas (Zoom, Google Meet, Microsoft Teams).
|
|
* **Gestión de Ocupación y Métricas (`/admin/occupancy-metrics`):** Dashboard analítico de tasas de ocupación horaria (día, semana, mes), horas pico, distribución por turno y comparativa física vs. virtual.
|
|
* **Gestión Académica:**
|
|
* **Carreras (`/admin/careers`):** ABM de carreras universitarias y planes de estudio con contador de asignaturas y comisiones activas.
|
|
* **Asignaturas (`/admin/subjects`):** Catálogo institucional de materias con créditos, departamentos y filtros por carrera y estado.
|
|
* **Comisiones y Cursadas (`/schedule/commissions`):** Gestión de cursadas, turnos, docentes, enlaces virtuales e hitos de evaluación.
|
|
* **Ciclo Lectivo (`/admin/academic-terms`):** Modelo y panel de administración de períodos académicos, cuatrimestres y activación del ciclo lectivo en curso.
|
|
* **Administración & Seguridad:**
|
|
* **Usuarios y Roles RBAC:** Cuentas, asignación de permisos matriciales y auditoría.
|
|
* **Tipificaciones de Hitos:** Catálogo de tipos de hitos de evaluación académica.
|
|
* **Sincronización Sheets:** Integración con Google Sheets para actualización en lote.
|
|
|
|
---
|
|
|
|
## 🛠️ Stack Tecnológico
|
|
|
|
| Componente | Tecnología |
|
|
| :--- | :--- |
|
|
| **Backend** | Python 3.12+ / Flask |
|
|
| **Base de Datos** | PostgreSQL 16+ / SQLAlchemy ORM |
|
|
| **Seguridad & Sesiones** | Flask-Login / Werkzeug / CSRF Protect |
|
|
| **Formularios** | Flask-WTF / WTForms |
|
|
| **Internacionalización** | Flask-Babel / GNU gettext |
|
|
| **Frontend** | Bootstrap 5.3, Bootstrap Icons, Vanilla JS, CSS Variables |
|
|
| **Calendario** | FullCalendar 5.11 |
|
|
|
|
---
|
|
|
|
## 🚀 Despliegue en Proxmox VE (LXC) con Entorno Virtual `venv`
|
|
|
|
El sistema está especialmente optimizado para ejecutarse en contenedores **LXC (Debian 12 Bookworm o Ubuntu 22.04/24.04 LTS)** dentro de **Proxmox VE**, utilizando un entorno virtual nativo de Python (`venv`), el motor **PostgreSQL** instalado en el propio contenedor y el servidor WSGI **Gunicorn** gestionado como servicio por **systemd**.
|
|
|
|
---
|
|
|
|
### 📋 Paso 1: Creación del Contenedor LXC en Proxmox VE
|
|
|
|
Podés crear el contenedor desde la interfaz Web de Proxmox (*Create CT*) o por terminal Proxmox con `pct create`:
|
|
|
|
* **Plantilla (Template):** `debian-12-standard` (*Recomendado*) o `ubuntu-22.04-standard` / `ubuntu-24.04-standard`.
|
|
* **CPU:** 1 a 2 vCPU.
|
|
* **Memoria RAM:** 1024 MB a 2048 MB (Swap: 512 MB).
|
|
* **Disco:** 8 GB a 15 GB (almacenamiento `local-lvm` o `zfs`).
|
|
* **Red (Network):** Modo Bridge `vmbr0` con IP estática en tu red local o DHCP (ej: `192.168.1.150/24`, Gateway: `192.168.1.1`).
|
|
* **Opciones del Contenedor:**
|
|
* *Unprivileged container:* Sí (marcado por defecto, compatible).
|
|
* *Features (Características):* Habilitar **Nesting (`nesting=1`)** en `CT > Opciones > Características` (requerido para systemd).
|
|
|
|
---
|
|
|
|
### ⚡ Paso 2: Instalación Automatizada con `install.sh`
|
|
|
|
1. **Ingresar a la consola del contenedor LXC:**
|
|
Desde la Web UI de Proxmox (consola noVNC) o desde el shell de tu nodo Proxmox:
|
|
```bash
|
|
pct enter <ID_DEL_CONTENEDOR>
|
|
```
|
|
|
|
2. **Clonar el repositorio y lanzar el instalador:**
|
|
```bash
|
|
apt update && apt install -y git
|
|
git clone https://gitea.oemspot.com.ar/carlostellocba/admin-edu-space.git
|
|
cd admin-edu-space
|
|
bash install.sh
|
|
```
|
|
|
|
3. **Flujo de Ejecución Automatizado en el LXC:**
|
|
* **Migración segura fuera de `/root`:** Si el repositorio se clonó en `/root`, el instalador lo traslada automáticamente a `/opt/admin-edu-space` para garantizar que el usuario del servicio (`eduspace`) tenga acceso de lectura y ejecución.
|
|
* **Locales UTF-8:** Configura `en_US.UTF-8` y `es_AR.UTF-8` para asegurar la internacionalización con `Flask-Babel` y prevenir errores de encoding.
|
|
* **Motor PostgreSQL:** Instala el motor PostgreSQL, inicia el servicio y verifica conectividad activa con bucle de espera.
|
|
* **Restauración del Snapshot Oficial ([classrooms_db.sql](file:///c:/Workspace/admin-edu-space/classrooms_db.sql)):**
|
|
* Detecta el volcado completo de datos.
|
|
* Crea la base de datos `classrooms_db` y el usuario `eduspace_user`.
|
|
* Restaura **25 aulas** (físicas y Campus Virtual $\infty$), **206 comisiones**, **206 materias**, **412 reservas históricas**, **24 carreras**, matrices RBAC y cuentas de acceso.
|
|
* Otorga privilegios totales (`GRANT ALL`) en el esquema `public`, todas las tablas y **todas las secuencias** al usuario `eduspace_user`.
|
|
* Ejecuta `init_db.py` de forma idempotente para validar roles y coherencia.
|
|
* **Entorno Virtual Python (`venv`):** Crea el entorno aislado en `/opt/admin-edu-space/venv` e instala todas las dependencias oficiales (`Flask`, `SQLAlchemy`, `Gunicorn`, etc.).
|
|
* **Servicio Systemd de Producción:** Configura el servicio `admin-edu-space.service` gestionado por **Gunicorn** (3 workers, puerto 5000), con reinicio automático ante fallos y habilitado al inicio del contenedor.
|
|
|
|
---
|
|
|
|
### 🌐 Paso 3: Acceso Inmediato a la Aplicación
|
|
|
|
Al finalizar la instalación, el script mostrará la dirección IP del contenedor:
|
|
* **URL:** **`http://<IP-DEL-LXC>:5000`** (ejemplo: `http://192.168.1.150:5000`)
|
|
* **Email Administrador:** `admin@edu-space.com`
|
|
* **Contraseña Administrador:** `admin123`
|
|
|
|
---
|
|
|
|
### 🛠️ Comandos de Gestión del Servicio en el LXC
|
|
|
|
```bash
|
|
# Consultar estado en tiempo real
|
|
systemctl status admin-edu-space
|
|
|
|
# Seguir logs de la aplicación
|
|
journalctl -u admin-edu-space -f
|
|
|
|
# Reiniciar la aplicación
|
|
systemctl restart admin-edu-space
|
|
|
|
# Detener el servicio
|
|
systemctl stop admin-edu-space
|
|
```
|
|
|
|
---
|
|
|
|
### 💾 Generación de Backups y Migración a Otros Contenedores LXC
|
|
|
|
Para respaldar la base de datos en ejecución o clonarla a otro contenedor LXC:
|
|
|
|
```bash
|
|
# Dentro del contenedor LXC:
|
|
cd /opt/admin-edu-space
|
|
bash backup_db.sh
|
|
```
|
|
|
|
* El script genera un archivo fechado en `backups/classrooms_db_YYYYMMDD_HHMMSS.sql`.
|
|
* Actualiza automáticamente el archivo principal [classrooms_db.sql](file:///c:/Workspace/admin-edu-space/classrooms_db.sql).
|
|
* **Para migrar a otro contenedor:** Podés transferir `classrooms_db.sql` mediante SCP o Git y ejecutar `bash install.sh` en el nuevo LXC.
|
|
|
|
---
|
|
|
|
### 💻 Instalación Manual para Desarrollo Local (con `venv`)
|
|
|
|
Si deseás correr el proyecto en una máquina de desarrollo (Windows / Linux / macOS) sin usar el instalador de Proxmox:
|
|
|
|
1. **Crear y activar el entorno virtual:**
|
|
* En Windows (PowerShell):
|
|
```powershell
|
|
python -m venv venv
|
|
.\venv\Scripts\Activate.ps1
|
|
```
|
|
* En Linux / macOS:
|
|
```bash
|
|
python3 -m venv venv
|
|
source venv/bin/activate
|
|
```
|
|
|
|
2. **Instalar dependencias:**
|
|
```bash
|
|
pip install -r requirements.txt
|
|
```
|
|
|
|
3. **Configurar base de datos local y restaurar snapshot:**
|
|
```bash
|
|
cp .env.example .env
|
|
|
|
# Crear base de datos en PostgreSQL local y cargar datos
|
|
sudo -u postgres psql -c "CREATE DATABASE classrooms_db;"
|
|
sudo -u postgres psql -d classrooms_db < classrooms_db.sql
|
|
```
|
|
|
|
4. **Compilar catálogos de traducción:**
|
|
```bash
|
|
pybabel compile -d translations
|
|
```
|
|
|
|
5. **Iniciar el servidor:**
|
|
```bash
|
|
python wsgi.py
|
|
```
|
|
Disponible en: **`http://localhost:5000`**
|
|
|
|
---
|
|
|
|
## 🔑 Credenciales Predeterminadas
|
|
|
|
| Usuario | Correo Electrónico | Contraseña | Rol |
|
|
| :--- | :--- | :--- | :--- |
|
|
| **Administrador del Sistema** | `admin@edu-space.com` | `admin123` | `Admin` (Acceso Total) |
|
|
|
|
> ⚠️ **Seguridad:** Cambiá la contraseña del administrador desde la interfaz web inmediatamente después del primer inicio de sesión.
|
|
|
|
---
|
|
|
|
## 📁 Estructura del Proyecto
|
|
|
|
```text
|
|
admin-edu-space/
|
|
├── app/
|
|
│ ├── __init__.py # Factoría de la aplicación Flask y extensiones
|
|
│ ├── forms/ # Formularios Flask-WTF con validación CSRF
|
|
│ │ ├── auth.py # Login, perfil y cambio de clave
|
|
│ │ ├── building.py # Sedes y edificios
|
|
│ │ ├── classroom.py # Aulas y capacidades (con soporte ∞)
|
|
│ │ └── reservation.py # Reservas de aulas y horarios
|
|
│ ├── models/ # Modelos relacionales SQLAlchemy
|
|
│ │ ├── academic_term.py # Ciclos lectivos y períodos académicos (activo/histórico)
|
|
│ │ ├── building.py # Sedes y edificios institucionales
|
|
│ │ ├── career.py # Carreras y titulaciones universitarias
|
|
│ │ ├── classroom.py # Aulas físicas y virtuales con capacidades
|
|
│ │ ├── genetic_algorithm.py # Estructuras de optimización heurística
|
|
│ │ ├── milestone.py # Tipificaciones de hitos académicos y exámenes
|
|
│ │ ├── reservation.py # Reservas horarias, estados y turnos
|
|
│ │ ├── role.py # Roles y matriz de permisos granulares RBAC
|
|
│ │ ├── subject.py # Asignaturas, materias y comisiones de cursada
|
|
│ │ └── user.py # Usuarios, credenciales y asignación de roles
|
|
│ ├── routes/ # Controladores y rutas modulares (Blueprints)
|
|
│ │ ├── admin.py # Carreras, Asignaturas, Ciclo Lectivo, Tipificaciones, Métricas, Usuarios y Roles
|
|
│ │ ├── auth.py # Autenticación, sesiones y perfil
|
|
│ │ ├── buildings.py # Gestión de sedes y edificios
|
|
│ │ ├── classrooms.py # Aulas presenciales vs. Campus Virtual a demanda y métricas de uso
|
|
│ │ ├── genetic_algorithm.py # Optimizador heurístico de asignación de espacios
|
|
│ │ ├── main.py # Dashboard principal y métricas rápidas
|
|
│ │ └── schedule.py # Calendario interactivo, cartelera del día, comisiones y reservas
|
|
│ ├── services/ # Servicios y lógica de negocio
|
|
│ │ └── sheets_importer.py # Parser y sincronizador bidireccional de Google Sheets
|
|
│ ├── static/ # Recursos estáticos web (CSS, JS, imágenes institucionales)
|
|
│ └── templates/ # Vistas Jinja2 renderizadas con Bootstrap 5
|
|
├── config/ # Configuraciones de entorno (desarrollo, testing, prod)
|
|
├── translations/ # Catálogos GNU gettext compilados (es / en)
|
|
├── classrooms_db.sql # Snapshot completo de base de datos (PostgreSQL 14+)
|
|
├── install.sh # Instalador automatizado para Proxmox VE LXC (venv + PostgreSQL)
|
|
├── backup_db.sh # Script para generar nuevos backups y actualizar snapshot
|
|
├── init_db.py # Inicializador DDL y sincronizador de esquema/roles
|
|
├── CHANGELOG_SESSION.md # Historial técnico cronológico
|
|
├── requirements.txt # Dependencias Python (incluye Gunicorn)
|
|
├── .env.example # Plantilla de variables de entorno
|
|
└── wsgi.py # Punto de entrada de la aplicación Flask
|
|
```
|
|
|
|
---
|
|
|
|
## 📄 Licencia
|
|
|
|
Este proyecto forma parte del sistema de gestión institucional y educativa de **UniCABA**. Todos los derechos reservados.
|
|
|