From 9521b86399ac951c3d5e828dda3a9b55b21294e3 Mon Sep 17 00:00:00 2001 From: Carlos Tello Date: Thu, 3 Sep 2026 03:12:32 -0300 Subject: [PATCH] docs: actualizar README.md en espanol con documentacion completa de UniCABA --- README.md | 440 ++++++++++++++++++++++++------------------------------ 1 file changed, 195 insertions(+), 245 deletions(-) diff --git a/README.md b/README.md index 8aec599..7ebefe6 100644 --- a/README.md +++ b/README.md @@ -1,249 +1,199 @@ -# Edu-Space Admin Panel +# Panel de Administración Edu-Space (UniCABA) -A comprehensive web-based administration interface for the Edu-Space Classroom Reservation System built with Flask. - -## Features - -### 🔐 Authentication & Security -- Secure login system with hashed passwords -- Role-based access control -- Session management with Flask-Login -- Password change functionality - -### 🏫 Classroom Management -- Create, edit, and delete classrooms -- Campus and building organization -- Capacity and resource tracking -- Real-time availability checking - -### 📅 Schedule Management -- Interactive calendar view (FullCalendar) -- Reservation creation and management -- Conflict detection and prevention -- Status tracking (Pending, Confirmed, Cancelled) -- Today's schedule overview - -### 📊 Dashboard & Analytics -- Real-time statistics -- Monthly reservation charts -- Quick actions interface -- Upcoming reservations overview - -### 🎨 Modern UI/UX -- Responsive Bootstrap 5 design -- Dark theme support -- Mobile-friendly interface -- Interactive components and charts - -## Tech Stack - -- **Backend**: Flask (Python) -- **Database**: SQLAlchemy (SQLite/PostgreSQL) -- **Frontend**: Bootstrap 5, jQuery, Chart.js -- **Authentication**: Flask-Login, Werkzeug -- **Forms**: Flask-WTF -- **Calendar**: FullCalendar.js - -## Installation - -### Prerequisites -- Python 3.8+ -- pip package manager - -### Setup - -1. **Clone or setup the project:** -```bash -cd /Users/alejandro.v/PycharmProjects/admin-edu-space -``` - -2. **Create virtual environment:** -```bash -python -m venv venv -source venv/bin/activate # On Windows: venv\Scripts\activate -``` - -3. **Install dependencies:** -```bash -pip install -r requirements.txt -``` - -4. **Setup environment variables:** -```bash -cp .env.example .env -# Edit .env with your configuration -``` - -5. **Initialize database:** -```bash -python app.py -``` - -## Configuration - -### Environment Variables (.env) - -```env -FLASK_APP=app.py -FLASK_ENV=development -SECRET_KEY=your-secret-key-here-please-change-in-production -DATABASE_URL=sqlite:///edu_space.db -API_BASE_URL=http://localhost:8080/api -``` - -## Usage - -### Start the Application - -```bash -python app.py -``` - -The application will be available at: `http://localhost:5000` - -### Default Login - -- **Email**: admin@edu-space.com -- **Password**: admin123 - -### Main Features - -1. **Dashboard**: Overview of system statistics and upcoming reservations -2. **Classrooms**: Manage classroom information, capacity, and resources -3. **Schedule**: View and manage reservations with calendar interface -4. **Profile**: User profile and password management - -## API Integration - -The admin panel integrates with the Spring Boot API at `http://localhost:8080/api`. Make sure the Java microservice is running for full functionality. - -## Project Structure - -``` -admin-edu-space/ -├── app/ -│ ├── __init__.py # Flask app factory -│ ├── models/ # Database models -│ │ ├── user.py -│ │ ├── classroom.py -│ │ ├── subject.py -│ │ └── reservation.py -│ ├── routes/ # Application routes -│ │ ├── auth.py -│ │ ├── main.py -│ │ ├── classrooms.py -│ │ └── schedule.py -│ ├── forms/ # WTForms classes -│ │ ├── auth.py -│ │ ├── classroom.py -│ │ └── reservation.py -│ ├── templates/ # Jinja2 templates -│ ├── static/ # Static files -├── config/ # Configuration files -├── requirements.txt -├── .env -├── app.py -└── README.md -``` - -## Database Schema - -### Users Table -- User authentication and authorization -- Role management (admin, staff) - -### Classrooms Table -- Classroom information -- Capacity and location details -- Resource management - -### Reservations Table -- Booking management -- Time slot scheduling -- Status tracking - -### Subjects + Commissions Tables -- Academic information -- Teacher assignments -- Student enrollment tracking - -## Security Features - -- Password hashing with bcrypt -- Session management -- CSRF protection -- Input validation and sanitization -- SQL injection prevention with SQLAlchemy ORM - -## Development - -### Running in Development Mode - -```bash -export FLASK_ENV=development -python app.py -``` - -### Adding New Features - -1. Create models in `app/models/` -2. Add routes in `app/routes/` -3. Create forms if needed in `app/forms/` -4. Update templates in `app/templates/` - -## Production Deployment - -### Environment Setup - -1. **Set production variables:** -```env -FLASK_ENV=production -SECRET_KEY= -DATABASE_URL= -``` - -2. **Use production WSGI server:** -```bash -pip install gunicorn -gunicorn -w 4 -b 0.0.0.0:5000 app:app -``` - -3. **Configure reverse proxy** (nginx/Apache) - -## Troubleshooting - -### Common Issues - -1. **Database connection errors:** - - Check DATABASE_URL string - - Ensure directory permissions - -2. **Login issues:** - - Verify admin user exists - - Check password hash - -3. **Static files not loading:** - - Ensure blueprint route registration - - Check file permissions - -## Contributing - -1. Fork the repository -2. Create feature branch -3. Make changes -4. Test thoroughly -5. Submit pull request - -## License - -This project is part of the Edu-Space educational management system. - -## Support - -For support and questions: -- Email: admin@edu-space.com -- Documentation: Check inline comments and README files +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**. --- -**Note**: This admin panel is designed to work alongside the Spring Boot microservice. Ensure both services are running for complete functionality. \ No newline at end of file +## 🏛️ 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. + +--- + +## 🛠️ 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:** + ```bash + 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): + ```powershell + python -m venv venv + .\venv\Scripts\Activate.ps1 + ``` + * En Linux / macOS: + ```bash + python3 -m venv venv + source venv/bin/activate + ``` + +3. **Instalar dependencias:** + ```bash + pip install -r requirements.txt + ``` + +4. **Configurar variables de entorno (`.env`):** + Crear o editar el archivo `.env` en la raíz del proyecto: + ```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: + ```bash + python init_db.py + ``` + +6. **Compilar catálogos de traducción (opcional si se modifican textos):** + ```bash + pybabel compile -d translations + ``` + +7. **Iniciar el servidor de desarrollo:** + ```bash + 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 + +```text +admin-edu-space/ +├── app/ +│ ├── __init__.py # Factoría de la aplicación Flask y extensiones +│ ├── models/ # Modelos de base de datos SQLAlchemy +│ │ ├── user.py # Modelo de usuario +│ │ ├── role.py # Roles y matriz de permisos RBAC +│ │ ├── classroom.py # Aulas y capacidades físicas / virtuales +│ │ ├── building.py # Edificios y sedes institucionales +│ │ ├── career.py # Carreras universitarias +│ │ ├── subject.py # Asignaturas y comisiones +│ │ └── reservation.py # Reservas horarias y turnos +│ ├── routes/ # Controladores y rutas (Blueprints) +│ │ ├── auth.py # Autenticación, login y perfil +│ │ ├── main.py # Dashboard y métricas generales +│ │ ├── admin.py # Gestión de usuarios, roles e importación +│ │ ├── classrooms.py # ABM de aulas y equipamiento +│ │ ├── buildings.py # Gestión de sedes y edificios +│ │ ├── schedule.py # Calendario, cartelera del día y reservas +│ │ └── genetic_algorithm.py # Optimizador genético de aulas +│ ├── services/ # Servicios de negocio +│ │ └── sheets_importer.py # Parser y sincronizador de Google Sheets +│ ├── forms/ # Formularios Flask-WTF +│ ├── templates/ # Plantillas Jinja2 (Bootstrap 5) +│ ├── static/ # Archivos CSS, JS e imágenes +│ └── utils/ # Decoradores de autorización y utilidades +├── config/ # Ajustes de configuración +├── translations/ # Catálogos de traducción (es / en) +├── init_db.py # Script DDL y semillero inicial +├── CHANGELOG_SESSION.md # Registro cronológico detallado de cambios +├── requirements.txt # Dependencias del proyecto +├── .env.example # Plantilla de variables de entorno +└── app.py # Punto de entrada de la aplicación +``` + +--- + +## 📄 Licencia + +Este proyecto forma parte del sistema de gestión institucional y educativa de **UniCABA**. Todos los derechos reservados. \ No newline at end of file