# 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`**.