carlostellocba/admin-edu-space
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
dev
admin-edu-space/ESTADO_MIGRACION_Y_ARQUITECTURA_OBJETIVO.md
T

15 KiB
Raw Permalink Blame History

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

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 View Git Blame Copy Permalink