diff --git a/.gitignore b/.gitignore index bc19353..a985e33 100644 --- a/.gitignore +++ b/.gitignore @@ -224,4 +224,7 @@ legacy_admin-edu-space/ .schemathesis/ AlumnosLS -prerrequisitos \ No newline at end of file +prerrequisitos + +.credentials +.credenciales \ No newline at end of file diff --git a/AGENTS.md b/AGENTS.md new file mode 100644 index 0000000..524c07e --- /dev/null +++ b/AGENTS.md @@ -0,0 +1,57 @@ +# AGENTS.md - admin-edu-space (Rama dev / MVP) +Plataforma web de gestión de espacios áulicos, sincronización académica y asignación de cursadas para UniCABA, diseñada para reemplazar el uso de planillas Excel en Bedelía, orquestar calendarios en tiempo real y conectarse con Moodle 4.1 y Google Workspace. + +## Stack y Estructura +- **Arquitectura**: Desacoplada (Backend Core REST API + Frontend BFF). +- **Backend Core**: Python 3.12, Flask 3.1, SQLAlchemy ORM, SQLite / PostgreSQL 15, Marshmallow/Pydantic DTOs, Flask-JWT-Extended (HS256 stateless). +- **Frontend BFF**: Node.js v20+, Express.js, motor de plantillas Nunjucks, cliente Axios con interceptores de autorización Bearer, Bootstrap 5 + Vanilla CSS. +- **Integraciones Clave**: + - Google OAuth 2.0 para autenticación institucional restringida a `@unicaba.edu.ar`. + - Moodle 4.1 REST API (`core_webservice_*`, `enrol_*`) con cola asíncrona resiliente (`MoodleSyncTask`), reintentos exponenciales, Dead Letter Queue (DLQ) y capa de caché híbrida (`CacheService` en Redis / memoria). + - Motor de Notificaciones SMTP dinámico (`EmailService`) con credenciales cifradas con Fernet en base de datos. + - Importador oficial de Google Sheets (`sheets_importer.py`) para ingesta masiva inicial. +- **Entorno de Ejecución**: Contenedores Linux LXC en Proxmox con Nginx como proxy inverso y terminación SSL (entorno productivo institucional: `eduspace.oemspot.com.ar`). + +## Comandos de Desarrollo y Verificación +- **Levantar Backend (Flask API :5000)**: + ```powershell + cd backend + .\venv\Scripts\activate + flask run --port 5000 + ``` +- **Levantar Frontend BFF (Express :3000)**: + ```powershell + cd frontend + npm run dev + ``` +- **Ejecutar Suite de Pruebas Automatizadas (Backend)**: + ```powershell + cd backend + .\venv\Scripts\activate + pytest tests -v + ``` +- **Auditoría Automatizada de Seguridad (SAST / SCA / DAST)**: + ```powershell + .\security_audit.bat --no-pause + ``` + +## Convenciones de Desarrollo +- Nombres de variables, funciones, clases, tablas, endpoints y commits estrictamente en **inglés**. +- Los endpoints de la API deben seguir estándares RESTful puros bajo `/api/v1/` retornando exclusivamente JSON. +- Interfaz gráfica de usuario, etiquetas de formularios, mensajes de error y documentación operativa exclusivamente en **español**. + +## Reglas de Dominio y Trampas Conocidas +- **Reemplazo del Excel de Bedelía**: La gestión operativa diaria debe realizarse en la app a través del circuito secuencial de 9 pasos (Sedes -> Aulas -> Ciclos Lectivos -> Carreras -> Asignaturas -> Comisiones -> Profesores -> Alumnos -> Reservas). Las comisiones heredan y exponen la Carrera de la asignatura para trazabilidad por plan de estudios. Las hojas de cálculo son únicamente para importación masiva de datos iniciales. +- **Sincronización con Moodle**: Prohibido hacer peticiones directas y síncronas bloqueantes a Moodle dentro de los controladores de usuario. Utilizar siempre `CacheService` para lecturas y encolar en `MoodleSyncTask` para escrituras. +- **Matriz de Conflictos de Reservas**: Una reserva no puede guardarse si genera superposición física de aula presencial, sobrepasa el aforo máximo o solapa al docente (salvo excepción justificada por co-docencia activa). +- **Restricción Diaria de Alumnos**: Un alumno no puede matricularse en dos materias regulares en el mismo día, a menos que sea un curso corto (`is_short_course`) o posea autorización expresa de Bedelía (`allow_same_day_exception`). +- **Autenticación**: Los flujos de acceso pasan por tokens JWT transportados en cookies seguras `HttpOnly`. + +## Límites +- **SIEMPRE**: Lee `docs/constitution.md` y la especificación activa antes de proponer o modificar código. +- **PREGUNTA ANTES DE**: Añadir nuevas dependencias a `requirements.txt` o `package.json`, alterar el esquema relacional de la base de datos o cambiar la estrategia de caché. +- **NUNCA**: Expongas contraseñas, tokens de Moodle, secretos de API o el contenido del archivo `.credenciales` en el código fuente, commits o logs públicos. + +## Memoria +- Al empezar, lee `MEMORY.md` para conocer el estado actual de la rama y los objetivos del sprint. +- Al terminar cualquier tarea, actualízalo resumiendo las decisiones tomadas y los siguientes pasos. \ No newline at end of file diff --git a/CHANGELOG.md b/CHANGELOG.md index 99361ee..12e2dd3 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -6,13 +6,37 @@ El formato está basado en [Keep a Changelog](https://keepachangelog.com/es-ES/1 --- ## [Unreleased] -### Planificado (Fase 6 del Roadmap MVP) +### Planificado (Fase 6 del Roadmap) - **Despliegue e Infraestructura (Fase 6):** `docker-compose.yml` productivo orquestando Flask (Gunicorn), Node.js BFF (PM2) y PostgreSQL 15, con proxy inverso Nginx, SSL/TLS y compresión. - **Sincronización Continua Moodle (Fase 6):** Automatización de workers persistentes en background para el procesamiento continuo de la cola de Web Services Moodle 4.1. - **Pruebas de Carga y Hardening (Fase 6):** Pruebas de estrés de concurrencia y validación final de producción. --- +## [3.3.0] - 2026-10-07 +### Añadido +- **Estandarización del Flujo Secuencial de Bedelía (9 Pasos Operativos):** + - Formalización del circuito paso a paso para reemplazar el archivo Excel manual de uso diario: + 1. **Sede / Edificio (`/buildings/list_buildings`):** Creación y administración del inmueble universitario. + 2. **Aula (`/classrooms/list_classrooms`):** Alta de espacios físicos y aulas virtuales con control de aforo y recursos. + 3. **Ciclo Lectivo (`/admin/academic_terms_list`):** Creación del período lectivo y activación del cuatrimestre corriente. + 4. **Carrera / Titulación (`/admin/careers_list`):** Creación y administración del programa académico institucional. + 5. **Asignatura / Materia (`/admin/subjects_list`):** Alta en plan de estudios asociada obligatoriamente a la Carrera. + 6. **Comisión (`/admin/commissions_list`):** Creación de comisiones con cupos y vinculación a la materia, ciclo lectivo y carrera asociada, con filtros directos por titulación. + 7. **Asociar Profesores (`/admin/commission_detail`):** Asignación del cuerpo docente y co-docentes con roles de cátedra. + 8. **Asociar Alumnos (`/admin/commission_detail`):** Matriculación con validación de restricciones horarias y excepciones de Bedelía. + 9. **Reserva de Espacios (`/schedule/add_reservation` o Drag & Drop en `/schedule/calendar_view`):** Asignación de aula y franja horaria en 1 clic con chequeo de conflictos. +- **Alineamiento de Documentación con SSD (Software System Design):** + - **Constitución del Sistema (`docs/constitution.md`):** Actualización con principios innegociables: arquitectura desacoplada REST + BFF, reemplazo definitivo del Excel, matriz de conflictos, caché de Moodle 4.1, y RBAC seguro. + - **Manual de Agentes (`AGENTS.md`):** Definición precisa del stack, comandos de desarrollo y pruebas, convenciones y límites. + - **Memoria Operativa (`MEMORY.md`):** Sincronización del estado de desarrollo para el Sprint Bedelía MVP. + - **Roadmap del Proyecto (`ROADMAP.md`):** Creación en la raíz del proyecto detallando el progreso y las metas del MVP. + - **Guía Operativa por Rol (`docs/GUIA_OPERATIVA_BEDELIA_Y_ROADMAP_FUTURO.md`):** Manual exhaustivo con paso a paso para Bedelía, Docentes y Alumnos. +- **Mantenimiento del Importador de Google Sheets:** + - Preservación del servicio `sheets_importer.py` para ingesta masiva inicial sin fricción para el personal. + +--- + ## [3.2.0] - 2026-09-23 ### Añadido - **Función de Reinicialización Total del Sistema (`POST /api/v1/admin/system/reset`):** diff --git a/MEMORY.md b/MEMORY.md new file mode 100644 index 0000000..a822412 --- /dev/null +++ b/MEMORY.md @@ -0,0 +1,31 @@ +# MEMORY.md - admin-edu-space +Memoria del proyecto entre sesiones para la rama `dev`. + +## Estado actual +- Fases 0 a 5.1 del Roadmap completadas y estabilizadas: + - Arquitectura desacoplada: Backend Flask REST API (:5000) + Frontend BFF Node.js/Express (:3000). + - Cobertura 100% ABM: Sedes/Edificios, Aulas (físicas/virtuales), Ciclos Lectivos, Carreras, Materias, Comisiones y Reservas. + - Matriz integral de conflictos (físico, docente con co-docencia, aforo y restricción diaria del alumno). + - Libro de Calificaciones (*Gradebook*) con actas de regularidad inmutables. + - Autenticación híbrida (Google OAuth 2.0, Moodle SSO, Local) y Modo Impersonación. + - Reinicialización segura del sistema con contraseña de Administrador. +- **Sprint Activo: MVP del Sistema de Bedelía — Reemplazo Definitivo del Excel**: + - Reemplazar la planilla Excel manual como herramienta operativa diaria de Bedelía. + - La plataforma asume el rol de fuente única de verdad para la asignación y gestión de cursadas. + - Las planillas/Google Sheets se mantienen únicamente para importación masiva de datos iniciales. + +## Decisiones (y por qué) +- **Flujo Secuencial de Bedelía (9 Pasos)**: Estandarizar la carga operativa en: 1) Sede -> 2) Aula -> 3) Ciclo Lectivo -> 4) Carrera -> 5) Materia (vinculada a Carrera) -> 6) Comisión (asociada a Materia, Carrera y Ciclo) -> 7) Profesores -> 8) Alumnos -> 9) Reserva de Espacio. Esto asegura consistencia e integridad relacional. +- **Asociación Explícita de Carreras**: Toda Asignatura se vincula a su Carrera y toda Comisión hereda y expone la Carrera, permitiendo filtros y búsquedas específicas por titulación. +- **Importador de Google Sheets Preservado**: Se conserva como ingestor inicial masivo sin fricción para no interrumpir el flujo actual del personal. +- **Guía Operativa por Rol**: Documentar explícitamente el procedimiento para Bedelía, Docentes y Alumnos para facilitar la adopción inmediata. + +## Aprendizajes y errores a evitar +- **Colisiones Virtuales**: En aulas virtuales no debe aplicarse colisión física horaria; múltiples comisiones pueden cursar simultáneamente con enlaces independientes. +- **Manejo de Estados Vacíos (Empty States)**: Proteger siempre las vistas de plantillas en Nunjucks contra colecciones vacías para evitar errores 500 cuando se reinicializa la base. +- **Seguridad de Secretos**: Mantener `.credenciales` y `.env` estrictamente fuera del índice de Git. + +## Próximos pasos +1. Finalizar la actualización de documentación SSD (ROADMAP.md, CHANGELOG.md, Guía Operativa). +2. Revisar y pulir en el código cada uno de los 8 pasos del flujo secuencial de Bedelía. +3. Ejecutar pruebas automatizadas y validación en el entorno de pruebas usando las herramientas de navegador / E2E. \ No newline at end of file diff --git a/ROADMAP.md b/ROADMAP.md new file mode 100644 index 0000000..5f01152 --- /dev/null +++ b/ROADMAP.md @@ -0,0 +1,104 @@ +# ROADMAP OFICIAL — Sistema Integral UniCABA (Admin Edu-Space) +## Gestión de Espacios Áulicos, Asignación de Comisiones y Operatoria de Bedelía + +**Institución:** Universidad de la Ciudad de Buenos Aires (UniCABA) +**Versión:** 3.3.0 (Sprint MVP Bedelía) +**Fecha de Actualización:** 07 de Octubre de 2026 +**Rama Base:** `dev` + +--- + +## 🗺️ Visión del Proyecto y Objetivo del Sprint +Consolidar la plataforma **Admin Edu-Space** como el sistema integral de gestión áulica y académica para **UniCABA**, **reemplazando definitivamente el archivo Excel que el personal de Bedelía utiliza para su gestión diaria**. A partir de este hito, la plataforma se convierte en la fuente única de verdad para la asignación de espacios, horarios y docentes, relegando las planillas externas a un simple mecanismo de importación masiva de datos iniciales. + +--- + +## 📊 Estado Global de Progreso + +``` +Fase 0: Desacople y Arquitectura Base [████████████████████] 100% (Completado) +Fase 1: Paridad Legacy, Virtualidad y Dashboards[████████████████████] 100% (Completado) +Fase 2: Co-docencia y Matriz de 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 5.1: Bedelía UX, ABMs 100% y Reset Seguro [████████████████████] 100% (Completado) +Sprint Activo: Flujo Bedelía & Reemplazo Excel [████████████████░░░░] 80% (En Curso) +Fase 6: Despliegue en Servidores y Hardening [███████░░░░░░░░░░░░░] 35% (Planificado) +``` + +--- + +## 🚀 Detalle de Fases y Entregables + +### Fase 0: Desacople y Arquitectura Base ✅ *(Completada)* +- [x] Backend Flask como API REST pura bajo `/api/v1/` retornando exclusivamente JSON. +- [x] Frontend BFF en Node.js + Express con renderizado de plantillas Nunjucks. +- [x] Autenticación desacoplada con tokens JWT en Cookie `HttpOnly` segura. +- [x] Pipeline de seguridad `SecurityFilterChain` con blindaje OWASP y rate limiting. +- [x] Cliente Axios centralizado con interceptor Bearer token automático. + +### Fase 1: Paridad Legacy, Virtualidad y Dashboards Especializados ✅ *(Completada)* +- [x] Importador de Google Sheets corregido: eliminación de colisiones en aulas virtuales múltiples (`Campus Virtual · VIRTUAL`). +- [x] Dashboards específicos e interactivos para **Bedelía**, **Docente**, **Alumno** y **Administrador**. +- [x] Cartelera del Día (`today_schedule`) con bloques horarios (07:00 a 22:00 hs) y filtros dinámicos. +- [x] Generación y persistencia de enlaces de Google Meet institucional por comisión y reserva. + +### Fase 2: Co-docencia, Matriz de Conflictos y Regla Diaria ✅ *(Completada)* +- [x] Tabla relacional `commission_teachers` para soportar múltiples docentes por comisión (titulares, adjuntos, ayudantes). +- [x] Matriz de conflictos con validación física estricta, chequeo de aforo de seguridad y superposición docente. +- [x] Excepción de superposición justificada por co-docencia activa. +- [x] Regla restrictiva de cursada diaria para estudiantes con bypass por curso corto (`is_short_course`) o excepción expresa de Bedelía. + +### Fase 3: Hitos Evaluativos y Libro de Calificaciones (*Gradebook*) ✅ *(Completada)* +- [x] Programación y calendario de parciales, recuperatorios, entregas y exámenes finales. +- [x] Matriz de carga rápida de notas con autoguardado asíncrono y promedios en tiempo real. +- [x] Cierre formal e inmutable de actas con número oficial (`ACTA-YYYY-Sem-ID`) y registro de auditoría. +- [x] Consulta de calificaciones y estado de regularidad para alumnos. + +### Fase 4: UI/UX Avanzada para Bedelía & Modo Impersonación ✅ *(Completada)* +- [x] Grilla semanal interactiva (Drag & Drop) con FullCalendar y barra lateral de comisiones sin aula. +- [x] Detección visual de colisiones en tiempo real con reversión automática y mensajes de alerta. +- [x] Modo de impersonación administrativa (*login as*) con cabecera `X-Impersonate-User` y banner visual ámbar. +- [x] Integración de Optimizador Genético heurístico acoplado a turnos académicos reales. + +### Fase 5: Integración Auth, Email y Moodle 4.1 ✅ *(Completada)* +- [x] Panel de configuración global administrativa con contraseñas cifradas vía Fernet. +- [x] Capa de caché híbrida (`CacheService` en Redis/memoria) y cola asíncrona tolerante a fallos (`MoodleSyncTask` con DLQ). +- [x] Autenticación híbrida: Google OAuth 2.0 (`@unicaba.edu.ar`), Moodle SSO y Login Local con fallback. +- [x] Motor de notificaciones transaccionales por email (`EmailService`) para docentes. + +### Fase 5.1: Cobertura ABM 100% y Mantenimiento Seguro ✅ *(Completada)* +- [x] ABMs completos y protegidos para **Sedes/Edificios**, **Aulas (físicas/virtuales)**, **Ciclos Lectivos**, **Carreras**, **Materias**, **Comisiones** y **Reservas**. +- [x] Módulo de Reinicio Total del Sistema (`POST /api/v1/admin/system/reset`) con validación obligatoria de contraseña de Administrador y preservación de cuentas y roles RBAC. +- [x] Soporte de inicialización limpia (`--empty-academic` / `--no-demo`) para arranque desde cero. + +--- + +### Sprint Activo: Flujo Completo de Bedelía & Reemplazo Definitivo de Excel 🏛️ ⚡ *(En Curso)* +* **Objetivo:** Permitirle a Bedelía gestionar íntegramente el ciclo de asignaciones académicas sin depender de planillas de cálculo, estandarizando el flujo de trabajo en 9 pasos secuenciales: + 1. [x] **Paso 1 — Sede / Edificio:** Alta y mantenimiento del espacio físico (`/buildings/list_buildings`). + 2. [x] **Paso 2 — Aula (Física / Virtual):** Definición de espacios, capacidades de aforo y recursos (`/classrooms/list_classrooms`). + 3. [x] **Paso 3 — Ciclo Lectivo:** Definición del período académico y activación del cuatrimestre vigente (`/admin/academic_terms_list`). + 4. [x] **Paso 4 — Carrera / Titulación:** Alta del programa académico o plan de estudios (`/admin/careers_list`). + 5. [x] **Paso 5 — Asignatura / Materia:** Alta en el plan de estudios vinculada obligatoriamente a la Carrera (`/admin/subjects_list`). + 6. [x] **Paso 6 — Comisión:** Creación de comisiones vinculadas a la materia, carrera y ciclo lectivo con filtrado y visualización contextual (`/admin/commissions_list`). + 7. [x] **Paso 7 — Asociar Profesores:** Asignación previa del equipo de cátedra (titulares y adjuntos) con roles específicos (`/admin/commission_detail`). + 8. [x] **Paso 8 — Asociar Alumnos:** Matriculación de estudiantes en la comisión con validación de restricciones horarias (`/admin/commission_detail`). + 9. [x] **Paso 9 — Reserva de Espacios:** Asignación ágil del aula (física o virtual) a la comisión, con validación de conflictos en 1 clic (`/schedule/add_reservation` o Drag & Drop en `/schedule/calendar_view`). +* **Canal de Importación de Planillas:** + - [x] Preservación del importador de Google Sheets (`sheets_importer.py`) como herramienta de carga masiva inicial. + - [ ] Compatibilidad futura con columnas de enlace virtual explícito y fecha específica en el sheet. +* **Documentación Operativa:** + - [x] Manual del Personal de Bedelía con el flujo secuencial de 9 pasos. + - [x] Manual del Docente (agenda, Google Meet y actas de notas). + - [x] Manual del Estudiante (consulta de aulas y exámenes). +* **Validación en Entorno Real:** + - [ ] Pruebas E2E en navegador validando el circuito completo en el entorno de pruebas LXC. + +--- + +### Fase 6: Despliegue en Servidores y Hardening 🏢 *(Planificada)* +- [ ] Automatización de workers persistentes en systemd para la cola asíncrona de Moodle. +- [ ] Configuración optimizada de `docker-compose.yml` de producción. +- [ ] Pruebas de estrés de concurrencia y validación final de performance sub-segundo. diff --git a/backend/app/models/subject.py b/backend/app/models/subject.py index 5cfcd65..2f6cc51 100644 --- a/backend/app/models/subject.py +++ b/backend/app/models/subject.py @@ -36,6 +36,11 @@ class Subject(db.Model): 'updated_at': self.updated_at.isoformat() if self.updated_at else None } + @property + def career(self): + """Helper to access career_obj directly""" + return self.career_obj + def __repr__(self): return f'' @@ -116,6 +121,18 @@ class Commission(db.Model): return "Sin asignar" return ", ".join([f"{t['name']} ({t['role']})" for t in t_list]) + @property + def career(self): + return self.subject.career_obj if self.subject else None + + @property + def career_name(self): + return self.subject.career_obj.name if (self.subject and self.subject.career_obj) else 'Carrera General' + + @property + def career_id(self): + return self.subject.career_id if self.subject else None + # Unique constraint __table_args__ = (db.UniqueConstraint('subject_id', 'code', 'semester', 'year'),) @@ -124,6 +141,8 @@ class Commission(db.Model): return { 'id': self.id, 'subject_id': self.subject_id, + 'career_id': self.career_id, + 'career_name': self.career_name, 'code': self.code, 'semester': self.semester, 'year': self.year, diff --git a/backend/app/routes/api/admin.py b/backend/app/routes/api/admin.py index 775c12d..8bcd6cf 100644 --- a/backend/app/routes/api/admin.py +++ b/backend/app/routes/api/admin.py @@ -182,12 +182,15 @@ def get_careers(): def get_commissions(): search = request.args.get('search', '').strip().lower() subject_id = request.args.get('subject_id', type=int) + career_id = request.args.get('career_id', type=int) shift = request.args.get('shift', '').strip() active = request.args.get('active', '').strip().lower() query = Commission.query if subject_id: query = query.filter(Commission.subject_id == subject_id) + if career_id: + query = query.join(Subject, Commission.subject_id == Subject.id).filter(Subject.career_id == career_id) if shift: query = query.filter(Commission.shift == shift) if active == 'true': @@ -198,6 +201,10 @@ def get_commissions(): commissions = query.order_by(Commission.id.asc()).all() subjects = Subject.query.order_by(Subject.name.asc()).all() + from app.models.career import Career + careers = Career.query.order_by(Career.name.asc()).all() + careers_data = [{'id': cr.id, 'name': cr.name, 'code': cr.code} for cr in careers] + commissions_data = [] for c in commissions: if search: @@ -206,9 +213,8 @@ def get_commissions(): if search not in s_name and search not in c_code: continue - career_name = 'Carrera General' - if c.subject and hasattr(c.subject, 'career') and c.subject.career: - career_name = c.subject.career.name + career_name = c.career_name if hasattr(c, 'career_name') else 'Carrera General' + career_id_val = c.career_id if hasattr(c, 'career_id') else (c.subject.career_id if c.subject else None) commissions_data.append({ 'id': c.id, @@ -217,6 +223,7 @@ def get_commissions(): 'subject_id': c.subject_id, 'subject_name': c.subject.name if c.subject else 'Sin materia', 'subject_code': c.subject.code if c.subject else '-', + 'career_id': career_id_val, 'career_name': career_name, 'semester': getattr(c, 'semester', '1C') or '1C', 'year': getattr(c, 'year', 2026) or 2026, @@ -235,11 +242,12 @@ def get_commissions(): subjects_data = [] for s in subjects: - c_name = s.career.name if (hasattr(s, 'career') and s.career) else 'Carrera General' + c_name = s.career_obj.name if (hasattr(s, 'career_obj') and s.career_obj) else 'Carrera General' subjects_data.append({ 'id': s.id, 'name': s.name, 'code': s.code, + 'career_id': s.career_id, 'career': c_name, 'career_name': c_name }) @@ -253,7 +261,8 @@ def get_commissions(): 'total': len(commissions_data), 'commissions': commissions_data, 'subjects': subjects_data, - 'academic_terms': terms_data + 'academic_terms': terms_data, + 'careers': careers_data }), 200 # --------------------------------------------------------- diff --git a/CHANGELOG_MVP.md b/docs/CHANGELOG_MVP.md similarity index 100% rename from CHANGELOG_MVP.md rename to docs/CHANGELOG_MVP.md diff --git a/ESTADO_MIGRACION_Y_ARQUITECTURA_OBJETIVO.md b/docs/ESTADO_MIGRACION_Y_ARQUITECTURA_OBJETIVO.md similarity index 100% rename from ESTADO_MIGRACION_Y_ARQUITECTURA_OBJETIVO.md rename to docs/ESTADO_MIGRACION_Y_ARQUITECTURA_OBJETIVO.md diff --git a/docs/GUIA_OPERATIVA_BEDELIA_Y_ROADMAP_FUTURO.md b/docs/GUIA_OPERATIVA_BEDELIA_Y_ROADMAP_FUTURO.md index 7644b6c..0ee5d94 100644 --- a/docs/GUIA_OPERATIVA_BEDELIA_Y_ROADMAP_FUTURO.md +++ b/docs/GUIA_OPERATIVA_BEDELIA_Y_ROADMAP_FUTURO.md @@ -1,208 +1,210 @@ -# GUÍA OPERATIVA DE SISTEMA, RELEVAMIENTO DE BEDELÍA Y ROADMAP DE EVOLUCIÓN +# GUÍA OPERATIVA DE SISTEMA, MANUAL DE PROCEDIMIENTOS Y ROADMAP DE EVOLUCIÓN ## Plataforma Admin Edu-Space — UniCABA -**Documento de Operaciones y Prospectiva Tecnológica** -**Versión:** 1.0 (Producción MVP) +**Documento de Operaciones, Flujo Secuencial de Bedelía y Manual de Usuario** +**Versión:** 3.3.0 (Producción MVP) +**Institución:** Universidad de la Ciudad de Buenos Aires (UniCABA) --- -## 1. Guía de Procedimientos del Programa por Rol +## 1. Guía de Procedimientos Operativos por Rol -### 1.1. Para el Personal de Bedelía (Gestores de Espacios) +--- -El personal de Bedelía es el corazón operativo de la infraestructura física universitaria. Su flujo de trabajo en Edu-Space sigue el siguiente ciclo: +### 1.1. Para el Personal de Bedelía (Gestores de Espacios y Cursadas) + +El personal de Bedelía es el corazón operativo de la infraestructura física y académica. El objetivo central de este sprint es **reemplazar definitivamente el archivo Excel que Bedelía utiliza actualmente para sus gestiones diarias**. A partir de ahora, la plataforma es la fuente única de verdad para administrar sedes, aulas, ciclos lectivos, materias, comisiones, docentes, alumnos y reservas. ``` - [ Inicio de Cuatrimestre ] - │ - ▼ - 1. Configuración del Ciclo Lectivo - (Fechas de inicio, fin, feriados y recesos) - │ - ▼ - 2. Carga/Actualización de Aulas y Sede - (Capacidad física, proyectores, computadoras, AC) - │ - ▼ - 3. Importación o Carga de Comisiones y Materias - (Docente a cargo, alumnos inscriptos, días y turnos) - │ - ▼ - 4. Ejecución del Optimizador Genético -(Distribución automatizada sin colisiones ni solapamientos) - │ - ▼ - 5. Publicación y Monitoreo en Tiempo Real -(Cartelera digital activa y gestión de contingencias/reparaciones) + [ 1. Sede / Edificio ] ──▶ [ 2. Aula (Física/Virtual) ] + │ │ + ▼ ▼ + [ 3. Ciclo Lectivo ] ──▶ [ 4. Carrera / Titulación ] + │ │ + ▼ ▼ + [ 5. Asignatura / Materia ] (Vinculada a la Carrera) + │ + ▼ + [ 6. Crear Comisión ] (Vinculada a Materia, Carrera y Ciclo) + │ + ┌───────────────┴───────────────┐ + ▼ ▼ +[ 7. Asociar Profesores ] [ 8. Asociar Alumnos ] + │ │ + └───────────────┬───────────────┘ + ▼ + [ 9. Reserva de Espacios ] + (Asignación en Aula & Horario) ``` -#### Paso a Paso Operativo: -1. **Configuración de Ciclo Lectivo:** - - Navegar al menú **Ciclos Lectivos** en la barra lateral. - - Definir el ciclo activo (ej: `2026 - 2C`), fijando las fechas de inicio de clases, exámenes finales y cierres de actas. -2. **Inventario de Aulas y Recursos:** - - En **Gestión de Aulas**, registrar cada aula con su capacidad real de asientos, tipo de pizarrón, presencia de proyector, conectividad de red y climatización. - - Marcar aulas en estado `Mantenimiento` en caso de fallas edilicias para excluirlas del algoritmo de asignación. -3. **Carga y Verificación de Comisiones:** - - Ingresar a **Comisiones / Horarios** para verificar la nómina de materias activas, sus horarios (Turno Mañana, Tarde o Noche) y la cantidad estimada de matriculados. -4. **Asignación Asistida por IA (Optimizador Genético):** - - Acceder al módulo **Optimizador Genético**. - - Seleccionar el ciclo lectivo y pulsar **"Ejecutar Optimización"**. - - El sistema evaluará millones de combinaciones en segundos, priorizando que los grupos más numerosos ocupen las aulas mayores y minimizando distancias de traslado de docentes. - - Bedelía puede revisar el cronograma propuesto y confirmarlo con un clic. -5. **Atención de Cambios de Último Momento:** - - Si un docente requiere cambio de aula o si un equipo multimedia falla, Bedelía ingresa a **Reservas / Asignaciones**, busca la franja horaria y reubica la comisión en un aula alternativa libre sugerida por el sistema. +--- + +#### 📋 Flujo Secuencial de 9 Pasos (Paso a Paso Detallado): + +#### Paso 1: Crear Sitio / Sede (Edificio) +1. **Acceso:** Ir al menú lateral ➔ **Espacios & Sedes** (o **Administración**) ➔ **Sedes / Edificios** (`/buildings/list_buildings`). +2. **Acción:** Presionar el botón `+ Nueva Sede`. +3. **Completar Datos:** + - **Nombre:** Ej. *Sede Central UniCABA*. + - **Dirección / Código:** Ej. *Paseo Colón 255* / *SEDE-CENTRAL*. + - **Estado:** Activo. +4. **Guardar:** Presionar `Guardar Sede`. El edificio queda registrado para albergar aulas físicas. + +#### Paso 2: Crear Aula (Espacios Físicos o Virtuales) +1. **Acceso:** Ir al menú lateral ➔ **Espacios & Sedes** ➔ **Catálogo de Aulas** (`/classrooms/list_classrooms`). +2. **Acción:** Presionar el botón `+ Nueva Aula` (`/classrooms/add_classroom`). +3. **Seleccionar Tipo de Espacio:** + - **Espacio Físico:** Seleccionar la Sede creada en el Paso 1, indicar el Piso (ej. *1° Piso*), el Código/Nombre del aula (ej. *Aula 101*), Capacidad máxima de bancos (ej. *40*) y Recursos (Proyector, Aire Acondicionado, PCs). + - **Espacio Virtual:** Marcar el casillero `¿Es espacio virtual / remoto?`. El sistema lo vinculará al entorno institucional remoto (Campus Virtual). +4. **Guardar:** Presionar `Crear Aula`. Queda lista para recibir reservas. + +#### Paso 3: Crear Ciclo Lectivo (Período Académico) +1. **Acceso:** Ir al menú lateral ➔ **Académica** ➔ **Ciclos Lectivos** (`/admin/academic_terms_list`). +2. **Acción:** Presionar el botón `+ Nuevo Ciclo Lectivo`. +3. **Completar Datos:** + - **Nombre:** Ej. *2026 - 2° Cuatrimestre* o *2026 - 1C*. + - **Fecha de Inicio y Fin:** Fechas formales del cuatrimestre. + - **Activar:** Marcar como `Ciclo Actual / Activo`. Todas las nuevas comisiones se asignarán por defecto a este ciclo. +4. **Guardar:** Presionar `Guardar Período`. + +#### Paso 4: Crear Carrera (Programa Académico / Titulación) +1. **Acceso:** Ir al menú lateral ➔ **Académica** ➔ **Carreras** (`/admin/careers_list`). +2. **Acción:** Presionar el botón `+ Nueva Carrera`. +3. **Completar Datos:** + - **Nombre de la Carrera:** Ej. *Licenciatura en Tecnologías Informáticas* o *Tecnicatura Universitaria en Ciberseguridad*. + - **Código Institucional:** Ej. *LTI* o *TUC*. + - **Descripción:** Objetivos del plan de estudios. +4. **Guardar:** Presionar `Crear Carrera`. Las materias y comisiones quedarán agrupadas bajo esta carrera. + +#### Paso 5: Crear Asignatura / Materia (Vinculada a la Carrera) +1. **Acceso:** Ir al menú lateral ➔ **Académica** ➔ **Asignaturas** (`/admin/subjects_list`). +2. **Acción:** Presionar el botón `+ Nueva Asignatura`. +3. **Completar Datos:** + - **Código de Materia:** Ej. *PROG-VANG-2026*. + - **Nombre de la Materia:** Ej. *Programación de Vanguardia*. + - **Carrera Vinculada:** Seleccionar obligatoriamente la Carrera creada en el Paso 4 (ej. *Licenciatura en Tecnologías Informáticas*). + - **Departamento / Créditos:** Indicar departamento y créditos académicos. + - **¿Es Curso Corto / Taller?:** Marcar si aplica para habilitar excepciones de cursada en el mismo día. +4. **Guardar:** Presionar `Crear Asignatura`. + +#### Paso 6: Crear Comisión (Asociada a Materia, Carrera y Ciclo) +1. **Acceso:** Ir al menú lateral ➔ **Académica** ➔ **Comisiones** (`/admin/commissions_list`). +2. **Acción:** Presionar el botón `+ Nueva Comisión`. +3. **Completar Datos:** + - **Asignatura / Materia:** Seleccionar la Asignatura creada en el Paso 5 (el sistema muestra su carrera asociada). + - **Código de Comisión:** Ej. *Comisión A* o *K3001*. + - **Ciclo Lectivo:** Seleccionar el ciclo activo creado en el Paso 3. + - **Turno:** *Mañana* (08:00 - 12:00), *Tarde* (14:00 - 18:00) o *Noche / Vespertino* (18:30 - 22:30). + - **Docente Titular (Opcional en este paso):** Puede asignarse de inmediato o más tarde. + - **Cupo Máximo:** Cantidad estimada de matriculados (ej. *35*). + - **Enlace Virtual:** Enlace opcional de Google Meet, Zoom o Teams si cursará en modalidad remota o híbrida. +4. **Guardar:** Presionar `Crear y Asociar Comisión`. La comisión hereda la carrera y el plan de estudios. + +#### Paso 7: Asociar Profesores (Equipo Docente / Co-docencia) +1. **Acceso:** En la lista de comisiones (`/admin/commissions_list`), hacer clic en la tuerca o nombre de la comisión para ingresar al **Detalle de Comisión** (`/admin/commission_detail?id=...`). +2. **Sección:** Localizar la tarjeta **"Equipo Docente / Cátedra"**. +3. **Acción:** Seleccionar al profesor en el desplegable de docentes, elegir su rol académico (*Titular*, *Adjunto*, *JTP*, *Ayudante*) y marcar si es el docente principal. +4. **Asignar:** Presionar `+ Vincular Docente`. + - *Nota de Co-docencia:* Si la comisión tiene múltiples docentes registrados, el sistema activará automáticamente la tolerancia de superposición horaria en la matriz de conflictos. + +#### Paso 8: Asociar Alumnos (Matriculación de Estudiantes) +1. **Acceso:** Dentro de la misma vista de **Detalle de Comisión** (`/admin/commission_detail`), localizar la tarjeta **"Alumnos Matriculados"**. +2. **Acción:** Presionar `Inscribir Alumno` y seleccionar al estudiante registrado en el sistema. +3. **Validación Automática:** El sistema comprobará si el alumno ya cursa otra materia regular el mismo día. + - Si no hay conflicto: La matriculación se efectiviza inmediatamente. + - Si existe superposición de día: El sistema solicita autorización expresa de Bedelía activando el switch `Autorizar excepción de cursada en el mismo día` e ingresando el motivo institucional. +4. **Confirmar:** Presionar `Inscribir`. + +#### Paso 9: Reserva de Espacios (Asignación de Aula y Horario) +Bedelía dispone de **3 modalidades complementarias** para efectuar la reserva según la conveniencia: +1. **Modalidad Rápida desde Comisiones:** + - En `/admin/commissions_list`, pulsar el botón con ícono de calendario `Asignar Aula` (`bi-calendar-plus`) en la fila de la comisión. + - El sistema redirige a `/schedule/add_reservation` precargando automáticamente la comisión, el cupo, la carrera y los datos de la materia. + - Seleccionar Edificio ➔ Piso ➔ Aula, día de la semana y franja horaria. + - Presionar `Confirmar Reserva`. La matriz de conflictos valida en tiempo real y confirma la reserva. +2. **Modalidad Interactiva (Drag & Drop en Calendario Semanal):** + - Ir a **Reservas / Calendario** (`/schedule/calendar`). + - En la barra lateral izquierda se muestran las *Comisiones Pendientes de Aula*. + - Arrastrar la tarjeta de la comisión directamente a la grilla horaria del aula deseada. + - El sistema valida instantáneamente; si no hay solapamiento ni choque de docentes, la reserva queda confirmada. Si hay colisión, revierte el movimiento y muestra una alerta clara en pantalla. +3. **Modalidad Automatizada con Inteligencia Artificial (Optimizador Genético):** + - Ir a **Optimizador de Aulas** (`/genetic-optimizer`). + - Seleccionar el ciclo lectivo y pulsar `Ejecutar Optimización`. + - El algoritmo heurístico evalúa millones de combinaciones, asignando las aulas de mayor capacidad a los grupos más numerosos y evitando todo solapamiento. + - Bedelía previsualiza el resultado y confirma la asignación masiva con 1 clic. + +--- + +#### 📥 Ingesta Masiva desde Google Sheets / Planillas: +- Para no interrumpir la dinámica durante la transición, Bedelía puede usar la importación oficial desde Google Sheets: + - Ir a **Administración** ➔ **Configuración Global** (`/admin/settings`). + - Verificar la URL de la planilla oficial publicada. + - Ejecutar la sincronización masiva para poblar comisiones y horarios. + - *A partir de ese momento, toda modificación, reemplazo o ajuste se realiza exclusivamente en Edu-Space*, dejando la planilla congelada como copia de respaldo. --- ### 1.2. Para el Cuerpo Docente (Profesores) -1. **Consulta de Aulas Asignadas:** - - Iniciar sesión con la cuenta docente. En el **Dashboard de Cátedra**, el profesor ve inmediatamente su agenda semanal: nombre de la materia, número de comisión, aula física asignada, piso y capacidad. -2. **Clases Virtuales e Híbridas (Google Meet):** - - Para las materias con modalidad combinada, el sistema genera y exhibe el enlace directo de **Google Meet**. El docente puede iniciarlo con un solo clic sin necesidad de crear salas manualmente. -3. **Solicitud de Asistencia o Recursos:** - - Desde la ficha de su clase, el profesor puede reportar incidencias (ej: falta de marcadores, proyector averiado) notificando directamente al panel de Bedelía. +1. **Consulta Inmediata de Aulas Asignadas:** + - Iniciar sesión en la plataforma con cuenta institucional. + - En el **Dashboard de Cátedra** (`/dashboard?role=docente`), el docente visualiza su agenda del día y de la semana: + - Nombre de la materia y número de comisión. + - Aula física exacta asignada, piso y sede. + - Cantidad de alumnos matriculados y equipamiento disponible. +2. **Clases Virtuales y Enlace a Google Meet:** + - Si la comisión es virtual o híbrida, el docente visualiza el botón destacado `Unirse a Clase Virtual (Meet)`. + - Con un solo clic se abre la sala de Google Meet oficial vinculada a la comisión. +3. **Libro de Calificaciones (*Gradebook*) y Actas de Notas:** + - Acceder al menú **Mis Materias** ➔ Seleccionar la comisión ➔ Pulsar `Libro de Calificaciones (Actas)`. + - Cargar las notas de exámenes parciales, recuperatorios y TPs en la grilla interactiva. + - El sistema realiza autoguardado asíncrono y calcula promedios y condición académica (*Promocionado*, *Regular*, *Libre*). + - Al finalizar el cuatrimestre, pulsar `Cerrar y Sellar Acta Oficial`. Se genera un identificador inmutable (`ACTA-2026-2C-XXXX`) registrado en auditoría. +4. **Solicitud de Asistencia o Incidencias:** + - Desde la ficha de la clase, el docente puede reportar cualquier falla edilicia (proyector averiado, aire acondicionado, falta de bancos) para que Bedelía actúe de inmediato. --- ### 1.3. Para los Estudiantes (Alumnado) -1. **Localización de Aula en Tiempo Real:** - - Desde cualquier smartphone o computadora, el alumno ingresa a `eduspace.oemspot.com.ar` y visualiza en su pantalla principal el aula de cursada del día, evitando aglomeraciones en los pasillos de entrada. -2. **Calendario Académico y Fechas de Parciales:** - - El alumno consulta los días confirmados de exámenes parciales, recuperatorios y entregas de trabajos prácticos fijados por sus cátedras. -3. **Cartelera de Avisos:** - - Acceso a novedades institucionales y eventuales traslados de aula notificados al instante. +1. **Brújula de Cursada "¿Dónde curso hoy?":** + - Desde su teléfono inteligente o computadora, el estudiante ingresa a `eduspace.oemspot.com.ar`. + - En la pantalla principal visualiza inmediatamente: + - Aula exacta de cursada del día, piso y sede (ej. *Aula 203 - 2° Piso - Sede Central*). + - Horario de inicio y fin de la clase. + - Nombre de la materia y docente a cargo. +2. **Acceso a Clases Virtuales:** + - Si la clase del día es virtual, en lugar del aula física se despliega el botón `Ingresar a la Clase Virtual`. +3. **Calendario Académico y Próximos Exámenes:** + - Visualización de la cuenta regresiva para exámenes parciales, fechas de entrega de trabajos prácticos y recesos. +4. **Consulta de Notas y Certificados:** + - En la sección **Mis Calificaciones**, el alumno puede revisar sus notas de parciales, condición final y número de acta oficial sellada por el docente. --- -## 2. Relevamiento y Cuestionario para Entrevista con Bedelía +## 2. Relevamiento Operativo y Adaptación Institucional -Para perfeccionar la aplicación y adaptarla de forma quirúrgica a las particularidades de UniCABA, se diseñó la siguiente guía de preguntas para entrevistar al equipo de Bedelía: +Para asegurar una transición sin fricción desde el Excel hacia Edu-Space en UniCABA, se definen los siguientes criterios operativos: -### Bloque A: Dinámica y Cuellos de Botella Actuales -1. *¿Cuál es el proceso exacto que utilizan hoy cuando se abre un nuevo cuatrimestre? ¿Cuánto tiempo les demanda asignar manualmente todas las aulas?* -2. *¿Cuáles son los conflictos más frecuentes que ocurren durante las dos primeras semanas de clase? (Ej: grupos que superan la capacidad del aula, docentes que piden proyector sin aviso previo, ruidos molestos).* -3. *¿Cómo gestionan hoy los cambios de aula imprevistos? (¿Cartel de papel en la puerta, aviso por WhatsApp, grupos de delegados?)* - -### Bloque B: Reglas de Negocio y Restricciones Específicas -4. *¿Existen docentes que por razones de movilidad reducida o edad deban tener asignadas aulas exclusivamente en Planta Baja o cerca de ascensores?* -5. *¿Hay cátedras que requieran software específico o laboratorios fijos que no puedan dictarse en aulas convencionales?* -6. *¿Qué margen de tolerancia de capacidad prefieren? (Ej: ¿Es aceptable ubicar a 30 alumnos en un aula de 32 bancos, o exigen un 15% de margen de seguridad libre?)* - -### Bloque C: Integración con Sistemas Institucionales -7. *¿De qué sistema extraen la nómina de alumnos inscriptos? (¿SIU Guaraní, planillas CSV/Excel, sistema propio de la Ciudad de Buenos Aires?)* -8. *¿Qué formato de reporte o planilla deben entregar a Dirección Académica al cerrar la planificación?* - -### Bloque D: Propuestas de Mejora Identificadas para Modificar en Edu-Space -* **Petición detectada:** Incorporación de un botón de "Intercambio Rápido de Aulas" entre dos comisiones simultáneas sin tener que desasignar y volver a asignar a ambas individualmente. -* **Petición detectada:** Alerta visual con código de colores cuando un aula física supere el 95% de aforo de seguridad. -* **Petición detectada:** Exportador directo en PDF imprimible con formato oficial apaisado para pegar en las carteleras de corcho tradicionales para aquellos alumnos sin batería en el móvil. +### Criterios Clave de Usabilidad para Bedelía: +1. **Intercambio Rápido de Aulas:** Permite permutar dos comisiones de aula en la misma franja horaria sin tener que desasignar y reasignar individualmente. +2. **Semáforo Visual de Aforo:** Alertas de color (Verde: < 80% ocupación, Amarillo: 80-95%, Rojo: > 95% o exceso de capacidad). +3. **Exportación Imprimible:** Generador de reportes de cartelera en formato apaisado para impresión en papel ante contingencias eléctricas o de red. --- -## 3. Especificación: Módulo y Pestaña de Beneficios Universitarios - -### 3.1. Propósito y Justificación -Uno de los principales factores de permanencia y bienestar estudiantil es el acceso ágil a los convenios y beneficios que brinda la comunidad académica. La incorporación de la pestaña **Beneficios** dentro del ecosistema Edu-Space centraliza esta información en la misma plataforma donde el alumno consulta su vida académica diaria. - -``` -┌────────────────────────────────────────────────────────────────────────┐ -│ PESTAÑA DE BENEFICIOS EDU-SPACE │ -├──────────────────┬──────────────────┬─────────────────┬────────────────┤ -│ 🏷️ COMERCIO │ 💻 LICENCIAS │ ☕ COMEDOR │ 📚 BIBLIOTECA │ -│ Y LIBRERÍA │ DE SOFTWARE │ UNIVERSITARIO │ DIGITAL │ -├──────────────────┼──────────────────┼─────────────────┼────────────────┤ -│ 20% en fotocopias│ GitHub Student │ Menú estudiantil│ Préstamo de │ -│ y apuntes con el │ Pack, JetBrains │ subsidiado con │ e-books y salas│ -│ carnet digital. │ Pro y Office 365 │ reserva previa. │ de estudio. │ -└──────────────────┴──────────────────┴─────────────────┴────────────────┘ -``` - -### 3.2. Modelo de Datos Propuesto (Entidades) -* **Tabla `beneficio`:** - - `id`: Clave primaria autoincremental. - - `categoria`: Enum (`Librería`, `Gastronomía`, `Software/Tecnología`, `Salud/Deportes`, `Cultura`). - - `titulo`: Nombre del beneficio (ej: *Descuento 20% en Fotocopiadora Central*). - - `descripcion`: Condiciones de uso y letra chica. - - `validez_hasta`: Fecha límite de vigencia. - - `codigo_descuento`: Cupón alfanumérico o enlace de validación. - - `convenio_empresa`: Nombre del proveedor o área universitaria. - - `activo`: Booleano para activar/pausar la visualización. - -### 3.3. Interfaz de Usuario (UI) -* Tarjetas dinámicas (*Cards*) con estética Glassmorphism, botón de "Copiar Código", botón de "Ver Mapa de Canje" y filtros por categoría. +## 3. Especificación: Módulo de Beneficios Universitarios (Futuro) +- Pestaña para centralizar convenios estudiantiles (Librerías, Software estudiantil, Comedor universitario, Biblioteca digital). +- Tarjetas con códigos de validación y mapa de canje. --- ## 4. Innovación a Futuro: Credencial Digital con QR y Rol "Recepción" - -### 4.1. Arquitectura de Acceso Seguro mediante QR Dinámico -Para modernizar el control de ingreso al edificio de UniCABA y erradicar las credenciales plásticas costosas y extraviables, se proyecta el módulo de **Credencial QR Inteligente**: - -``` - [ Pantalla Alumno (Edu-Space) ] - Generación de Token TOTP Cifrado (HMAC-SHA256) - (Cambia cada 30 segundos para evitar capturas de pantalla compartidas) - │ - ▼ Muestra Código QR en Pantalla - - [ Puesto de Acceso / Molinete ] - │ - ▼ Escaneo con Cámara Web o Lector Óptico 2D - [ Tablet / Terminal Rol "Recepción" ] - - Valida firma criptográfica con la API - - Consulta estado del estudiante: ¿Alumno Regular Activo? ¿Tiene clase en esta sede hoy? - │ - ▼ - ✅ ACCESO PERMITIDO: Nombre, Foto, Carrera y Aula asignada ("Aula 104 - 1° Piso") - ❌ ACCESO DENEGADO / ALERTA: Matrícula suspendida o no regular -``` - -### 4.2. Especificación del Nuevo Rol de Usuario: `recepcion` -* **Permisos del Rol:** - - Acceso restringido exclusivamente a la pantalla de escaneo (`/reception/scanner`) y al monitor de aforo edilicio en vivo (`/reception/headcount`). - - Imposibilidad de alterar notas, comisiones o configuraciones de Bedelía. -* **Beneficios de Seguridad Institucional:** - - **Control de Aforo en Tiempo Real:** El personal de portería y seguridad conoce en todo momento la cantidad exacta de personas dentro del edificio, dato crítico ante evacuaciones por siniestros. - - **Guía al Ingresante:** Al momento del escaneo, el sistema le muestra en pantalla al recepcionista a qué aula debe dirigirse el estudiante, permitiendo orientarlo amablemente en el momento del ingreso. +- Credencial QR inteligente con token dinámico TOTP (HMAC-SHA256) que cambia cada 30 segundos en la pantalla del alumno. +- Rol de usuario `recepcion` en tablets de molinete para validar ingreso, registrar aforo edilicio en tiempo real y guiar al estudiante a su aula asignada. --- -## 5. Aplicación Móvil en Ionic (Capacitor) para Android e iOS - -### 5.1. ¿Por Qué Ionic Framework + Capacitor? -Para llevar Edu-Space a los dispositivos móviles de los estudiantes y profesores sin duplicar el costo de desarrollo en lenguajes nativos independientes (Kotlin/Swift), la elección óptima de ingeniería es **Ionic con Capacitor**: - -1. **Reutilización del Código y UI Web:** El diseño responsivo ya desarrollado en HTML5/CSS/JavaScript se compila directamente dentro de un contenedor webview de alto rendimiento nativo. -2. **Acceso a Hardware Nativo mediante Plugins Capacitor:** - - `@capacitor/camera`: Para que el personal de recepción o docentes escaneen códigos QR directamente con el lente del celular. - - `@capacitor/push-notifications`: Notificaciones Push en tiempo real emitidas por Firebase Cloud Messaging (FCM) ante avisos urgentes (ej: *"Tu clase de Algoritmos se trasladó al Aula 201"*). - - `@capacitor/preferences` / `@capacitor-community/sqlite`: Almacenamiento local para permitir al alumno consultar sus horarios sin consumir datos móviles o en zonas del edificio con baja señal de red. - -### 5.2. Arquitectura de Distribución - -``` - ┌──────────────────────────────────┐ - │ Código Base Edu-Space Frontend │ - └─────────────────┬────────────────┘ - │ - ▼ - ┌──────────────────────────────────┐ - │ Capacitor Bridge CLI │ - └────────┬────────────────┬────────┘ - │ │ - ┌───────────────▼──┐ ┌──▼────────────────┐ - │ Proyecto Nativo│ │ Proyecto Nativo │ - │ Android │ │ iOS │ - │ (Gradle/APK) │ │ (Xcode/Archive) │ - └───────┬──────────┘ └──┬────────────────┘ - │ │ - ▼ ▼ - Google Play Store Apple App Store -``` - -### 5.3. Fases de Implementación Móvil -* **Fase 1 (Empaquetado y Notificaciones):** Inicialización de Capacitor en el proyecto, configuración de iconos adaptativos y recepción de notificaciones Push de cambios de aula. -* **Fase 2 (Modo Desconectado / Offline):** Caché del cronograma semanal en almacenamiento interno del dispositivo para consulta sin internet. -* **Fase 3 (Publicación):** Firma digital de binarios (`.aab` para Android y `.ipa` para iOS) y subida a las consolas de Google Play y Apple Developer. +## 5. Aplicación Móvil Híbrida en Ionic (Capacitor) +- Envoltorio Capacitor multiplataforma para Android e iOS reutilizando la interfaz web responsiva de Edu-Space. +- Notificaciones Push institucionales ante traslados o cancelaciones de aula de último momento. +- Modo de consulta offline del cronograma semanal almacenado en caché interna del teléfono. diff --git a/ROADMAP_MVP.md b/docs/ROADMAP_MVP.md similarity index 100% rename from ROADMAP_MVP.md rename to docs/ROADMAP_MVP.md diff --git a/SECURITY_AUDIT_REPORT.md b/docs/SECURITY_AUDIT_REPORT.md similarity index 100% rename from SECURITY_AUDIT_REPORT.md rename to docs/SECURITY_AUDIT_REPORT.md diff --git a/docs/constitution.md b/docs/constitution.md new file mode 100644 index 0000000..979b32f --- /dev/null +++ b/docs/constitution.md @@ -0,0 +1,42 @@ +# Constitución de admin-edu-space +Principios innegociables y mandatorios del Software System Design (SSD). Toda especificación, diseño, plan y tarea del agente debe cumplirlos estrictamente sin excepción. + +--- + +### 1. La Especificación y el SSD Mandan +Nada se implementa, refactoriza o modifica en la plataforma si no está documentado en la especificación activa o alineado con el Software System Design (SSD). Si se detecta un caso de uso no previsto o una ambigüedad en los requerimientos, se detiene la ejecución y se consulta al responsable del proyecto antes de avanzar. + +### 2. Arquitectura Desacoplada (Backend RESTful + Frontend BFF) +El sistema opera bajo una arquitectura desacoplada de dos capas: +- **Backend Core API (Python / Flask + SQLAlchemy)**: Expone exclusivamente servicios RESTful bajo el prefijo `/api/v1/`, retornando respuestas JSON estructuradas con serializadores/DTOs. Gestiona la autenticación stateless mediante tokens JWT (HS256), la integridad referencial en base de datos y el pipeline de blindaje `SecurityFilterChain`. +- **Frontend BFF (Node.js / Express + Nunjucks)**: Orquesta la presentación y la experiencia de usuario (UX), mantiene la sesión mediante cookies seguras `HttpOnly`, inyecta encabezados de autorización Bearer en llamadas Axios hacia el backend y adapta las vistas según el rol del usuario autenticado. + +### 3. Reemplazo Definitivo del Excel como Herramienta Operativa +El objetivo primordial del sistema es erradicar el uso del archivo Excel/planilla como herramienta de gestión cotidiana de Bedelía, convirtiendo a la plataforma en la **única fuente de verdad** (Single Source of Truth) para la administración de espacios, comisiones y cursadas a través del ciclo estructurado de 9 pasos (Sedes -> Aulas -> Ciclos Lectivos -> Carreras -> Asignaturas -> Comisiones -> Profesores -> Alumnos -> Reservas). Toda asignatura debe pertenecer a su carrera y toda comisión hereda y expone esta pertenencia institucional para filtros y reportes académicos. +- La importación desde Google Sheets / planillas externas se mantiene exclusivamente como mecanismo de **ingesta masiva inicial y compatibilidad**, mientras que todas las altas, modificaciones, cancelaciones y reubicaciones deben realizarse directamente en la plataforma. + +### 4. Matriz Infranqueable de Conflictos Académicos y Espaciales +La asignación de reservas de aulas debe validar en tiempo real e impedir de forma determinística: +1. **Conflicto Físico**: Doble asignación horaria en una misma aula presencial para el mismo día y bloque horario. +2. **Conflicto de Aforo**: Asignación de una comisión cuyo cupo estimado supere la capacidad física del aula. +3. **Conflicto Docente**: Superposición horaria de un profesor en múltiples espacios simultáneos, permitiendo excepción **únicamente** cuando la comisión cuenta con co-docencia activa registrada en `CommissionTeacher`. +4. **Restricción Diaria del Alumno**: Bloqueo de cursada de dos asignaturas regulares en el mismo día de la semana, exceptuando talleres/cursos cortos (`is_short_course`) o autorización expresa y justificada de Bedelía (`allow_same_day_exception`). + +### 5. Caché First y Resiliencia en Servicios Externos (Moodle 4.1 & SMTP) +- Toda consulta de datos o perfiles provenientes de Moodle 4.1 debe consultar en primer término la capa de caché (`CacheService` en Redis o memoria). +- Toda operación de sincronización hacia Moodle debe encolarse de forma asíncrona no bloqueante (`MoodleSyncTask`) utilizando reintentos exponenciales (*Exponential Backoff*) y derivación a Dead Letter Queue (DLQ) ante indisponibilidad. +- Prohibidas las peticiones síncronas bloqueantes a servicios externos dentro de las transacciones de los controladores web. +- El servicio de correo transaccional (`EmailService`) debe utilizar credenciales dinámicas descifradas con Fernet sin impactar los tiempos de respuesta. + +### 6. Privacidad Estricta, Blindaje RBAC y Trazabilidad +- Los datos de alumnos, docentes y credenciales de acceso son de máxima confidencialidad. Ningún endpoint debe exponer contraseñas, secretos o información privada a roles no autorizados. +- La autenticación institucional de Google Workspace debe validar estrictamente los dominios institucionales autorizados (`@unicaba.edu.ar`). +- Toda acción sensible (reseteo de sistema, impersonación de usuarios, reapertura/cierre de actas de notas) debe quedar registrada de forma inmutable en la tabla de auditoría (`AuditLog`). + +### 7. Convenciones de Código e Idioma +- **Código Fuente**: Nombres de variables, clases, métodos, commits y pruebas en **inglés**. +- **Interfaz y Documentación**: Vistas, mensajes de error, respuestas al usuario, correos electrónicos y documentación operativa en **español**. + +### 8. Testing Automatizado como Puerta de Enlace (Quality Gate) +- La suite de pruebas automatizadas (`pytest backend/tests`) y los controles de seguridad SAST/DAST/SCA (`security_audit.bat`) son mandatorios. +- Queda terminantemente prohibido cerrar una tarea o fusionar cambios a la rama de integración con pruebas fallando o vulnerabilidades críticas no remediadas. \ No newline at end of file diff --git a/frontend/src/routes/admin.js b/frontend/src/routes/admin.js index 5ca1654..64c3519 100644 --- a/frontend/src/routes/admin.js +++ b/frontend/src/routes/admin.js @@ -830,6 +830,7 @@ const handleCommissionsList = async (req, res) => { try { const search = (req.query.search || '').trim(); const subject_id = req.query.subject_id || ''; + const career_id = req.query.career_id || ''; const shift = req.query.shift || ''; const active = req.query.active || ''; const created = req.query.created === '1'; @@ -838,10 +839,11 @@ const handleCommissionsList = async (req, res) => { let subjects = []; let teachers = []; let academic_terms = []; + let careers = []; try { const [cRes, uRes] = await Promise.allSettled([ - req.apiClient.get('/commissions', { params: { search, subject_id, shift, active } }), + req.apiClient.get('/commissions', { params: { search, subject_id, career_id, shift, active } }), req.apiClient.get('/users') ]); @@ -849,10 +851,13 @@ const handleCommissionsList = async (req, res) => { commissions = (cRes.value.data.commissions || []).map(c => ({ ...c, get_full_code: () => c.full_code || c.code, + career_id: c.career_id, + career_name: c.career_name || 'Carrera General', subject: { id: c.subject_id, name: c.subject_name, code: c.subject_code, + career_id: c.career_id, career_name: c.career_name || 'Carrera General' }, teacher: c.teacher_name ? { name: c.teacher_name } : null, @@ -860,6 +865,15 @@ const handleCommissionsList = async (req, res) => { })); subjects = cRes.value.data.subjects || []; academic_terms = cRes.value.data.academic_terms || []; + careers = cRes.value.data.careers || []; + } + + // Fallback para careers si no vinieron en la respuesta de commissions + if (!careers || careers.length === 0) { + try { + const carRes = await req.apiClient.get('/careers'); + careers = carRes.data?.careers || []; + } catch (carErr) {} } // Si por alguna razón no vinieron academic_terms en commissions, intentar fallback @@ -887,8 +901,10 @@ const handleCommissionsList = async (req, res) => { subjects, teachers, academic_terms, + careers, search, subject_filter: subject_id ? parseInt(subject_id, 10) : '', + career_filter: career_id ? parseInt(career_id, 10) : '', shift_filter: shift, active_filter: active, created, diff --git a/frontend/src/routes/dashboard.js b/frontend/src/routes/dashboard.js index 2c0550b..a14daa7 100644 --- a/frontend/src/routes/dashboard.js +++ b/frontend/src/routes/dashboard.js @@ -108,74 +108,21 @@ router.get('/', async (req, res) => { }; } else if (role === 'bedelia') { role_data = { - pending_reservations: apiPending || [ - { - id: 101, - start_time: '08:00', - end_time: '12:00', - classroom: { code: 'Aula 101' }, - subject_name: 'Arquitectura de Computadoras', - user: { name: 'Prof. Gabriel Martínez' } - }, - { - id: 102, - start_time: '14:00', - end_time: '18:00', - classroom: { code: 'Lab Informática 2' }, - subject_name: 'Bases de Datos II', - user: { name: 'Dra. Laura Blanco' } - }, - { - id: 103, - start_time: '18:30', - end_time: '22:00', - classroom: { code: 'Aula Magna' }, - subject_name: 'Seminario de Ciberseguridad', - user: { name: 'Lic. Fernando Gómez' } - } - ], - today_schedule_list: apiTodaySchedule || [ - { start_time: '08:00', end_time: '12:00', classroom: { code: 'Aula 102' }, subject_name: 'Algoritmos y Estructuras de Datos', user: { name: 'Prof. Ana Vega' } }, - { start_time: '08:30', end_time: '12:30', classroom: { code: 'Aula 204' }, subject_name: 'Matemática Discreta', user: { name: 'Prof. Carlos López' } }, - { start_time: '14:00', end_time: '18:00', classroom: { code: 'Lab Redes' }, subject_name: 'Redes y Telecomunicaciones', user: { name: 'Ing. Marcos Ruiz' } } - ], + pending_reservations: apiPending || [], + today_schedule_list: apiTodaySchedule || [], unassigned_commissions_week: bedeliaData.unassigned_commissions_week || [], unassigned_commissions_month: bedeliaData.unassigned_commissions_month || [], available_classrooms_week: bedeliaData.available_classrooms_week || [], available_classrooms_month: bedeliaData.available_classrooms_month || [] }; } else if (role === 'docente') { - const myClasses = apiTodaySchedule ? apiTodaySchedule.slice(0, 3) : null; + const myClasses = apiTodaySchedule ? apiTodaySchedule.slice(0, 3) : []; role_data = { - my_today_classes: myClasses || [ - { - id: 201, - start_time: '08:30', - end_time: '12:00', - subject_name: 'Algoritmos y Estructuras de Datos', - subject_code: 'AED-102', - commission: { code: 'COM-A' }, - classroom: { is_virtual: false, location_display: 'Piso 1 · Aula 104' }, - virtual_link: '' - }, - { - id: 202, - start_time: '18:30', - end_time: '22:00', - subject_name: 'Programación Concurrente y Distribuida', - subject_code: 'PCD-301', - commission: { code: 'COM-D' }, - classroom: { is_virtual: true, location_display: 'Campus Virtual' }, - virtual_link: 'https://meet.google.com/edu-space-pcd' - } - ], - virtual_classrooms: [ - { code: 'Sala Virtual 1', link: 'https://meet.google.com/edu-space-v1' }, - { code: 'Sala Virtual 2', link: 'https://meet.google.com/edu-space-v2' } - ] + my_today_classes: myClasses, + virtual_classrooms: [] }; } else if (role === 'alumno') { - const studentClasses = apiTodaySchedule ? apiTodaySchedule.slice(0, 4) : null; + const studentClasses = apiTodaySchedule ? apiTodaySchedule.slice(0, 4) : []; let upcomingMilestonesList = []; try { const mResp = await req.apiClient.get('/students/my-upcoming-milestones'); @@ -196,75 +143,13 @@ router.get('/', async (req, res) => { console.warn('Student milestones fetch notice:', e.message); } - if (upcomingMilestonesList.length === 0) { - upcomingMilestonesList = [ - { - title: 'Primer Examen Parcial', - materia_codigo: 'BDR-201', - subject_name: 'Bases de Datos Relacionales', - date: '25/09/2026', - days_remaining: 2, - type_obj: { name: 'Examen Parcial', color: '#dc3545' }, - milestone_type: { name: 'Examen Parcial', color: '#dc3545' }, - notes: 'Traer DNI y calculadora', - classroom: 'Piso 2 · Aula 204' - }, - { - title: 'Entrega TP Grupal Nº 2', - materia_codigo: 'AED-102', - subject_name: 'Algoritmos y Estructuras de Datos', - date: '30/09/2026', - days_remaining: 7, - type_obj: { name: 'Trabajo Práctico', color: '#198754' }, - milestone_type: { name: 'Trabajo Práctico', color: '#198754' }, - notes: 'Subir código al repositorio', - classroom: 'Campus Virtual', - link: 'https://campus.edu-space.com/tps' - }, - { - title: 'Recuperatorio Parcial 1', - materia_codigo: 'RYT-302', - subject_name: 'Redes y Telecomunicaciones', - date: '08/10/2026', - days_remaining: 15, - type_obj: { name: 'Recuperatorio', color: '#fd7e14' }, - milestone_type: { name: 'Recuperatorio', color: '#fd7e14' }, - notes: 'Piso 2 · Aula 204', - classroom: 'Piso 2 · Aula 204' - } - ]; - } - role_data = { - today_classes: studentClasses || [ - { - start_time: '08:00', - end_time: '12:00', - subject_name: 'Bases de Datos Relacionales', - subject_code: 'BDR-201', - commission: { code: 'COM-1' }, - classroom: { is_virtual: false, location_display: 'Piso 2 · Laboratorio 3' }, - virtual_link: '' - }, - { - start_time: '18:30', - end_time: '22:30', - subject_name: 'Redes y Telecomunicaciones', - subject_code: 'RYT-302', - commission: { code: 'COM-2' }, - classroom: { is_virtual: true, location_display: 'Campus Virtual (Google Meet)' }, - virtual_link: 'https://meet.google.com/edu-space-demo' - } - ], + today_classes: studentClasses, upcoming_milestones: upcomingMilestonesList }; } - const upcoming_reservations = apiUpcoming || [ - { start_time: '08:00', end_time: '12:00', date_display: '22/09', subject_name: 'Matemática Discreta', subject_code: 'MAT-101', shift: 'Mañana', commission: { code: 'COM-1' }, status: 'CONFIRMED', classroom: { code: 'Aula 101' }, user: { name: 'Prof. Carlos López' } }, - { start_time: '14:00', end_time: '18:00', date_display: '23/09', subject_name: 'Sistemas Operativos', subject_code: 'SO-202', shift: 'Tarde', commission: { code: 'COM-2' }, status: 'CONFIRMED', classroom: { code: 'Lab 2' }, user: { name: 'Dra. Ana Vega' } }, - { start_time: '18:30', end_time: '22:30', date_display: '24/09', subject_name: 'Ingeniería de Software', subject_code: 'IS-301', shift: 'Noche', commission: { code: 'COM-3' }, status: 'PENDING', classroom: { code: 'Aula Magna' }, user: { name: 'Ing. Marcos Ruiz' } } - ]; + const upcoming_reservations = apiUpcoming || []; let show_role_banner = true; if (apiData && apiData.ui && apiData.ui.show_role_banner !== undefined) { diff --git a/frontend/views/admin/commissions/detail.html b/frontend/views/admin/commissions/detail.html index 31f56ee..62a5417 100644 --- a/frontend/views/admin/commissions/detail.html +++ b/frontend/views/admin/commissions/detail.html @@ -65,9 +65,12 @@
{{ commission.subject.name }}
-

{{ commission.subject.code }} - {% if commission.subject.career_obj %}— {{ commission.subject.career_obj.name }}{% endif %} -

+
+ {{ commission.subject.code }} + + {{ commission.career_name or (commission.subject.career_obj.name if commission.subject.career_obj else 'Carrera General') }} + +
{% if commission.shift %} diff --git a/frontend/views/admin/commissions/list.html b/frontend/views/admin/commissions/list.html index 23218c4..ad27c70 100644 --- a/frontend/views/admin/commissions/list.html +++ b/frontend/views/admin/commissions/list.html @@ -102,6 +102,19 @@
+ + +
+
-
+
-
+
-
+
- +
@@ -177,7 +190,7 @@
{{ comm.subject.name }}
{{ comm.subject.code }} - {{ comm.subject.career_name or 'Carrera General' }} + {{ comm.career_name or comm.subject.career_name or 'Carrera General' }} {{ comm.semester }} {{ comm.year }}
diff --git a/frontend/views/base.html b/frontend/views/base.html index 6016f7d..a2f3b62 100644 --- a/frontend/views/base.html +++ b/frontend/views/base.html @@ -969,12 +969,50 @@ {% elif user_role == 'bedelia' %} - - - - - - + + + + {% elif user_role == 'docente' %}