224 lines
15 KiB
Markdown
224 lines
15 KiB
Markdown
# Estado Actual de la Migración y Arquitectura Objetivo
|
|
## Sistema Integral de Gestión de Aulas, Cursadas y Seguimiento Académico — UniCABA
|
|
|
|
**Rol:** Arquitecto de Software y Analista Funcional Senior
|
|
**Institución:** Universidad de la Ciudad de Buenos Aires (UniCABA)
|
|
**Fecha de Actualización:** 19 de Septiembre de 2026
|
|
**Rama Activa:** `testing`
|
|
|
|
---
|
|
|
|
## 1. De Dónde Venimos: La Versión Monolítica (`legacy_admin-edu-space`)
|
|
|
|
La versión original del sistema correspondía a un monolito clásico desarrollado en Python (Flask) con renderizado del lado del servidor mediante plantillas Jinja2 y ORM SQLAlchemy:
|
|
|
|
```
|
|
[Cliente Web / Navegador]
|
|
│
|
|
▼ (HTTP / HTML)
|
|
┌────────────────────────────────────────────────────────┐
|
|
│ Monolito Legacy (legacy_admin-edu-space) │
|
|
│ - Rutas Flask con render_template (Jinja2) │
|
|
│ - Sesión en Cookies de Flask (Flask-Login con estado) │
|
|
│ - Consultas directas SQLAlchemy acopladas a vistas │
|
|
│ - Base de Datos (SQLite / PostgreSQL) │
|
|
└────────────────────────────────────────────────────────┘
|
|
```
|
|
|
|
### Fortalezas Heredadas del Monolito
|
|
1. **Modelado de Dominio Inicial:** Entidades base para Sedes (`Building`), Aulas (`Classroom`), Materias (`Subject`), Comisiones (`Commission`), Reservas (`Reservation`) y Usuarios (`User`).
|
|
2. **Importador de Planillas Oficiales:** Módulo de sincronización con Google Sheets para alimentar la cartelera con la oferta de comisiones y clases.
|
|
3. **Algoritmo Genético Experimental:** Prototipo de optimización predictiva para asignación de aulas físicas según aforo y equipamiento.
|
|
|
|
### Limitaciones Críticas que Forzaron la Migración
|
|
* **Acoplamiento Servidor-Vista:** Lógica de negocio mezclada dentro de controladores web y macros de plantillas Jinja2, impidiendo el consumo móvil (app institucional) o integraciones externas (SIU Guaraní, Moodle).
|
|
* **Fallas Graves en Virtualidad:** El importador de Google Sheets descartaba más del 75% de las clases virtuales por asumir que el aula `Campus Virtual · VIRTUAL` sufría colisiones físicas de horario ante comisiones simultáneas.
|
|
* **Falta de Perspectiva por Rol:** El dashboard era único y uniforme; no distinguía entre el trabajo administrativo de Bedelía, la consulta rápida de cursada del Alumno, o la gestión evaluativa del Docente.
|
|
* **Escalabilidad y Seguridad:** Autenticación dependiente de la sesión en memoria del servidor web, sin soporte de tokens JWT sin estado ni separación de responsabilidades (BFF pattern).
|
|
|
|
---
|
|
|
|
## 2. Dónde Estamos Actualmente: Arquitectura Desacoplada Backend-BFF
|
|
|
|
La infraestructura ha sido transformada en un modelo desacoplado y de alta disponibilidad:
|
|
|
|
```
|
|
[ Navegador Web / Cliente ]
|
|
│
|
|
│ (HTTP / HTML + Cookies HttpOnly)
|
|
▼
|
|
┌──────────────────────────────────────────────┐
|
|
│ Frontend BFF (Node.js + Express) │
|
|
│ Puerto: 3000 │
|
|
│ - Renderizado Nunjucks con herencia limpia │
|
|
│ - Orquestación y agregación de UI │
|
|
│ - Gestión de Cookie JWT y Contexto de Rol │
|
|
│ - Cliente Axios con Interceptor Bearer │
|
|
└──────────────────────┬───────────────────────┘
|
|
│
|
|
│ (REST JSON / JWT Bearer)
|
|
▼
|
|
┌──────────────────────────────────────────────┐
|
|
│ Backend Core API (Python + Flask) │
|
|
│ Puerto: 5000 │
|
|
│ - Endpoints RESTful bajo /api/v1/ │
|
|
│ - Autenticación Stateless JWT (HS256) │
|
|
│ - Pipeline Enterprise SecurityFilterChain │
|
|
│ - Capa de Servicios y DTOs (Pydantic) │
|
|
│ - Persistencia SQLAlchemy (Transaccional) │
|
|
└──────────────────────┬───────────────────────┘
|
|
│
|
|
▼
|
|
[ Base de Datos SQLite / PG ]
|
|
```
|
|
|
|
### Estado de Implementación al Día de la Fecha
|
|
|
|
| Componente / Módulo | Estado en Legacy | Estado Actual (Backend API + BFF) | Nivel de Paridad |
|
|
| :--- | :--- | :--- | :---: |
|
|
| **Autenticación & Sesión** | Flask-Login basado en sesión de servidor | Autenticación REST JWT con cookie HttpOnly segura y RBAC centralizado | **120% (Superado)** |
|
|
| **Dashboards por Rol** | Dashboard monolítico único para todos | 4 Dashboards especializados (`admin`, `bedelia`, `docente`, `alumno`) con selector dinámico | **150% (Superado)** |
|
|
| **Campus Virtual & Enlaces** | Colisión de clases virtuales; pérdida de enlaces Meet | Aulas virtuales concurrentes sin límite, auto-generación de enlaces Google Meet por comisión | **140% (Superado)** |
|
|
| **Importador Google Sheets** | 363 reservas importadas (colisiones masivas) | 643 reservas totales (388 virtuales) sin colisión horaria entre comisiones | **100% (Paridad Total)** |
|
|
| **Cartelera del Día (`today_schedule`)** | Vista Jinja con bloques rígidos | Timeline interactivo por horas (7 a 21 hs), filtros por piso/turno y switch `hide_virtual` | **110% (Superado)** |
|
|
| **Ficha de Reserva (`view_reservation`)** | Vista monolítica rígida | Acoplada al BFF con relaciones anidadas completas, edición en cascada, confirmación y cancelación | **100% (Paridad Total)** |
|
|
| **Gestión de Comisiones (`commissions_list`)** | Lista plana sin modal de creación en admin | Modal `#modalAddCommission` con vinculación obligatoria a Asignatura, docente, cupo, horarios y Meet | **125% (Superado)** |
|
|
| **Calendario FullCalendar** | Feed JSON básico | Endpoint `/api/v1/reservations` con discriminación cromática (`#6366F1` virtuales) | **100% (Paridad Total)** |
|
|
|
|
---
|
|
|
|
## 3. A Dónde Queremos Ir: El Sistema Integral UniCABA
|
|
|
|
El objetivo institucional es consolidar la plataforma como el **ERP Académico y Gestor de Espacios Oficial de UniCABA**, dando soporte a las dinámicas pedagógicas físicas y digitales de la universidad.
|
|
|
|
### A. Entorno Físico vs. Campus Virtual
|
|
1. **Edificio Físico (Central):**
|
|
- Espacios con aforo estrictamente limitado, asignación por piso/ala y equipamiento técnico (proyectores, laboratorios informáticos, acústica).
|
|
- Validación matemática de no-solapamiento temporal para evitar doble asignación de aula física.
|
|
2. **Campus Virtual:**
|
|
- Capacidad física infinita; asignación lógica de salas vinculadas a la plataforma oficial (Google Meet institucional, Zoom o Microsoft Teams).
|
|
- Control de concurrencia temporal de docentes y estudiantes (evitar que un docente o alumno deba estar en dos salas remotas al mismo tiempo).
|
|
|
|
---
|
|
|
|
## 4. Reglas de Negocio del Sistema Objetivo
|
|
|
|
### 1. Perfiles y Permisos (RBAC Avanzado)
|
|
* **Administrador General (Superadmin):**
|
|
* Gobernanza total del sistema, configuración de periodos y parametrización de reglas de conflicto.
|
|
* **Modo Impersonación / Vista Previa:** Visualización en tiempo real del sistema desde la perspectiva exacta de cualquier usuario (Bedelía, Docente, Alumno) para soporte y auditoría.
|
|
* Flexibilidad académica para autorizar excepciones de cursada simultánea y apertura de comisiones extraordinarias.
|
|
* **Bedelía / Gestión Operativa:**
|
|
* Administración integral del inventario físico (Sedes, Edificios, Pisos, Aulas) y virtual.
|
|
* Creación y parametrización de Ciclos Lectivos, Asignaturas y Comisiones.
|
|
* **Asignación Docente Co-docente:** Posibilidad de asignar más de un profesor a una misma comisión (equipo de cátedra: titulares, adjuntos, ayudantes).
|
|
* Gestión de cupos máximos, padrón de alumnos matriculados y resolución de conflictos de asignación.
|
|
* Supervisión de hitos evaluativos institucionales.
|
|
* **Docente:**
|
|
* Vista segmentada estrictamente a sus comisiones asignadas.
|
|
* Calendario de clases presenciales y accesos directos a sesiones de videoconferencia.
|
|
* Gestión del calendario de evaluación: carga de fechas de parciales, recuperatorios, entregas de trabajos prácticos y finales.
|
|
* Matriz ágil de carga y edición de calificaciones y estados de regularidad.
|
|
* **Alumno:**
|
|
* Acceso enfocado a sus materias cursadas en el periodo lectivo activo.
|
|
* Brújula de cursada diaria (*¿Dónde curso hoy?* con sede, piso y aula física o enlace virtual).
|
|
* Calendario unificado de entregas de TPs, parciales y finales con avisos preventivos.
|
|
* Consulta histórica de notas y retroalimentaciones pedagógicas.
|
|
|
|
### 2. Estructura Académica y Ciclo Lectivo
|
|
* **Ciclo Lectivo Flexible:** Estructurado por Año (ej. `2026`) y Periodos estándar (`1C`, `2C`, `Anual`), permitiendo el alta de "Cursos Cortos Intensivos" o trayectos formativos extracurriculares con fechas especiales.
|
|
* **Restricción Diaria de Cursada del Estudiante:**
|
|
* **Regla por defecto:** Un estudiante universitario no puede cursar dos asignaturas regulares el mismo día calendario.
|
|
* **Excepción parametrizable:** Se autoriza la coincidencia en el mismo día si una de las materias corresponde a un curso corto intensivo o mediante autorización explícita de Bedelía/Secretaría Académica.
|
|
|
|
### 3. Matriz de Conflictos y Validaciones de Solapamiento
|
|
```mermaid
|
|
flowchart TD
|
|
Req([Solicitud de Asignación / Reserva]) --> V1{¿Es Aula Física?}
|
|
V1 -- Sí --> C1{¿Aula ocupada en ese día y horario?}
|
|
C1 -- Sí --> Err1[BLOQUEO: Conflicto Físico Infranqueable]
|
|
C1 -- No --> C2{¿Aforo de alumnos <= Capacidad aula?}
|
|
C2 -- No --> Err2[BLOQUEO: Aforo Excedido]
|
|
C2 -- Sí --> V2
|
|
V1 -- No (Virtual) --> V2
|
|
|
|
V2{¿Docente en otra clase en el mismo horario?}
|
|
V2 -- Sí --> C3{¿Comisión cuenta con Co-Docencia?}
|
|
C3 -- No --> Err3[BLOQUEO: Conflicto Docente]
|
|
C3 -- Sí --> Warn1[ALERTA: Excepción Co-Docente Justificada]
|
|
C3 --> V3
|
|
V2 -- No --> V3
|
|
|
|
V3{¿Alumno cursa otra materia regular el mismo día?}
|
|
V3 -- Sí --> C4{¿Es Curso Corto o Autorizado?}
|
|
C4 -- No --> Err4[BLOQUEO: Regla Restricción Diaria]
|
|
C4 -- Sí --> Ok[ASIGNACIÓN EXITOSA]
|
|
V3 -- No --> Ok
|
|
```
|
|
|
|
---
|
|
|
|
## 5. Diseño Técnico: Base de Datos Relacional Normalizada
|
|
|
|
Para soportar las reglas de co-docencia, inscripciones, evaluaciones y restricciones de día, el esquema de datos evolucionará hacia la siguiente estructura:
|
|
|
|
### Entidades Principales
|
|
1. **`academic_terms` (Ciclos Lectivos):** `id`, `name`, `code` (ej. '2026-1C'), `year`, `term_type` ('1C', '2C', 'ANUAL', 'CORTO'), `start_date`, `end_date`, `is_active`.
|
|
2. **`subjects` (Materias / Asignaturas):** `id`, `code`, `name`, `career_id`, `is_short_course` (boolean), `credits`, `active`.
|
|
3. **`commissions` (Comisiones de Cursada):** `id`, `subject_id`, `term_id`, `code`, `shift`, `schedule_display`, `max_students`, `virtual_link`, `active`.
|
|
4. **`commission_teachers` (Co-docencia / Equipo Docente):** `id`, `commission_id`, `teacher_id`, `role` ('TITULAR', 'ADJUNTO', 'AYUDANTE'), `can_grade` (boolean).
|
|
5. **`commission_schedules` (Asignación Horaria y Espacial):**
|
|
* `id`, `commission_id`, `day_of_week` (1=Lunes .. 7=Domingo), `start_time`, `end_time`, `classroom_id` (física o virtual), `is_virtual`.
|
|
* *Constraint de Integridad:* `UNIQUE(classroom_id, day_of_week, start_time, end_time)` para aulas no virtuales.
|
|
6. **`enrollments` (Inscripciones de Alumnos):** `id`, `commission_id`, `student_id`, `status` ('REGULAR', 'CONDICIONAL', 'LIBRE', 'PROMOVIDO'), `enrolled_at`, `allow_same_day_exception` (boolean).
|
|
7. **`evaluation_milestones` (Hitos Evaluativos):** `id`, `commission_id`, `milestone_type_id`, `title`, `date`, `start_time`, `weight_percentage`, `is_mandatory`.
|
|
8. **`student_grades` (Calificaciones y Actas):** `id`, `milestone_id`, `student_id`, `numeric_score`, `concept_score`, `feedback`, `graded_by_teacher_id`, `graded_at`.
|
|
|
|
---
|
|
|
|
## 6. Diseño de Contratos de API RESTful (Backend Core)
|
|
|
|
### A. Módulo de Comisiones y Co-docencia
|
|
* `GET /api/v1/commissions`: Filtro por término académico, carrera, asignatura, turno y estado.
|
|
* `POST /api/v1/commissions`: Alta de comisión vinculada a una asignatura con generación automática de Meet.
|
|
* `POST /api/v1/commissions/{id}/teachers`: Asignación de docentes con rol en cátedra (co-docencia).
|
|
* `DELETE /api/v1/commissions/{id}/teachers/{teacher_id}`: Desvinculación de docente.
|
|
|
|
### B. Módulo de Matriz de Conflictos y Validación
|
|
* `POST /api/v1/schedules/validate`:
|
|
* **Payload:** `{ commission_id, classroom_id, day_of_week, start_time, end_time, teacher_ids, student_ids }`
|
|
* **Respuesta:** `{ valid: boolean, conflicts: [ { type: 'PHYSICAL'|'TEACHER'|'STUDENT_DAILY', message, details } ] }`
|
|
|
|
### C. Módulo de Hitos Evaluativos y Libro de Calificaciones
|
|
* `GET /api/v1/commissions/{id}/milestones`: Listado de exámenes, entregas y parciales.
|
|
* `POST /api/v1/commissions/{id}/milestones`: Creación de hito evaluativo.
|
|
* `GET /api/v1/commissions/{id}/gradebook`: Matriz completa de alumnos y notas de la comisión.
|
|
* `PUT /api/v1/commissions/{id}/gradebook`: Carga masiva o individual de calificaciones por docente.
|
|
|
|
### D. Modo Impersonación de Superadmin
|
|
* Cabecera HTTP: `X-Impersonate-User: {user_id}`
|
|
* Procesamiento en `authMiddleware`: Si el token emisor corresponde al rol `SUPERADMIN`, el contexto de ejecución adopta los permisos y vistas del usuario destino para auditoría, dejando registro en `audit_logs`.
|
|
|
|
---
|
|
|
|
## 7. Directrices UI/UX para el Frontend BFF
|
|
|
|
1. **Panel de Bedelía:**
|
|
- Grilla interactiva semanal (tipo TimeGrid) donde los bloques de comisiones se visualizan codificados por color según edificio, aula física o aula virtual.
|
|
- Detección inmediata de colisiones con carteles de advertencia flotantes antes de confirmar cambios.
|
|
2. **Matriz de Carga Rápida para Docentes:**
|
|
- Tabla editable en línea (*spreadsheet-like*) para volcar notas de parciales y entregas sin recargar la página, con autoguardado asíncrono.
|
|
3. **Perspectiva del Alumno:**
|
|
- Interfaz simplificada con diseño enfocado en dispositivos móviles, mostrando en la tarjeta de inicio la clase del momento con botón directo para ingresar a la videollamada o indicador de piso y aula física.
|
|
|
|
---
|
|
|
|
## 8. Conclusión del Diagnóstico
|
|
|
|
El sistema ha superado con éxito la fase de desacople inicial y estabilización de virtualidad:
|
|
- Se logró paridad total con `legacy_admin-edu-space` en importación de cronograma y cartelera.
|
|
- Se eliminaron las fallas de colisión virtual y se establecieron los 4 dashboards por rol.
|
|
- Se completó el acople de la ficha de reserva (`schedule.view_reservation`) y la creación asistida de comisiones en el BFF.
|
|
|
|
Las siguientes etapas se concentrarán en la consolidación de las reglas académicas complejas (co-docencia, restricción diaria de cursada, matriz de conflictos y libro de calificaciones) detalladas en el **`ROADMAP_MVP.md`**.
|