docs: estado de migracion, arquitectura objetivo UniCABA, roadmap MVP y changelog oficial
This commit is contained in:
@@ -0,0 +1,223 @@
|
||||
# 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`**.
|
||||
Reference in New Issue
Block a user