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

---

🚀 Instalación y Puesta en Marcha

⚡ Opción A — Deploy Automático en Debian 12 LXC (Recomendado)

El repositorio incluye un instalador interactivo (install.sh) que configura todo el entorno de producción automáticamente: dependencias del sistema, PostgreSQL, entorno virtual Python, inicialización de base de datos y servicio systemd con Gunicorn.

Prerrequisitos

• Contenedor LXC o servidor con Debian 12 (Bookworm)
• Acceso root (o sudo)
• Conexión a Internet

Pasos

# 1. Clonar el repositorio
git clone https://gitea.oemspot.com.ar/carlostellocba/admin-edu-space.git
cd admin-edu-space

# 2. Dar permisos de ejecución al instalador
chmod +x install.sh

# 3. Ejecutar el instalador como root
sudo bash install.sh

Durante la ejecución el instalador solicitará únicamente la contraseña para el usuario de base de datos (si se deja vacío usa eduspace2024 por defecto).

Qué instala y configura automáticamente

Paso	Acción
1	Configura locale en_US.UTF-8 en el sistema (previene errores de encoding)
2	Instala Python 3, venv, pip, build-tools, libpq-dev y PostgreSQL
3	Inicia y habilita el servicio PostgreSQL para el arranque automático
4	Genera SECRET_KEY aleatoria y crea el archivo .env de producción
5	Crea el usuario eduspace_user y la base de datos classrooms_db en PostgreSQL
6	Crea el virtualenv e instala todas las dependencias + Gunicorn
7	Ejecuta init_db.py (tablas, roles RBAC, edificios y usuario admin inicial)
8	Crea el usuario del sistema eduspace (sin shell, por seguridad)
9	Registra y arranca el servicio systemd admin-edu-space en el puerto 5000
10	Muestra resumen con URL, credenciales y comandos de gestión

Comandos de gestión post-instalación

# Ver estado del servicio
systemctl status admin-edu-space

# Ver logs en tiempo real
journalctl -u admin-edu-space -f

# Reiniciar la aplicación
systemctl restart admin-edu-space

# Detener la aplicación
systemctl stop admin-edu-space

Nota: Si el archivo .env ya existe en el directorio (por ejemplo, copiado manualmente antes de correr el instalador), el script lo conserva sin sobrescribirlo.

---

🖥️ Opción B — Instalación Manual (Desarrollo Local)

Prerrequisitos

1. Python 3.10 o superior
2. PostgreSQL en ejecución con una base de datos creada (ej. classrooms_db).
3. Git

Pasos de Configuración

1. Clonar el repositorio:

   git clone https://gitea.oemspot.com.ar/carlostellocba/admin-edu-space.git
   cd admin-edu-space
   

2. Crear y activar el entorno virtual:

   • En Windows (PowerShell):

     python -m venv venv
     .\venv\Scripts\Activate.ps1
     

   • En Linux / macOS:

     python3 -m venv venv
     source venv/bin/activate
     

3. Instalar dependencias:

   pip install -r requirements.txt
   

4. Configurar variables de entorno (.env): Copiar la plantilla y editar con los valores de tu entorno:

   cp .env.example .env
   

   SECRET_KEY=clave-secreta-de-produccion-cambiar-en-despliegue
   DATABASE_URL=postgresql://postgres:postgres@localhost:5432/classrooms_db
   FLASK_ENV=development
   FLASK_DEBUG=1
   

5. Inicializar la Base de Datos: Ejecutar el script de inicialización para crear tablas, roles institucionales, permisos RBAC, sedes y el usuario administrador:

   python init_db.py
   

6. Compilar catálogos de traducción (opcional si se modifican textos):

   pybabel compile -d translations
   

7. Iniciar el servidor de desarrollo:

   python app.py
   

   La aplicación estará 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)

⚠️ Importante: Cambiá la contraseña del administrador inmediatamente después del primer acceso.

---

📁 Estructura del Proyecto

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/
│   │   │   ├── style.css            # Estilos base y utilidades
│   │   │   └── theme.css            # Variables CSS para modo claro y modo oscuro
│   │   └── js/
│   │       ├── genetic-algorithm.js # Lógica de ejecución del algoritmo genético
│   │       ├── main.js              # Interacciones globales y filtros dinámicos
│   │       └── theme-toggle.js      # Conmutador reactivo de tema con persistencia
│   ├── templates/                   # Vistas Jinja2 renderizadas con Bootstrap 5
│   │   ├── base.html                # Plantilla maestra con navbar categorizada y menú Gestión
│   │   ├── dashboard.html           # Panel principal de control y métricas
│   │   ├── genetic_optimizer.html   # Interfaz del optimizador de espacios
│   │   ├── admin/
│   │   │   ├── academic_terms/      # Gestión de Ciclos Lectivos y cuatrimestres
│   │   │   ├── careers/             # Gestión de Carreras y titulaciones
│   │   │   ├── metrics/             # Dashboard de Ocupación y Métricas de Espacios
│   │   │   ├── milestone_types/     # Gestión de Tipificaciones de Hitos
│   │   │   ├── roles/               # Gestión de Roles y Matriz de Permisos RBAC
│   │   │   ├── subjects/            # Gestión de Asignaturas y Materias
│   │   │   ├── users/               # Gestión de Usuarios y cuentas
│   │   │   └── import.html          # Sincronización con Google Sheets
│   │   ├── auth/                    # Vistas de autenticación y perfil de usuario
│   │   ├── buildings/               # Listado, alta y edición de sedes y edificios
│   │   ├── classrooms/              # Listado físico vs virtual, alta, edición y ficha
│   │   └── schedule/                # Calendario (FullCalendar), cartelera del día, comisiones y reservas
│   └── utils/                       # Utilidades transversales y decoradores
│       └── decorators.py            # Decoradores RBAC (@permission_required, can_manage, etc.)
├── config/                          # Configuraciones de entorno (desarrollo, testing, prod)
├── translations/                    # Catálogos GNU gettext compilados (es / en)
├── install.sh                       # Instalador automático para Debian 12 LXC
├── init_db.py                       # Inicializador DDL y semillero de datos
├── CHANGELOG_SESSION.md             # Historial técnico cronológico
├── requirements.txt                 # Dependencias Python
├── .env.example                     # Plantilla de variables de entorno
└── app.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.