carlostellocba/admin-edu-space
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
5dcf3b75f1691296d937b804a6f29319ad35f668
admin-edu-space/README.md
T

14 KiB
Raw Blame History

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

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): Crear o editar el archivo .env en la raíz del proyecto:

    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)

📁 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)
├── 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.

Reference in New Issue View Git Blame Copy Permalink