diff --git a/CHANGELOG.md b/CHANGELOG.md index 7056fd2..e8e37c1 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -11,6 +11,22 @@ El formato está basado en [Keep a Changelog](https://keepachangelog.com/es-ES/1 - **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.6.0] - 2026-10-16 +### Added +- **Migración Integral del Backend Core a FastAPI (Principio 11)**: + - **Arquitectura en 4 Capas Desacoplada**: Implementados `backend/main.py` (FastAPI bootstrap), `backend/routers/` (APIRouters modulares), `backend/schemas/` (Pydantic v2 BaseModels con validación declarativa) y `backend/database.py` (persistencia relacional). + - **Routers FastAPI de Alto Rendimiento**: + - `routers/version.py`: Endpoint `/api/v1/version` identificando el motor FastAPI ASGI. + - `routers/auth.py`: Autenticación híbrida (Local con fallback admin, Google OAuth 2.0 institucional, Moodle delegado, cookies JWT `HttpOnly`, revocación y refresh silencioso). + - `routers/classrooms.py`: ABM de aulas físicas y virtuales con filtros granulares y auditoría. + - `routers/reservations.py`: Gestión integral de reservas con matriz de colisiones física, docente y aforo, y respuestas semánticas 409 Conflict. + - `routers/students.py`: Consulta de calificaciones individuales e hitos académicos. + - `routers/dashboard.py`: Métricas operativas en tiempo real (día, mañana, semana y mes) y sincronización con Google Sheets. + - `routers/optimizer.py` y `/api/genetic`: Trabajos de optimización áulica y sincronización Spring Boot. + - **Documentación Interactiva Automática**: Swagger UI expuesto nativamente en `/docs`, ReDoc en `/redoc` y OpenAPI v3 en `/openapi.json`. + - **Puente ASGI/WSGI de Cero Regresión**: Integración con `a2wsgi` para delegar sin interrupción cualquier módulo legado manteniendo compatibilidad total con Gunicorn, Uvicorn y systemd. + - **Suite de Pruebas**: Suite ampliada a 57 tests automatizados con 100% de éxito (`57 passed`). + ## [3.5.7] - 2026-10-16 ### Added - **Principio 11 de la Constitución: Estándares Modernos de APIs (FastAPI/Pydantic) e Integración con Modelos de IA (LLMs)**: diff --git a/MEMORY.md b/MEMORY.md index 1069423..c6ef855 100644 --- a/MEMORY.md +++ b/MEMORY.md @@ -1,296 +1,309 @@ -# 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. - -- **Depuración de Mocks en Dashboard**: Se eliminaron los arrays estáticos de fallback (`upcoming_reservations`, `today_schedule_list`, etc.) en `frontend/src/routes/dashboard.js` que mostraban asignaturas ficticias ("Matemática Discreta", "Sistemas Operativos", "Ingeniería de Software") en ausencia de datos reales. -- **Resolución de Error 500 en Aulas Presenciales y Virtuales**: Se reparó el balance de etiquetas de Nunjucks en `frontend/views/classrooms/list.html` y se reubicaron los modales de eliminación en el bloque físico. Validado con HTTP 200 en `/classrooms/list_classrooms?view_mode=physical` y `view_mode=virtual`. -- **Estandarización de Versiones (v3.4.0)**: Expuesto en Backend (`/api/v1/version`), Frontend BFF (`/version`), badges en el pie de página de la barra lateral (`sidebar-footer`) y en la pantalla de inicio de sesión (`login.html`). -- **Materias Compartidas en Múltiples Carreras (Many-to-Many)**: Se creó la tabla `subject_careers` en la base de datos relacional para asociar una materia a múltiples carreras simultáneamente (ej: IOT en DATOS, TEC. DIG y VIDEOJUEGOS, o Teoría y Práctica en PROF PROF y CIENCIAS), manteniendo `career_id` principal por retrocompatibilidad. -- **Normalización del Importador de Google Sheets**: `sheets_importer.py` descubre dinámicamente las 6 pestañas semanales (Lunes a Sábado), desglosa y mapea de forma canónica las carreras separadas por guion (`-`), soporta códigos combinados (`/`) y desglosa métricas por día de cursada (`by_day`). -- **Reactivación de Bedelía en Producción**: Activada la cuenta `bedelia@edu-space.com` para trabajo operativo institucional continuo. - -- **Corrección de Vistas de Bedelía (Reservas de Hoy, Semana, Aulas Libres y Comisiones Sin Aula)**: - - **Causa Raíz de Reservas Vacías**: `sheets_importer.py` generaba reservas únicamente para `weeks_to_generate = 4` a partir del 31 de agosto de 2026 (finalizando el 26 de septiembre). En la fecha actual de octubre de 2026 (`2026-10-07`), la base de datos tenía 0 reservas para el día y la semana. Se amplió a `weeks_to_generate = 16` cubriendo todo el 2° cuatrimestre regular (hasta el 19 de diciembre de 2026), generando **2464 reservas totales**, **34 clases para hoy** y **154 clases para la semana actual**. - - **Fecha Dinámica en Cartelera**: Se corrigió `handleTodaySchedule` en `frontend/src/routes/schedule.js` que tenía hardcodeado `2026-09-18` como fecha por defecto, reemplazándolo por la fecha actual ISO (`new Date().toISOString().split('T')[0]`) y añadiendo navegación interactiva entre días (`prev_date`, `next_date`, y botón "Hoy"). - - **Panel Operativo de Cartelera & Agenda en Dashboard**: Se incorporó en el Dashboard de Bedelía la sección "Cartelera Operativa & Agenda de Clases" con tabs dinámicos para alternar entre "Clases de Hoy" y "Esta Semana", visualizando horario, aula física o sala virtual (con enlace directo a Meet), materia, comisión, turno y docente. - - **Aulas Disponibles por Período**: Se agregó el selector interactivo "Hoy" (con 18 aulas libres detectadas para el día), "Esta Semana" y "Este Mes" en el panel `#bedelia-available-classrooms`, permitiendo asignar aulas libres con un clic. - - **Comisiones Sin Aula Física ni Virtual**: Se agregó el tab "Sin Aula Física ni Virtual (General)" en `#bedelia-unassigned-commissions` para identificar comisiones sin asignación de espacio, y se añadió la columna "Espacio / Aula" con filtro rápido `unassigned_room=true` en `/admin/commissions_list`. -- **Filtrado Temporal de Aulas y Comisiones (Día, Semana y Mes)**: - - **Requerimiento**: Poder filtrar tanto **Aulas Asignadas** vs **Aulas Sin Asignar (Libres)** como **Comisiones Asignadas** vs **Comisiones Sin Asignar** por **Día**, **Semana** y **Mes**, con la opción de **Día por defecto** y aclarando la **fecha explícita** para fácil identificación de todos los usuarios. - - **Backend (`dashboard.py`)**: Se calculan estructuras `filter_stats` para los tres períodos (`today`, `week`, `month`) con métricas precisas (counts, porcentajes) y diccionarios legibles `date_labels` en español ("Hoy · Miércoles 07/10/2026", "Semana del 05/10 al 11/10/2026", "Mes de Octubre 2026"). - - **Frontend BFF & UI (`dashboard.js`, `dashboard.html`)**: - - **Panel de Percentiles**: Switcher interactivo `[ Día (Hoy) ]` (activo por defecto), `[ Semana ]` y `[ Mes ]` con badge explícito de fecha y barras reactivas. - - **Panel de Comisiones**: Switcher `[ Día (Hoy) ]`, `[ Semana ]`, `[ Mes ]` con badge de fecha explícita, más pestañas para conmutar entre "Comisiones Asignadas (Con Aula)" y "Comisiones Sin Asignar (Pendientes)" con acciones directas para asignar espacio. - - **Panel de Aulas**: Switcher `[ Día (Hoy) ]`, `[ Semana ]`, `[ Mes ]` con badge de fecha explícita, más pestañas para conmutar entre "Aulas Sin Asignar (Libres)" y "Aulas Asignadas (En Uso)" con acceso directo a cartelera o asignación inmediata. - - **Validación en Producción**: Desplegado en `https://eduspace.oemspot.com.ar` y verificado con éxito (HTTP 200 en login de Bedelía y renderizado exacto de datos reales). - -- **Evolución del Importador de Google Sheets (Filtros por Carrera, Materia, Día y Fecha Manual)**: - - **Requerimiento**: Permitir filtrar qué Carrera, qué Materia y qué Día importar desde el Google Sheet online de UniCABA, como así también agregar la fecha manualmente para corregir o evitar errores si el Sheet no tiene la fecha o se requiere asignar una clase puntual en el calendario. - - **Backend (`sheets_importer.py` & `dashboard.py`)**: - - Se implementó `inspect_sheet_content()` que descarga e inspecciona las 6 hojas del Sheet online en ~7s, descubriendo de forma dinámica todas las Carreras únicas (18 carreras detectadas) y Materias únicas (206 materias detectadas). - - Se agregaron los parámetros `filter_career`, `filter_subject`, `filter_day`, `manual_date` y `single_date_only` al método `sync(...)`. - - Normalización robusta de días con `normalize_day_name(...)` insensible a acentos y mayúsculas. - - Soporte de coincidencia parcial y sensible a carreras compuestas (ej: `DATOS (CCC)` coincide con asignaturas compartidas con `TEC. DIG.` y `VIDEOJUEGOS`). - - Soporte de asignación de fecha puntual manual (`single_date_only=True`), creando 1 única reserva para esa fecha exacta en vez de las 16 semanas regulares, o tomando la fecha manual como base del cuatrimestre. - - Nuevo endpoint REST `GET/POST /api/v1/dashboard/sheets-inspect` y actualización de `/api/v1/dashboard/sync-sheets`. - - **Frontend BFF & UI (`admin.js` & `import.html`)**: - - Panel interactivo "Sincronización Académica con Filtros Avanzados y Control de Fecha". - - Selectores dinámicos de Día (Todos, Lunes, Martes, etc.), inputs con autocompletado `` para Carreras y Materias. - - Selector interactivo de Fecha Manual (`type="date"`) con switch toggle para "Importar ÚNICAMENTE para esta fecha puntual". - - Botón "Inspeccionar Sheet Online" con llamada AJAX a `/admin/sheets_inspect` que carga en vivo las carreras y materias descubiertas. - - Tarjeta de informe detallado post-sincronización con badges temáticos de "Filtros Activos", número de "Filas Coincidentes" vs totales, y modo de generación. - - **Validación en Producción**: - - Pruebas automatizadas de backend: 49 tests aprobados en pytest (100% passed). - - Desplegado en producción institucional (`https://eduspace.oemspot.com.ar`). - - Verificación online con `bedelia@edu-space.com`: HTTP 200 en `/admin/google_sheets_import`, endpoint `/admin/sheets_inspect` retornando 239 filas y 18 carreras, y sincronización filtrada con éxito (ej. Martes + DATOS procesando exactamente sus 3 filas coincidentes). - -- **Sprint v3.4.1: Corrección de Bug en Import Sheet, Aulas Virtuales en Bedelía, Modularización de Vistas y Reglas de Workflow**: - - **Fix Bug Google Sheets Import (`Error loading Google Sheets sync view`)**: - - **Causa Raíz**: `availableCareers` y `availableSubjects` se declaraban únicamente dentro de un bloque condicional en `admin.js`, provocando `ReferenceError: availableCareers is not defined` en peticiones GET normales. - - **Solución**: Se declararon e inicializaron a nivel de función `handleGoogleSheetsImport` tanto en la consulta inicial de `Promise.allSettled` como en el refresh posterior a la sincronización. - - **Fix Bug Aulas Virtuales en Dashboard de Bedelía**: - - **Causa Raíz**: El conteo `virtual_classrooms` en `dashboard.py` calculaba `len(virtual_classrooms_list)` sobre la tabla relacional `classrooms`, que solo contiene 1 registro genérico (`id: 331, code: 'VIRTUAL', building: 'Campus Virtual'`). - - **Solución**: Se actualizó la lógica para calcular las salas virtuales a partir de las comisiones activas con modalidad virtual (Google Meet/Teams/Zoom) o reservas en Campus Virtual, reportando las 101 salas virtuales activas. Se incorporó el arreglo `virtual_rooms` en `role_data` de Bedelía y se agregó la pestaña *"Salas Virtuales (Campus Virtual)"* con 127 enlaces a Google Meet en el panel de Aulas (`dashbede.html`). - - **Modularización de la Arquitectura de Vistas (`dashboard.html` como Layout Padre)**: - - Se dividió el archivo monolítico `dashboard.html` de más de 2300 líneas en 4 componentes/subvistas según el rol del usuario: - - `dashadm.html` (Administrador) - - `dashbede.html` (Bedelía) - - `dashprof.html` (Docente / Profesor) - - `dashalum.html` (Alumno / Estudiante) - - `dashboard.html` actúa ahora como layout/plantilla padre limpia que inyecta la subvista correspondiente mediante `{% include %}` de Nunjucks. - - **Actualización de Reglas en `docs/constitution.md` (Principio 9)**: - - Se agregó el Principio 9 innegociable: - 1) Siempre actualizar y guardar el control de la nueva versión semántica al momento de compilar. - 2) Al finalizar la compilación, siempre subir y desplegar la nueva versión al servidor institucional de producción. - - **Despliegue y Verificación en Producción**: - - Versionado elevado a `v3.4.1`. - - Desplegado exitosamente en el servidor LXC `10.0.0.217` (`https://eduspace.oemspot.com.ar`). - - Verificación HTTP 200 en `/version`, login admin, `/admin/google_sheets_import`, dashboards modularizados de los 4 roles y cuenta institucional de Bedelía. -- **Sprint UX/UI: Agrupación Cronológica de Reservas y Formato Limpio de Fechas (v3.4.2)**: - - **Problema 1: Duplicación de Reservas por Hora en Cartelera**: - - En `/schedule/today_schedule`, un bucle fijo `for (let hour = 7; hour <= 21; hour++)` insertaba la misma reserva en cada bloque horario de 1 hora que abarcaba la materia (ej. Marketing Digital de 08:00 a 11:00 hs aparecía repetida a las 8, 9 y 10). - - **Solución**: Se eliminó la clonación artificial y se introdujo la agrupación nativa por franja horaria real de cursada (`grouped_slots`, ej. `08:00 - 11:00 hs`, `18:30 - 21:00 hs`). Cada reserva aparece agrupada exactamente UNA SOLA VEZ en su bloque horario correspondiente con turno, duración, aula, cupo y enlace a Meet/Zoom. - - **Problema 2: Formato ISO Crudo en Listado de Reservas**: - - En `/schedule/list_reservations` (tabla y tarjetas) se mostraban strings crudos con 'T' y segundos (`2026-10-08T08:00:00 - 2026-10-08T11:00:00 hs`). - - **Solución**: Se enriquecieron todas las reservas con la función `formatReservationDates` y nuevos filtros Nunjucks (`format_date_human`, `format_time`, `format_time_range`), mostrando fecha limpia (`Jueves 08/10/2026` / `08/10/2026`) y horario amigable (`08:00 - 11:00 hs`). - - **Bump Semántico y Despliegue Obligatorio (Principio 9)**: - - Versión incrementada a `v3.4.2` en Frontend y Backend. - - Despliegue inmediato al servidor institucional `10.0.0.217` y verificación en caliente. -- **Sprint Importador Google Sheets: Selección Granular y Grilla Interactiva (v3.4.3)**: - - **Selección Granular de Entidades (Tarjetas Checkbox)**: - - Réplica del diseño visual de la Herramienta de Purga con botones "Marcar Todo" y "Desmarcar Todo". - - Toggles individuales para Asignaciones de aulas (`import_reservations`), Aulas físicas y virtuales (`import_classrooms`), Comisiones (`import_commissions`), Asignaturas (`import_subjects`) y Carreras (`import_careers`). - - **Selector de Días de la Semana con Checkboxes Múltiples**: - - Reemplazo del selector simple por checkboxes individuales para Lunes a Sábado con accesos rápidos ("Todos", "Lun a Vie", "Limpiar"). - - **Grilla de Previsualización Interactiva e Inspección Previa**: - - El botón "Inspeccionar Sheet Online" no importa directamente; extrae y presenta una grilla interactiva completa (`preview_rows`) de registros online. - - Selección individual por fila y checkbox maestro superior. - - Modificación manual inline de fechas de cursada por fila mediante Datepicker (``) y aplicador de fecha masiva a seleccionados. - - Resaltado visual con badges de alerta y error ante registros incompletos o aulas no reconocidas. - - Buscador en vivo multi-criterio y paginación fluida (25 filas por página) para evitar bloqueos del navegador. - - Modal de confirmación previa con desglose exacto de filas y entidades antes de iniciar la sincronización. - - **Backend y BFF REST**: - - `sheets_importer.py` ampliado para retornar `preview_rows` y procesar `selected_rows` con granularidad de entidades. - - Endpoints `POST /api/v1/dashboard/sheets-inspect` y `POST /api/v1/dashboard/sync-sheets`. - - **Bump Semántico y Despliegue Obligatorio (Principio 9)**: - - Versión incrementada a `v3.4.3` en Frontend y Backend. - - Despliegue y verificación en caliente en el servidor institucional `10.0.0.217` (`https://eduspace.oemspot.com.ar`). - -- **Sprint Dashboard Bedelía: Filtro Temporal "Mañana" en Switchers y Cartelera (v3.4.4)**: - - **Requerimiento**: Agregar "Mañana" en el filtro actual del dashboard que decía "Día (Hoy) / Semana / Mes". - - **Implementación**: - - **Backend API (`backend/app/routes/api/dashboard.py`)**: Cálculo de `tomorrow_dt` (00:00:00 a 23:59:59), agregando estadísticas en `filter_stats['tomorrow']` para percentiles de aulas físicas y comisiones asignadas/sin asignar, y `tomorrow_schedule_list` para la agenda de clases. - - **Frontend BFF & Vistas (`frontend/views/dashboard/dashbede.html`, `dashbede.html`, `dashadm.html`, `dashboard.html`)**: - - Switcher de percentiles: botón "Mañana" con actualización dinámica de percentiles de ocupación de aulas físicas. - - Switcher de comisiones: botón "Mañana" y bloques `#commBlock-tomorrow-unassigned` y `#commBlock-tomorrow-assigned`. - - Switcher de aulas físicas: botón "Mañana" y bloques `#classBlock-tomorrow-unassigned` (aulas libres con botón "Asignar") y `#classBlock-tomorrow-assigned` (aulas en uso). - - Cartelera Operativa & Agenda de Clases: botón "Clases de Mañana" y tabla `#bedeliaScheduleTomorrow` mostrando asignaturas, comisiones, docentes y enlaces para mañana. - - **Bump Semántico y Despliegue Obligatorio (Principio 9)**: - - Versión incrementada a `v3.4.4` en Frontend y Backend. - - Despliegue al servidor institucional `10.0.0.217` (`https://eduspace.oemspot.com.ar`) y verificación en caliente. - -- **Sprint Optimizador de Aulas IA: Corrección de Permisos y Carga de Comisiones (v3.4.5)**: - - **Problema Reportado**: AI Room Reservation Optimizer no mostraba comisiones y los indicadores de Available Classrooms, Active Commissions y Existing Reservations quedaban en `--`. - - **Causa Raíz Identificada**: - - En `backend/app/routes/genetic_algorithm.py` las rutas `@genetic_bp.route('/commissions')`, `/algorithm-status`, `/preview-optimization`, `/optimize` y `/apply-optimization` exigían de forma estricta `g.jwt_user.role in ['ADMIN', 'teacher']` o `g.jwt_user.role in ['ADMIN']`. - - Al ingresar como Bedelía (`role == 'Bedelia'`), Docentes o Administradores con rol en minúsculas, el backend devolvía `403 Forbidden`, bloqueando la llamada AJAX y dejando la interfaz vacía con `--`. - - En el Frontend BFF, la ruta `/genetic_optimizer` no requería `requireAuth` ni pasaba datos de sesión de usuario a la plantilla. - - **Solución Implementada**: - - Creación del helper `check_optimizer_permission(user, requires_write)` en `backend/app/routes/genetic_algorithm.py` habilitando acceso a `admin`, `administrador`, `bedelia`, `docente`/`teacher` y permisos RBAC en 'optimizer'. - - `GET /api/genetic/commissions` ahora enriquece los objetos con `subject_name`, `subject_code`, `career_name`, `schedule` y `shift`. - - `frontend/views/genetic_optimizer.html`: Traducido íntegramente a español institucional ("Optimizador Inteligente de Asignación de Aulas (IA)"), tarjetas de comisiones con badges, buscador en vivo multi-criterio y manejo de errores visual. - - `frontend/public/js/genetic-algorithm.js`: Traducción de alertas, modales y tablas de resultados. - - `frontend/src/app.js`: Protección con `requireAuth` e inyección de sesión a la vista. - - **Bump Semántico y Despliegue Obligatorio (Principio 9)**: - - Versión incrementada a `v3.4.5` en Frontend y Backend. - - Despliegue inmediato al servidor institucional `10.0.0.217` y verificación en caliente HTTP 200. - -- **Sprint v3.4.6: Corrección Integral de Reservas, Pisos Dinámicos, Fechas Humanas y Filtro de Carreras**: - - **Incidencias Resueltas**: - 1. `/schedule/add_reservation` y `/schedule/edit`: Corregido error de serialización JSON que rompía el selector en cascada Edificio -> Piso -> Aula al seleccionar "Edificio Central". Inyección segura sin entities y matching resiliente de pisos físicos y virtuales. - 2. `/schedule/calendar_view`: Limpieza de datos hardcodeados/mockeados (`Arquitectura de Software ARQ-101`, `COM-A`, `Licenciatura en Sistemas`). El feed y filtros ahora consumen asignaturas, carreras y comisiones reales de la BD. - 3. `sheets_importer.py`: Eliminada la autogeneración no deseada de enlaces de Google Meet / Zoom (`meet.google.com/edu-...`) en reservas importadas cuando la celda original está vacía (ej. `#9797 ASIG00215 - Marketing Digital`). - 4. `/classrooms/view_classroom`: Formateadas fechas y horarios a español legible (ej. `Viernes 04/09/2026 · 18:30 a 21:30 hs`) eliminando formato ISO repetido y ampliando rango a todo el semestre 2026. - 5. `/buildings/list_buildings` y `/buildings/view/:id`: Corregida la ficha de edificio que mostraba "No hay aulas asignadas a este edificio" a pesar de tener 6 aulas físicas asociadas (`floors_list` y `classrooms_by_floor`), corregido el contador de "Pisos Presenciales" (4 pisos) y soporte completo de niveles dinámicos alfanuméricos (PB, EP, Subsuelo, etc.). - 6. `/admin/commissions_list`: Corregido `UnboundLocalError` en `backend/app/routes/api/admin.py` por importación interna tardía de `Career`, que arrojaba HTTP 500 al filtrar por `career_id=180, 181, 182`. -- **Sprint v3.4.8: Registro de Auditoría Institucional y Trazabilidad Operativa**: - - **Incidencias y Mejoras**: - 1. `/api/v1/admin/audit-logs`: Implementación del endpoint RESTful con paginación, filtros por módulo (`auth`, `reservations`, `classrooms`, `buildings`, `optimizer`, `admin`, etc.), acción (`LOGIN`, `LOGIN_FAILED`, `CREATE`, `UPDATE`, `DELETE`, `CONFIRM`, etc.) y búsqueda multi-campo. - 2. Modelo `AuditLog`: Agregado método `to_dict()` para serialización JSON segura e ISO. - 3. `AuditService`: Soporte de parámetros explícitos `user_id` y `user_email` para registrar eventos cuando el usuario no está autenticado o el intento de acceso falla. - 4. `/api/v1/auth/`: Instrumentada la captura de inicios de sesión (`LOGIN`), Google OAuth (`LOGIN_GOOGLE`), Moodle delegado (`LOGIN_MOODLE`), fallos de inicio de sesión (`LOGIN_FAILED`), accesos bloqueados (`LOGIN_BLOCKED`), cierres de sesión (`LOGOUT`) y cambios de contraseña institucional (`PASSWORD_CHANGE`). - 5. `/api/v1/reservations`: Auditoría de creación (`CREATE`), edición (`UPDATE`), cancelación (`CANCEL`), borrado permanente (`DELETE`) y confirmación oficial (`CONFIRM`). - 6. `/api/v1/classrooms` y `/api/v1/buildings`: Auditoría de altas, modificaciones, alternancia de estado activo/inactivo (`TOGGLE`) y bajas. - 7. Optimizador Genético IA: Auditoría de ejecuciones (`OPTIMIZE_RUN`) y aplicación de asignaciones masivas en base de datos (`OPTIMIZE_APPLY`). - 8. Frontend BFF (`/admin/audit_logs`): Conexión del BFF con la REST API, badges temáticos e intuitivos, filtros rápidos por categorías, visor modal para detalles extensos o JSON, y paginador dinámico nativo que preserva parámetros de consulta. - - **Bump Semántico y Despliegue Obligatorio (Principio 9)**: - - Versión incrementada a `v3.4.8` en Frontend y Backend. - -- **Sprint v3.4.9: Solución de Límite de Payload en Importador de Sheets & Diagnóstico Transparente de Incidentes**: - - **Incidencias y Mejoras**: - 1. `frontend/src/app.js`: Elevado límite de `express.json` y `express.urlencoded` de 100 KB por defecto a 50 MB (`{ limit: '50mb' }`), resolviendo el error `PayloadTooLargeError: request entity too large: expected 154166, length 154166, limit 102400` que provocaba HTTP 500 al enviar la matriz de filas preseleccionadas en `/admin/google_sheets_import`. - 2. Manejo de Incidentes y Diagnóstico Transparente: Reemplazo total de la pantalla genérica de error por una interfaz estructurada con código de ticket único (`INC-YYYYMMDD-XXXX`), diagnóstico descriptivo clasificado, sección técnica de diagnóstico colapsable (Ruta, Timestamp, Usuario actuante, IP, Stack trace), botón para copiar reporte a soporte IT y enlace directo a la Auditoría Institucional. - 3. `backend/app/routes/api/admin.py`: Nuevo endpoint `/api/v1/admin/log-error` para registrar incidentes técnicos no controlados del frontend directamente en `AuditLog` (`action='SYSTEM_ERROR'`, `module='system'`). - 4. `backend/app/routes/api/dashboard.py`: Instrumentada auditoría completa en `sync_google_sheets` para registrar tanto importaciones exitosas (`SHEETS_IMPORT`) como fallos (`SHEETS_IMPORT_ERROR`) con desglose de estadísticas y excepciones. -- **Sprint v3.5.0: Cierre Formal del MVP de Bedelía & Adopción del Arnés SDD / IA**: - - **Metodología y Arnés de Ingeniería con IA (Apuntes Día 1, 2 y 3)**: - 1. Creación de la Skill de SDD (`.agents/skills/sdd/SKILL.md`) con las plantillas de `spec.md`, `plan.md`, `tasks.md` y sintaxis formal **EARS** en español. - 2. Creación de comandos reutilizables de agentes en `.opencode/commands/` (`sdd-spec`, `sdd-plan`, `sdd-tasks`). - 3. Definición de roles de subagentes en `.opencode/agents/`: Coordinator, Planner, Implementer, Reviewer (QA). - 4. Integración del arnés en `AGENTS.md`. - - **Diagnóstico y Cierre de Brecha del MVP**: - - Se identificó la causa raíz de la percepción de "estar lejos": el *Scope Creep* sin especificación formal de cierre y la falta de exportación/impresión de carteleras que forzaba a Bedelía a recurrir al Excel para imprimir o compartir partes con portería y docentes. - - Se formalizó la primera especificación oficial del proyecto en `specs/001-cierre-mvp-bedelia/` (`spec.md`, `plan.md`, `tasks.md`), delimitando de forma estricta los Requisitos Funcionales en **EARS** y estableciendo un perímetro cerrado de **Fuera de Alcance**. - - **Implementación Técnica**: - 1. `frontend/src/routes/schedule.js`: Endpoint `/schedule/export_csv` con codificación UTF-8 BOM (`\uFEFF`) y delimitadores `;` para apertura nativa e inmediata en Microsoft Excel en español. - 2. `frontend/views/schedule/today.html`: Botones directos `[ Excel / CSV ]` e `[ Imprimir ]`, acompañados de estilos CSS `@media print` que formatean la grilla de asignaciones en hoja A4 limpia con membrete institucional oficial de UniCABA. - 3. `frontend/views/dashboard/dashbede.html`: Accesos rápidos en el Launchpad operativo de Bedelía para descargar la planilla del día e imprimir en 1 clic. - - **Calidad y Bump Semántico (Principio 9)**: - - 52 pruebas de backend ejecutadas con 100% de éxito en pytest (`52 passed`). - - Versión incrementada a `v3.5.0` en `package.json`, `app.js`, `__init__.py`, `setup.py` y `openapi.py`. - -- **Sprint v3.5.1: Exportación y Replicación Moodle Producción a Local con Usuarios y Emails Reales**: - - **Especificación SDD (`specs/002-moodle-export-sync/`)**: Creados `spec.md` (6 RF en EARS), `plan.md` y `tasks.md` (todas las tareas completadas). - - **Extracción Híbrida y Concurrente con Emails Reales**: - - `scripts/moodle_replicator.py` se autentica en `https://campus.udelaciudad.edu.ar/` con `logintoken` dinámico. - - Obtiene la nómina masiva estructurada vía `/user/action_redir.php` (`download_participants&dataformat=json`). - - Consulta de forma concurrente (ThreadPool con 10 workers) los perfiles de los usuarios (`user/view.php`) extrayendo sus correos personales y reales (`@gmail.com`, `@hotmail.com`, etc.), eliminando cualquier generación de emails inventados. - - Normalización fonética/ortográfica sin acentos (`normalize_name`) para vincular con 100% de precisión docentes y estudiantes entre HTML y JSON. - - **Reglas de Acceso y DNI Determinístico**: - - DNI de 8 dígitos determinístico derivado del ID de Moodle (`90{moodle_id:06d}`), asignado idénticamente como `username` y `password` para pruebas locales. - - Preservado el DNI y correo real de Carlos Tello (`34247025`, `carlostellocba@gmail.com`). - - **Carga en Moodle Local (`10.0.0.207`)**: - - Creación y actualización de usuarios mediante Moodle REST API (`core_user_create_users`, `core_user_update_users`). - - 504 matriculaciones completadas exitosamente en los 4 cursos oficiales: - * Carrera Lic. en Tecnologías Digitales (CCC): ID Prod 922 -> ID Local 19 (194 alumnos). - * ASIG00124 - Sistemas Digitales_2/2026: ID Prod 5311 -> ID Local 16 (131 alumnos y 2 profesores). - * ASIG00126 - Seguridad de la Información_2/2026: ID Prod 5313 -> ID Local 17 (138 alumnos y 2 profesores). - * ASIG00127 - Programación de Vanguardia - E1_2/2026: ID Prod 5314 -> ID Local 18 (41 alumnos y 2 profesores). - - Desactivada la política restrictiva de contraseñas (`passwordpolicy=0`) en el entorno de pruebas local para permitir contraseñas numéricas idénticas al DNI. - - Verificación exitosa de login de estudiante en `http://10.0.0.207/moodle/login/index.php`. - - **Skill de Automatización**: Creada `.agents/skills/moodle-replicator/SKILL.md` con manual operativo y comandos CLI. - -- **Sprint v3.5.2: Replicación Completa de 16 Cursos, User-Agent Mozilla/5.0 y Fix de Credenciales**: - - **Catálogo Completo de la Carrera (16 Cursos)**: - - Se identificaron y replicaron la totalidad de las 15 materias de la Licenciatura en Tecnologías Digitales (1/2025, 2/2025, 1/2026 y 2/2026) más el curso de la carrera (Local 19). - - Resuelto el caso de alumnos como `90010202` (Carlos Guillermo Terzano): ahora cuenta con sus 6 materias reales cursadas (Local 4, 5, 8, 9, 10, 11) además de la carrera. - - Carlos Tello (`34247025`) matriculado en las 15 asignaturas y la carrera. - - Más de 1.100 matriculaciones procesadas y validadas con 100% de éxito. - - **Identificación y Asignación de Todos los Docentes**: - - Extraídos y asignados todos los profesores reales con rol `editingteacher` (ID 3) y correos institucionales `@udelaciudad.edu.ar`. - - **Cabecera HTTP y User-Agent**: - - Forzado estrictamente el encabezado `User-Agent: Mozilla/5.0 (Windows NT 10.0; Win64; x64)` en todas las solicitudes al campus para evitar alertas por `python-requests`. - - **Sincronización de Contraseña Local (Fix 34247025)**: - - Se corrigió la contraseña del usuario `34247025` restableciéndola a `34247025` idéntica al DNI en Moodle local. Verificado inicio de sesión exitoso. - -- **Sprint v3.5.3: Importación de Roles Moodle-App, Limpieza Total de Admin y Purga de Cursos**: - - **Sincronización RBAC de Roles Moodle a PostgreSQL de la App (`classrooms_db`)**: - - Desarrollado `scripts/import_moodle_to_app.py` y bandera `--sync-app` en `moodle_replicator.py`. - - Mapeo unívoco: Moodle `editingteacher` -> App `Docente` (`role_id=2`), Moodle `student` -> App `Alumno` (`role_id=6`). - - Importados **653 usuarios únicos** (15 Docentes y 640 Alumnos) a la base de datos de producción con contraseñas PBKDF2 coincidentes con el DNI, habilitando de inmediato la asignación de comisiones, reservas e inscripciones. - - **Desmatriculación de Cuenta Admin en Moodle Local (`10.0.0.207`)**: - - Removidas todas las matriculaciones de `admin` en cursos académicos y generales (quedando con 0 enrolments). - - **Sprint v3.5.4: Conexión Moodle API, Login Delegado y Sincronización Moodle -> Edu Space**: - - **Habilitación de Web Services para Tokens de Usuario en Moodle Local (`10.0.0.207`)**: - - Asignada la capability `moodle/webservice:createtoken` al rol 7 (`user` / usuario autenticado) en `mdl_role_capabilities`. - - Habilitado `enablemobilewebservice = 1` y servicio `moodle_mobile_app` (`enabled = 1`). - - Verificada la emisión de tokens exitosa para usuarios individuales (incluyendo `34247025`) tanto contra `moodle_api` como contra `moodle_mobile_app`. - - **Conexión de Admin Edu Space con Moodle Local**: - - Configurado el token `810428346d3601c68a37a315fcba8d4391629f46` de `moodle_api` en `system_settings` de `classrooms_db`. - - Habilitada `auth_moodle_enabled = 'true'` y `moodle_server_url = 'http://10.0.0.207/moodle'`. - - Adaptado el endpoint de autenticación `/api/v1/auth/moodle` para autenticar con `moodle_api` (con fallback a `moodle_mobile_app`) y hacer matching de cuenta local por número de documento (DNI). - - **Sincronización Bidireccional Moodle -> Edu Space**: - - Agregado el endpoint administrativo `POST /api/v1/admin/moodle/sync-from-moodle`. - - Incorporados los métodos `get_courses()`, `get_categories()` y `sync_from_moodle_to_app()` en `MoodleClient`. -- **Sprint v3.5.5: Autenticación por API Key para Moodle, Purga de Tareas y Hardening**: - - **Purga de Tareas de Sincronización Residuales**: - - Eliminadas las 6 tareas pendientes residuales de prueba (#1 a #6) en la tabla `moodle_sync_tasks` de `classrooms_db` en `10.0.0.217`, dejando la cola limpia en 0 registros. - - **Ampliación de Funciones Web Services en Moodle Local (`10.0.0.207`)**: - - Asignadas al servicio `moodle_api` las funciones `enrol_manual_unenrol_users`, `core_enrol_unenrol_user_enrolment`, `core_role_assign_roles` y `core_role_unassign_roles`, completando el catálogo a 15 funciones esenciales. - - **Seguridad por Restricción de Red (IP Restriction)**: - - Fijada la restricción de red `iprestriction = '10.0.0.0/24'` en `mdl_external_tokens`, asegurando que solo el tráfico interno institucional pueda utilizar los tokens de Moodle. - - **Autenticación por API Key Institucional en Admin Edu Space**: - - Creado mecanismo para autenticar endpoints de sincronización (`/settings/moodle/sync` y `/moodle/sync-from-moodle`) mediante `X-API-Key` institucional de 64 caracteres hex. - - Generada y almacenada la clave API institucional cifrada con Fernet en `system_settings` (`classrooms_db`). - - Agregados endpoints para consulta y regeneración de clave API (`/api/v1/admin/settings/moodle/api-key`). - -- **Sprint v3.5.6: Principio 10 de Tolerancia Cero a Errores de Código, Robustez en SystemSetting y Replicador**: - - **Principio 10 de la Constitución**: - - Incorporada regla mandatoria en `docs/constitution.md`, `AGENTS.md`, `.agents/skills/sdd/SKILL.md`, `.agents/skills/deploy/SKILL.md` y `.opencode/agents/` (`coordinator.md`, `implementer.md`, `reviewer.md`). - - Es estrictamente inadmisible declarar una tarea o sprint como terminado o completado si persisten errores en el código o en el analizador de la IDE (`@[current_problems]`). - - **Reparación de Tipos en Replicador Moodle**: - - Ajustado casteo a entero `int(course_meta['local_id'])` y `int(u.get('role_id', 5))` en `scripts/moodle_replicator.py`. - - **Robustez Híbrida en `SystemSetting`**: - - Implementado descriptor híbrido `_hybrid_setting_method` para `get_decrypted_value` y `get_masked_value`, permitiendo indistintamente la invocación como método de clase o de instancia sin errores de argumentos. - - **Resolución de Condición de Carrera en Tests de SQLite**: - - Añadida espera activa de finalización de workers en `test_05_api_async_job_submission_and_polling` para evitar bloqueos de base de datos en `tearDown()`. - - **Validación Automatizada**: - - 52/52 tests pasando en verde al 100% (`pytest tests -v`). - -- **Sprint v3.5.7: Principio 11 de la Constitución — Estándares Modernos de APIs (FastAPI/Pydantic) e Integración con Modelos de IA (LLMs)**: - - **Arquitectura Modular en 4 Capas**: - - Desacople estricto: `main.py` (bootstrap/registro), `routers/` (endpoints agrupados por dominio con prefijos y tags para Swagger), `schemas/` (contratos con Pydantic `BaseModel`), `storage.py` (acceso a persistencia). Prohibida la lógica de negocio en el frontend o en archivos monolíticos. - - **Tipado Fuerte y Validación Pydantic**: - - Uso obligatorio de `Field` para validaciones declarativas (`min_length`, `max_length`, `gt`, `ge`, regex). - - Distinción estricta de Path Parameters (obligatorios) y Query Parameters (opcionales tipados con defaults). - - Manejo y respuesta automática de error `422 Unprocessable Entity` detallando el campo exacto. - - **Semántica HTTP y Excepciones Controladas**: - - Uso de códigos de estado HTTP semánticos (`201 Created` en POST, `200 OK`, `204 No Content`). - - Prohibido retornar `null` o respuestas vacías ante fallos: levantar `HTTPException` controladas con detalle descriptivo (404, 400, 409). - - **Documentación Interactiva Automática**: - - Contratos OpenAPI expuestos en `/docs` (Swagger UI) con capacidades de prueba en vivo (*Try it out*). - - **Integración Asíncrona con Modelos de IA Locales (LLMs) & Asistente Virtual**: - - **Pestaña en Configuración Global**: Planificada en `ROADMAP.md` y UI administrativa para configurar URL del servidor local (Ollama, llama.cpp), modelo, token y timeout para el futuro asistente virtual de la app. - - **Cliente Asíncrono no Bloqueante**: Uso mandatorio de `httpx.AsyncClient` con `async def` / `await` para inferencias concurrentes sin bloquear el servidor. - - **Timeout Generoso**: Configurar timeout de 600 segundos previendo carga de modelos en VRAM o prompts extensos. - - **Formato Estándar de Roles**: Historial estructurado bajo `role: "system" | "user" | "assistant"` y `content: prompt`. - - **Actualización Documental Completa**: - - Sincronizados `docs/constitution.md` (Principio 11), `AGENTS.md`, `.agents/skills/sdd/SKILL.md`, `.opencode/agents/` (`coordinator.md`, `planner.md`, `implementer.md`, `reviewer.md`), `ROADMAP.md` (Fase 7) y `MEMORY.md`. - -## Próximos pasos -1. Monitorear los inicios de sesión delegados en producción con cuentas docentes y estudiantiles. -2. Implementar la pestaña de Asistente IA en la Configuración Global administrativa (`ROADMAP.md` Fase 7). -3. Continuar con el roadmap hacia la Fase 6 de hardening y orquestación de servicios en Docker. \ No newline at end of file +# 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. + +- **Depuración de Mocks en Dashboard**: Se eliminaron los arrays estáticos de fallback (`upcoming_reservations`, `today_schedule_list`, etc.) en `frontend/src/routes/dashboard.js` que mostraban asignaturas ficticias ("Matemática Discreta", "Sistemas Operativos", "Ingeniería de Software") en ausencia de datos reales. +- **Resolución de Error 500 en Aulas Presenciales y Virtuales**: Se reparó el balance de etiquetas de Nunjucks en `frontend/views/classrooms/list.html` y se reubicaron los modales de eliminación en el bloque físico. Validado con HTTP 200 en `/classrooms/list_classrooms?view_mode=physical` y `view_mode=virtual`. +- **Estandarización de Versiones (v3.4.0)**: Expuesto en Backend (`/api/v1/version`), Frontend BFF (`/version`), badges en el pie de página de la barra lateral (`sidebar-footer`) y en la pantalla de inicio de sesión (`login.html`). +- **Materias Compartidas en Múltiples Carreras (Many-to-Many)**: Se creó la tabla `subject_careers` en la base de datos relacional para asociar una materia a múltiples carreras simultáneamente (ej: IOT en DATOS, TEC. DIG y VIDEOJUEGOS, o Teoría y Práctica en PROF PROF y CIENCIAS), manteniendo `career_id` principal por retrocompatibilidad. +- **Normalización del Importador de Google Sheets**: `sheets_importer.py` descubre dinámicamente las 6 pestañas semanales (Lunes a Sábado), desglosa y mapea de forma canónica las carreras separadas por guion (`-`), soporta códigos combinados (`/`) y desglosa métricas por día de cursada (`by_day`). +- **Reactivación de Bedelía en Producción**: Activada la cuenta `bedelia@edu-space.com` para trabajo operativo institucional continuo. + +- **Corrección de Vistas de Bedelía (Reservas de Hoy, Semana, Aulas Libres y Comisiones Sin Aula)**: + - **Causa Raíz de Reservas Vacías**: `sheets_importer.py` generaba reservas únicamente para `weeks_to_generate = 4` a partir del 31 de agosto de 2026 (finalizando el 26 de septiembre). En la fecha actual de octubre de 2026 (`2026-10-07`), la base de datos tenía 0 reservas para el día y la semana. Se amplió a `weeks_to_generate = 16` cubriendo todo el 2° cuatrimestre regular (hasta el 19 de diciembre de 2026), generando **2464 reservas totales**, **34 clases para hoy** y **154 clases para la semana actual**. + - **Fecha Dinámica en Cartelera**: Se corrigió `handleTodaySchedule` en `frontend/src/routes/schedule.js` que tenía hardcodeado `2026-09-18` como fecha por defecto, reemplazándolo por la fecha actual ISO (`new Date().toISOString().split('T')[0]`) y añadiendo navegación interactiva entre días (`prev_date`, `next_date`, y botón "Hoy"). + - **Panel Operativo de Cartelera & Agenda en Dashboard**: Se incorporó en el Dashboard de Bedelía la sección "Cartelera Operativa & Agenda de Clases" con tabs dinámicos para alternar entre "Clases de Hoy" y "Esta Semana", visualizando horario, aula física o sala virtual (con enlace directo a Meet), materia, comisión, turno y docente. + - **Aulas Disponibles por Período**: Se agregó el selector interactivo "Hoy" (con 18 aulas libres detectadas para el día), "Esta Semana" y "Este Mes" en el panel `#bedelia-available-classrooms`, permitiendo asignar aulas libres con un clic. + - **Comisiones Sin Aula Física ni Virtual**: Se agregó el tab "Sin Aula Física ni Virtual (General)" en `#bedelia-unassigned-commissions` para identificar comisiones sin asignación de espacio, y se añadió la columna "Espacio / Aula" con filtro rápido `unassigned_room=true` en `/admin/commissions_list`. +- **Filtrado Temporal de Aulas y Comisiones (Día, Semana y Mes)**: + - **Requerimiento**: Poder filtrar tanto **Aulas Asignadas** vs **Aulas Sin Asignar (Libres)** como **Comisiones Asignadas** vs **Comisiones Sin Asignar** por **Día**, **Semana** y **Mes**, con la opción de **Día por defecto** y aclarando la **fecha explícita** para fácil identificación de todos los usuarios. + - **Backend (`dashboard.py`)**: Se calculan estructuras `filter_stats` para los tres períodos (`today`, `week`, `month`) con métricas precisas (counts, porcentajes) y diccionarios legibles `date_labels` en español ("Hoy · Miércoles 07/10/2026", "Semana del 05/10 al 11/10/2026", "Mes de Octubre 2026"). + - **Frontend BFF & UI (`dashboard.js`, `dashboard.html`)**: + - **Panel de Percentiles**: Switcher interactivo `[ Día (Hoy) ]` (activo por defecto), `[ Semana ]` y `[ Mes ]` con badge explícito de fecha y barras reactivas. + - **Panel de Comisiones**: Switcher `[ Día (Hoy) ]`, `[ Semana ]`, `[ Mes ]` con badge de fecha explícita, más pestañas para conmutar entre "Comisiones Asignadas (Con Aula)" y "Comisiones Sin Asignar (Pendientes)" con acciones directas para asignar espacio. + - **Panel de Aulas**: Switcher `[ Día (Hoy) ]`, `[ Semana ]`, `[ Mes ]` con badge de fecha explícita, más pestañas para conmutar entre "Aulas Sin Asignar (Libres)" y "Aulas Asignadas (En Uso)" con acceso directo a cartelera o asignación inmediata. + - **Validación en Producción**: Desplegado en `https://eduspace.oemspot.com.ar` y verificado con éxito (HTTP 200 en login de Bedelía y renderizado exacto de datos reales). + +- **Evolución del Importador de Google Sheets (Filtros por Carrera, Materia, Día y Fecha Manual)**: + - **Requerimiento**: Permitir filtrar qué Carrera, qué Materia y qué Día importar desde el Google Sheet online de UniCABA, como así también agregar la fecha manualmente para corregir o evitar errores si el Sheet no tiene la fecha o se requiere asignar una clase puntual en el calendario. + - **Backend (`sheets_importer.py` & `dashboard.py`)**: + - Se implementó `inspect_sheet_content()` que descarga e inspecciona las 6 hojas del Sheet online en ~7s, descubriendo de forma dinámica todas las Carreras únicas (18 carreras detectadas) y Materias únicas (206 materias detectadas). + - Se agregaron los parámetros `filter_career`, `filter_subject`, `filter_day`, `manual_date` y `single_date_only` al método `sync(...)`. + - Normalización robusta de días con `normalize_day_name(...)` insensible a acentos y mayúsculas. + - Soporte de coincidencia parcial y sensible a carreras compuestas (ej: `DATOS (CCC)` coincide con asignaturas compartidas con `TEC. DIG.` y `VIDEOJUEGOS`). + - Soporte de asignación de fecha puntual manual (`single_date_only=True`), creando 1 única reserva para esa fecha exacta en vez de las 16 semanas regulares, o tomando la fecha manual como base del cuatrimestre. + - Nuevo endpoint REST `GET/POST /api/v1/dashboard/sheets-inspect` y actualización de `/api/v1/dashboard/sync-sheets`. + - **Frontend BFF & UI (`admin.js` & `import.html`)**: + - Panel interactivo "Sincronización Académica con Filtros Avanzados y Control de Fecha". + - Selectores dinámicos de Día (Todos, Lunes, Martes, etc.), inputs con autocompletado `` para Carreras y Materias. + - Selector interactivo de Fecha Manual (`type="date"`) con switch toggle para "Importar ÚNICAMENTE para esta fecha puntual". + - Botón "Inspeccionar Sheet Online" con llamada AJAX a `/admin/sheets_inspect` que carga en vivo las carreras y materias descubiertas. + - Tarjeta de informe detallado post-sincronización con badges temáticos de "Filtros Activos", número de "Filas Coincidentes" vs totales, y modo de generación. + - **Validación en Producción**: + - Pruebas automatizadas de backend: 49 tests aprobados en pytest (100% passed). + - Desplegado en producción institucional (`https://eduspace.oemspot.com.ar`). + - Verificación online con `bedelia@edu-space.com`: HTTP 200 en `/admin/google_sheets_import`, endpoint `/admin/sheets_inspect` retornando 239 filas y 18 carreras, y sincronización filtrada con éxito (ej. Martes + DATOS procesando exactamente sus 3 filas coincidentes). + +- **Sprint v3.4.1: Corrección de Bug en Import Sheet, Aulas Virtuales en Bedelía, Modularización de Vistas y Reglas de Workflow**: + - **Fix Bug Google Sheets Import (`Error loading Google Sheets sync view`)**: + - **Causa Raíz**: `availableCareers` y `availableSubjects` se declaraban únicamente dentro de un bloque condicional en `admin.js`, provocando `ReferenceError: availableCareers is not defined` en peticiones GET normales. + - **Solución**: Se declararon e inicializaron a nivel de función `handleGoogleSheetsImport` tanto en la consulta inicial de `Promise.allSettled` como en el refresh posterior a la sincronización. + - **Fix Bug Aulas Virtuales en Dashboard de Bedelía**: + - **Causa Raíz**: El conteo `virtual_classrooms` en `dashboard.py` calculaba `len(virtual_classrooms_list)` sobre la tabla relacional `classrooms`, que solo contiene 1 registro genérico (`id: 331, code: 'VIRTUAL', building: 'Campus Virtual'`). + - **Solución**: Se actualizó la lógica para calcular las salas virtuales a partir de las comisiones activas con modalidad virtual (Google Meet/Teams/Zoom) o reservas en Campus Virtual, reportando las 101 salas virtuales activas. Se incorporó el arreglo `virtual_rooms` en `role_data` de Bedelía y se agregó la pestaña *"Salas Virtuales (Campus Virtual)"* con 127 enlaces a Google Meet en el panel de Aulas (`dashbede.html`). + - **Modularización de la Arquitectura de Vistas (`dashboard.html` como Layout Padre)**: + - Se dividió el archivo monolítico `dashboard.html` de más de 2300 líneas en 4 componentes/subvistas según el rol del usuario: + - `dashadm.html` (Administrador) + - `dashbede.html` (Bedelía) + - `dashprof.html` (Docente / Profesor) + - `dashalum.html` (Alumno / Estudiante) + - `dashboard.html` actúa ahora como layout/plantilla padre limpia que inyecta la subvista correspondiente mediante `{% include %}` de Nunjucks. + - **Actualización de Reglas en `docs/constitution.md` (Principio 9)**: + - Se agregó el Principio 9 innegociable: + 1) Siempre actualizar y guardar el control de la nueva versión semántica al momento de compilar. + 2) Al finalizar la compilación, siempre subir y desplegar la nueva versión al servidor institucional de producción. + - **Despliegue y Verificación en Producción**: + - Versionado elevado a `v3.4.1`. + - Desplegado exitosamente en el servidor LXC `10.0.0.217` (`https://eduspace.oemspot.com.ar`). + - Verificación HTTP 200 en `/version`, login admin, `/admin/google_sheets_import`, dashboards modularizados de los 4 roles y cuenta institucional de Bedelía. +- **Sprint UX/UI: Agrupación Cronológica de Reservas y Formato Limpio de Fechas (v3.4.2)**: + - **Problema 1: Duplicación de Reservas por Hora en Cartelera**: + - En `/schedule/today_schedule`, un bucle fijo `for (let hour = 7; hour <= 21; hour++)` insertaba la misma reserva en cada bloque horario de 1 hora que abarcaba la materia (ej. Marketing Digital de 08:00 a 11:00 hs aparecía repetida a las 8, 9 y 10). + - **Solución**: Se eliminó la clonación artificial y se introdujo la agrupación nativa por franja horaria real de cursada (`grouped_slots`, ej. `08:00 - 11:00 hs`, `18:30 - 21:00 hs`). Cada reserva aparece agrupada exactamente UNA SOLA VEZ en su bloque horario correspondiente con turno, duración, aula, cupo y enlace a Meet/Zoom. + - **Problema 2: Formato ISO Crudo en Listado de Reservas**: + - En `/schedule/list_reservations` (tabla y tarjetas) se mostraban strings crudos con 'T' y segundos (`2026-10-08T08:00:00 - 2026-10-08T11:00:00 hs`). + - **Solución**: Se enriquecieron todas las reservas con la función `formatReservationDates` y nuevos filtros Nunjucks (`format_date_human`, `format_time`, `format_time_range`), mostrando fecha limpia (`Jueves 08/10/2026` / `08/10/2026`) y horario amigable (`08:00 - 11:00 hs`). + - **Bump Semántico y Despliegue Obligatorio (Principio 9)**: + - Versión incrementada a `v3.4.2` en Frontend y Backend. + - Despliegue inmediato al servidor institucional `10.0.0.217` y verificación en caliente. +- **Sprint Importador Google Sheets: Selección Granular y Grilla Interactiva (v3.4.3)**: + - **Selección Granular de Entidades (Tarjetas Checkbox)**: + - Réplica del diseño visual de la Herramienta de Purga con botones "Marcar Todo" y "Desmarcar Todo". + - Toggles individuales para Asignaciones de aulas (`import_reservations`), Aulas físicas y virtuales (`import_classrooms`), Comisiones (`import_commissions`), Asignaturas (`import_subjects`) y Carreras (`import_careers`). + - **Selector de Días de la Semana con Checkboxes Múltiples**: + - Reemplazo del selector simple por checkboxes individuales para Lunes a Sábado con accesos rápidos ("Todos", "Lun a Vie", "Limpiar"). + - **Grilla de Previsualización Interactiva e Inspección Previa**: + - El botón "Inspeccionar Sheet Online" no importa directamente; extrae y presenta una grilla interactiva completa (`preview_rows`) de registros online. + - Selección individual por fila y checkbox maestro superior. + - Modificación manual inline de fechas de cursada por fila mediante Datepicker (``) y aplicador de fecha masiva a seleccionados. + - Resaltado visual con badges de alerta y error ante registros incompletos o aulas no reconocidas. + - Buscador en vivo multi-criterio y paginación fluida (25 filas por página) para evitar bloqueos del navegador. + - Modal de confirmación previa con desglose exacto de filas y entidades antes de iniciar la sincronización. + - **Backend y BFF REST**: + - `sheets_importer.py` ampliado para retornar `preview_rows` y procesar `selected_rows` con granularidad de entidades. + - Endpoints `POST /api/v1/dashboard/sheets-inspect` y `POST /api/v1/dashboard/sync-sheets`. + - **Bump Semántico y Despliegue Obligatorio (Principio 9)**: + - Versión incrementada a `v3.4.3` en Frontend y Backend. + - Despliegue y verificación en caliente en el servidor institucional `10.0.0.217` (`https://eduspace.oemspot.com.ar`). + +- **Sprint Dashboard Bedelía: Filtro Temporal "Mañana" en Switchers y Cartelera (v3.4.4)**: + - **Requerimiento**: Agregar "Mañana" en el filtro actual del dashboard que decía "Día (Hoy) / Semana / Mes". + - **Implementación**: + - **Backend API (`backend/app/routes/api/dashboard.py`)**: Cálculo de `tomorrow_dt` (00:00:00 a 23:59:59), agregando estadísticas en `filter_stats['tomorrow']` para percentiles de aulas físicas y comisiones asignadas/sin asignar, y `tomorrow_schedule_list` para la agenda de clases. + - **Frontend BFF & Vistas (`frontend/views/dashboard/dashbede.html`, `dashbede.html`, `dashadm.html`, `dashboard.html`)**: + - Switcher de percentiles: botón "Mañana" con actualización dinámica de percentiles de ocupación de aulas físicas. + - Switcher de comisiones: botón "Mañana" y bloques `#commBlock-tomorrow-unassigned` y `#commBlock-tomorrow-assigned`. + - Switcher de aulas físicas: botón "Mañana" y bloques `#classBlock-tomorrow-unassigned` (aulas libres con botón "Asignar") y `#classBlock-tomorrow-assigned` (aulas en uso). + - Cartelera Operativa & Agenda de Clases: botón "Clases de Mañana" y tabla `#bedeliaScheduleTomorrow` mostrando asignaturas, comisiones, docentes y enlaces para mañana. + - **Bump Semántico y Despliegue Obligatorio (Principio 9)**: + - Versión incrementada a `v3.4.4` en Frontend y Backend. + - Despliegue al servidor institucional `10.0.0.217` (`https://eduspace.oemspot.com.ar`) y verificación en caliente. + +- **Sprint Optimizador de Aulas IA: Corrección de Permisos y Carga de Comisiones (v3.4.5)**: + - **Problema Reportado**: AI Room Reservation Optimizer no mostraba comisiones y los indicadores de Available Classrooms, Active Commissions y Existing Reservations quedaban en `--`. + - **Causa Raíz Identificada**: + - En `backend/app/routes/genetic_algorithm.py` las rutas `@genetic_bp.route('/commissions')`, `/algorithm-status`, `/preview-optimization`, `/optimize` y `/apply-optimization` exigían de forma estricta `g.jwt_user.role in ['ADMIN', 'teacher']` o `g.jwt_user.role in ['ADMIN']`. + - Al ingresar como Bedelía (`role == 'Bedelia'`), Docentes o Administradores con rol en minúsculas, el backend devolvía `403 Forbidden`, bloqueando la llamada AJAX y dejando la interfaz vacía con `--`. + - En el Frontend BFF, la ruta `/genetic_optimizer` no requería `requireAuth` ni pasaba datos de sesión de usuario a la plantilla. + - **Solución Implementada**: + - Creación del helper `check_optimizer_permission(user, requires_write)` en `backend/app/routes/genetic_algorithm.py` habilitando acceso a `admin`, `administrador`, `bedelia`, `docente`/`teacher` y permisos RBAC en 'optimizer'. + - `GET /api/genetic/commissions` ahora enriquece los objetos con `subject_name`, `subject_code`, `career_name`, `schedule` y `shift`. + - `frontend/views/genetic_optimizer.html`: Traducido íntegramente a español institucional ("Optimizador Inteligente de Asignación de Aulas (IA)"), tarjetas de comisiones con badges, buscador en vivo multi-criterio y manejo de errores visual. + - `frontend/public/js/genetic-algorithm.js`: Traducción de alertas, modales y tablas de resultados. + - `frontend/src/app.js`: Protección con `requireAuth` e inyección de sesión a la vista. + - **Bump Semántico y Despliegue Obligatorio (Principio 9)**: + - Versión incrementada a `v3.4.5` en Frontend y Backend. + - Despliegue inmediato al servidor institucional `10.0.0.217` y verificación en caliente HTTP 200. + +- **Sprint v3.4.6: Corrección Integral de Reservas, Pisos Dinámicos, Fechas Humanas y Filtro de Carreras**: + - **Incidencias Resueltas**: + 1. `/schedule/add_reservation` y `/schedule/edit`: Corregido error de serialización JSON que rompía el selector en cascada Edificio -> Piso -> Aula al seleccionar "Edificio Central". Inyección segura sin entities y matching resiliente de pisos físicos y virtuales. + 2. `/schedule/calendar_view`: Limpieza de datos hardcodeados/mockeados (`Arquitectura de Software ARQ-101`, `COM-A`, `Licenciatura en Sistemas`). El feed y filtros ahora consumen asignaturas, carreras y comisiones reales de la BD. + 3. `sheets_importer.py`: Eliminada la autogeneración no deseada de enlaces de Google Meet / Zoom (`meet.google.com/edu-...`) en reservas importadas cuando la celda original está vacía (ej. `#9797 ASIG00215 - Marketing Digital`). + 4. `/classrooms/view_classroom`: Formateadas fechas y horarios a español legible (ej. `Viernes 04/09/2026 · 18:30 a 21:30 hs`) eliminando formato ISO repetido y ampliando rango a todo el semestre 2026. + 5. `/buildings/list_buildings` y `/buildings/view/:id`: Corregida la ficha de edificio que mostraba "No hay aulas asignadas a este edificio" a pesar de tener 6 aulas físicas asociadas (`floors_list` y `classrooms_by_floor`), corregido el contador de "Pisos Presenciales" (4 pisos) y soporte completo de niveles dinámicos alfanuméricos (PB, EP, Subsuelo, etc.). + 6. `/admin/commissions_list`: Corregido `UnboundLocalError` en `backend/app/routes/api/admin.py` por importación interna tardía de `Career`, que arrojaba HTTP 500 al filtrar por `career_id=180, 181, 182`. +- **Sprint v3.4.8: Registro de Auditoría Institucional y Trazabilidad Operativa**: + - **Incidencias y Mejoras**: + 1. `/api/v1/admin/audit-logs`: Implementación del endpoint RESTful con paginación, filtros por módulo (`auth`, `reservations`, `classrooms`, `buildings`, `optimizer`, `admin`, etc.), acción (`LOGIN`, `LOGIN_FAILED`, `CREATE`, `UPDATE`, `DELETE`, `CONFIRM`, etc.) y búsqueda multi-campo. + 2. Modelo `AuditLog`: Agregado método `to_dict()` para serialización JSON segura e ISO. + 3. `AuditService`: Soporte de parámetros explícitos `user_id` y `user_email` para registrar eventos cuando el usuario no está autenticado o el intento de acceso falla. + 4. `/api/v1/auth/`: Instrumentada la captura de inicios de sesión (`LOGIN`), Google OAuth (`LOGIN_GOOGLE`), Moodle delegado (`LOGIN_MOODLE`), fallos de inicio de sesión (`LOGIN_FAILED`), accesos bloqueados (`LOGIN_BLOCKED`), cierres de sesión (`LOGOUT`) y cambios de contraseña institucional (`PASSWORD_CHANGE`). + 5. `/api/v1/reservations`: Auditoría de creación (`CREATE`), edición (`UPDATE`), cancelación (`CANCEL`), borrado permanente (`DELETE`) y confirmación oficial (`CONFIRM`). + 6. `/api/v1/classrooms` y `/api/v1/buildings`: Auditoría de altas, modificaciones, alternancia de estado activo/inactivo (`TOGGLE`) y bajas. + 7. Optimizador Genético IA: Auditoría de ejecuciones (`OPTIMIZE_RUN`) y aplicación de asignaciones masivas en base de datos (`OPTIMIZE_APPLY`). + 8. Frontend BFF (`/admin/audit_logs`): Conexión del BFF con la REST API, badges temáticos e intuitivos, filtros rápidos por categorías, visor modal para detalles extensos o JSON, y paginador dinámico nativo que preserva parámetros de consulta. + - **Bump Semántico y Despliegue Obligatorio (Principio 9)**: + - Versión incrementada a `v3.4.8` en Frontend y Backend. + +- **Sprint v3.4.9: Solución de Límite de Payload en Importador de Sheets & Diagnóstico Transparente de Incidentes**: + - **Incidencias y Mejoras**: + 1. `frontend/src/app.js`: Elevado límite de `express.json` y `express.urlencoded` de 100 KB por defecto a 50 MB (`{ limit: '50mb' }`), resolviendo el error `PayloadTooLargeError: request entity too large: expected 154166, length 154166, limit 102400` que provocaba HTTP 500 al enviar la matriz de filas preseleccionadas en `/admin/google_sheets_import`. + 2. Manejo de Incidentes y Diagnóstico Transparente: Reemplazo total de la pantalla genérica de error por una interfaz estructurada con código de ticket único (`INC-YYYYMMDD-XXXX`), diagnóstico descriptivo clasificado, sección técnica de diagnóstico colapsable (Ruta, Timestamp, Usuario actuante, IP, Stack trace), botón para copiar reporte a soporte IT y enlace directo a la Auditoría Institucional. + 3. `backend/app/routes/api/admin.py`: Nuevo endpoint `/api/v1/admin/log-error` para registrar incidentes técnicos no controlados del frontend directamente en `AuditLog` (`action='SYSTEM_ERROR'`, `module='system'`). + 4. `backend/app/routes/api/dashboard.py`: Instrumentada auditoría completa en `sync_google_sheets` para registrar tanto importaciones exitosas (`SHEETS_IMPORT`) como fallos (`SHEETS_IMPORT_ERROR`) con desglose de estadísticas y excepciones. +- **Sprint v3.5.0: Cierre Formal del MVP de Bedelía & Adopción del Arnés SDD / IA**: + - **Metodología y Arnés de Ingeniería con IA (Apuntes Día 1, 2 y 3)**: + 1. Creación de la Skill de SDD (`.agents/skills/sdd/SKILL.md`) con las plantillas de `spec.md`, `plan.md`, `tasks.md` y sintaxis formal **EARS** en español. + 2. Creación de comandos reutilizables de agentes en `.opencode/commands/` (`sdd-spec`, `sdd-plan`, `sdd-tasks`). + 3. Definición de roles de subagentes en `.opencode/agents/`: Coordinator, Planner, Implementer, Reviewer (QA). + 4. Integración del arnés en `AGENTS.md`. + - **Diagnóstico y Cierre de Brecha del MVP**: + - Se identificó la causa raíz de la percepción de "estar lejos": el *Scope Creep* sin especificación formal de cierre y la falta de exportación/impresión de carteleras que forzaba a Bedelía a recurrir al Excel para imprimir o compartir partes con portería y docentes. + - Se formalizó la primera especificación oficial del proyecto en `specs/001-cierre-mvp-bedelia/` (`spec.md`, `plan.md`, `tasks.md`), delimitando de forma estricta los Requisitos Funcionales en **EARS** y estableciendo un perímetro cerrado de **Fuera de Alcance**. + - **Implementación Técnica**: + 1. `frontend/src/routes/schedule.js`: Endpoint `/schedule/export_csv` con codificación UTF-8 BOM (`\uFEFF`) y delimitadores `;` para apertura nativa e inmediata en Microsoft Excel en español. + 2. `frontend/views/schedule/today.html`: Botones directos `[ Excel / CSV ]` e `[ Imprimir ]`, acompañados de estilos CSS `@media print` que formatean la grilla de asignaciones en hoja A4 limpia con membrete institucional oficial de UniCABA. + 3. `frontend/views/dashboard/dashbede.html`: Accesos rápidos en el Launchpad operativo de Bedelía para descargar la planilla del día e imprimir en 1 clic. + - **Calidad y Bump Semántico (Principio 9)**: + - 52 pruebas de backend ejecutadas con 100% de éxito en pytest (`52 passed`). + - Versión incrementada a `v3.5.0` en `package.json`, `app.js`, `__init__.py`, `setup.py` y `openapi.py`. + +- **Sprint v3.5.1: Exportación y Replicación Moodle Producción a Local con Usuarios y Emails Reales**: + - **Especificación SDD (`specs/002-moodle-export-sync/`)**: Creados `spec.md` (6 RF en EARS), `plan.md` y `tasks.md` (todas las tareas completadas). + - **Extracción Híbrida y Concurrente con Emails Reales**: + - `scripts/moodle_replicator.py` se autentica en `https://campus.udelaciudad.edu.ar/` con `logintoken` dinámico. + - Obtiene la nómina masiva estructurada vía `/user/action_redir.php` (`download_participants&dataformat=json`). + - Consulta de forma concurrente (ThreadPool con 10 workers) los perfiles de los usuarios (`user/view.php`) extrayendo sus correos personales y reales (`@gmail.com`, `@hotmail.com`, etc.), eliminando cualquier generación de emails inventados. + - Normalización fonética/ortográfica sin acentos (`normalize_name`) para vincular con 100% de precisión docentes y estudiantes entre HTML y JSON. + - **Reglas de Acceso y DNI Determinístico**: + - DNI de 8 dígitos determinístico derivado del ID de Moodle (`90{moodle_id:06d}`), asignado idénticamente como `username` y `password` para pruebas locales. + - Preservado el DNI y correo real de Carlos Tello (`34247025`, `carlostellocba@gmail.com`). + - **Carga en Moodle Local (`10.0.0.207`)**: + - Creación y actualización de usuarios mediante Moodle REST API (`core_user_create_users`, `core_user_update_users`). + - 504 matriculaciones completadas exitosamente en los 4 cursos oficiales: + * Carrera Lic. en Tecnologías Digitales (CCC): ID Prod 922 -> ID Local 19 (194 alumnos). + * ASIG00124 - Sistemas Digitales_2/2026: ID Prod 5311 -> ID Local 16 (131 alumnos y 2 profesores). + * ASIG00126 - Seguridad de la Información_2/2026: ID Prod 5313 -> ID Local 17 (138 alumnos y 2 profesores). + * ASIG00127 - Programación de Vanguardia - E1_2/2026: ID Prod 5314 -> ID Local 18 (41 alumnos y 2 profesores). + - Desactivada la política restrictiva de contraseñas (`passwordpolicy=0`) en el entorno de pruebas local para permitir contraseñas numéricas idénticas al DNI. + - Verificación exitosa de login de estudiante en `http://10.0.0.207/moodle/login/index.php`. + - **Skill de Automatización**: Creada `.agents/skills/moodle-replicator/SKILL.md` con manual operativo y comandos CLI. + +- **Sprint v3.5.2: Replicación Completa de 16 Cursos, User-Agent Mozilla/5.0 y Fix de Credenciales**: + - **Catálogo Completo de la Carrera (16 Cursos)**: + - Se identificaron y replicaron la totalidad de las 15 materias de la Licenciatura en Tecnologías Digitales (1/2025, 2/2025, 1/2026 y 2/2026) más el curso de la carrera (Local 19). + - Resuelto el caso de alumnos como `90010202` (Carlos Guillermo Terzano): ahora cuenta con sus 6 materias reales cursadas (Local 4, 5, 8, 9, 10, 11) además de la carrera. + - Carlos Tello (`34247025`) matriculado en las 15 asignaturas y la carrera. + - Más de 1.100 matriculaciones procesadas y validadas con 100% de éxito. + - **Identificación y Asignación de Todos los Docentes**: + - Extraídos y asignados todos los profesores reales con rol `editingteacher` (ID 3) y correos institucionales `@udelaciudad.edu.ar`. + - **Cabecera HTTP y User-Agent**: + - Forzado estrictamente el encabezado `User-Agent: Mozilla/5.0 (Windows NT 10.0; Win64; x64)` en todas las solicitudes al campus para evitar alertas por `python-requests`. + - **Sincronización de Contraseña Local (Fix 34247025)**: + - Se corrigió la contraseña del usuario `34247025` restableciéndola a `34247025` idéntica al DNI en Moodle local. Verificado inicio de sesión exitoso. + +- **Sprint v3.5.3: Importación de Roles Moodle-App, Limpieza Total de Admin y Purga de Cursos**: + - **Sincronización RBAC de Roles Moodle a PostgreSQL de la App (`classrooms_db`)**: + - Desarrollado `scripts/import_moodle_to_app.py` y bandera `--sync-app` en `moodle_replicator.py`. + - Mapeo unívoco: Moodle `editingteacher` -> App `Docente` (`role_id=2`), Moodle `student` -> App `Alumno` (`role_id=6`). + - Importados **653 usuarios únicos** (15 Docentes y 640 Alumnos) a la base de datos de producción con contraseñas PBKDF2 coincidentes con el DNI, habilitando de inmediato la asignación de comisiones, reservas e inscripciones. + - **Desmatriculación de Cuenta Admin en Moodle Local (`10.0.0.207`)**: + - Removidas todas las matriculaciones de `admin` en cursos académicos y generales (quedando con 0 enrolments). + - **Sprint v3.5.4: Conexión Moodle API, Login Delegado y Sincronización Moodle -> Edu Space**: + - **Habilitación de Web Services para Tokens de Usuario en Moodle Local (`10.0.0.207`)**: + - Asignada la capability `moodle/webservice:createtoken` al rol 7 (`user` / usuario autenticado) en `mdl_role_capabilities`. + - Habilitado `enablemobilewebservice = 1` y servicio `moodle_mobile_app` (`enabled = 1`). + - Verificada la emisión de tokens exitosa para usuarios individuales (incluyendo `34247025`) tanto contra `moodle_api` como contra `moodle_mobile_app`. + - **Conexión de Admin Edu Space con Moodle Local**: + - Configurado el token `810428346d3601c68a37a315fcba8d4391629f46` de `moodle_api` en `system_settings` de `classrooms_db`. + - Habilitada `auth_moodle_enabled = 'true'` y `moodle_server_url = 'http://10.0.0.207/moodle'`. + - Adaptado el endpoint de autenticación `/api/v1/auth/moodle` para autenticar con `moodle_api` (con fallback a `moodle_mobile_app`) y hacer matching de cuenta local por número de documento (DNI). + - **Sincronización Bidireccional Moodle -> Edu Space**: + - Agregado el endpoint administrativo `POST /api/v1/admin/moodle/sync-from-moodle`. + - Incorporados los métodos `get_courses()`, `get_categories()` y `sync_from_moodle_to_app()` en `MoodleClient`. +- **Sprint v3.5.5: Autenticación por API Key para Moodle, Purga de Tareas y Hardening**: + - **Purga de Tareas de Sincronización Residuales**: + - Eliminadas las 6 tareas pendientes residuales de prueba (#1 a #6) en la tabla `moodle_sync_tasks` de `classrooms_db` en `10.0.0.217`, dejando la cola limpia en 0 registros. + - **Ampliación de Funciones Web Services en Moodle Local (`10.0.0.207`)**: + - Asignadas al servicio `moodle_api` las funciones `enrol_manual_unenrol_users`, `core_enrol_unenrol_user_enrolment`, `core_role_assign_roles` y `core_role_unassign_roles`, completando el catálogo a 15 funciones esenciales. + - **Seguridad por Restricción de Red (IP Restriction)**: + - Fijada la restricción de red `iprestriction = '10.0.0.0/24'` en `mdl_external_tokens`, asegurando que solo el tráfico interno institucional pueda utilizar los tokens de Moodle. + - **Autenticación por API Key Institucional en Admin Edu Space**: + - Creado mecanismo para autenticar endpoints de sincronización (`/settings/moodle/sync` y `/moodle/sync-from-moodle`) mediante `X-API-Key` institucional de 64 caracteres hex. + - Generada y almacenada la clave API institucional cifrada con Fernet en `system_settings` (`classrooms_db`). + - Agregados endpoints para consulta y regeneración de clave API (`/api/v1/admin/settings/moodle/api-key`). + +- **Sprint v3.5.6: Principio 10 de Tolerancia Cero a Errores de Código, Robustez en SystemSetting y Replicador**: + - **Principio 10 de la Constitución**: + - Incorporada regla mandatoria en `docs/constitution.md`, `AGENTS.md`, `.agents/skills/sdd/SKILL.md`, `.agents/skills/deploy/SKILL.md` y `.opencode/agents/` (`coordinator.md`, `implementer.md`, `reviewer.md`). + - Es estrictamente inadmisible declarar una tarea o sprint como terminado o completado si persisten errores en el código o en el analizador de la IDE (`@[current_problems]`). + - **Reparación de Tipos en Replicador Moodle**: + - Ajustado casteo a entero `int(course_meta['local_id'])` y `int(u.get('role_id', 5))` en `scripts/moodle_replicator.py`. + - **Robustez Híbrida en `SystemSetting`**: + - Implementado descriptor híbrido `_hybrid_setting_method` para `get_decrypted_value` y `get_masked_value`, permitiendo indistintamente la invocación como método de clase o de instancia sin errores de argumentos. + - **Resolución de Condición de Carrera en Tests de SQLite**: + - Añadida espera activa de finalización de workers en `test_05_api_async_job_submission_and_polling` para evitar bloqueos de base de datos en `tearDown()`. + - **Validación Automatizada**: + - 52/52 tests pasando en verde al 100% (`pytest tests -v`). + +- **Sprint v3.5.7: Principio 11 de la Constitución — Estándares Modernos de APIs (FastAPI/Pydantic) e Integración con Modelos de IA (LLMs)**: + - **Arquitectura Modular en 4 Capas**: + - Desacople estricto: `main.py` (bootstrap/registro), `routers/` (endpoints agrupados por dominio con prefijos y tags para Swagger), `schemas/` (contratos con Pydantic `BaseModel`), `storage.py` (acceso a persistencia). Prohibida la lógica de negocio en el frontend o en archivos monolíticos. + - **Tipado Fuerte y Validación Pydantic**: + - Uso obligatorio de `Field` para validaciones declarativas (`min_length`, `max_length`, `gt`, `ge`, regex). + - Distinción estricta de Path Parameters (obligatorios) y Query Parameters (opcionales tipados con defaults). + - Manejo y respuesta automática de error `422 Unprocessable Entity` detallando el campo exacto. + - **Semántica HTTP y Excepciones Controladas**: + - Uso de códigos de estado HTTP semánticos (`201 Created` en POST, `200 OK`, `204 No Content`). + - Prohibido retornar `null` o respuestas vacías ante fallos: levantar `HTTPException` controladas con detalle descriptivo (404, 400, 409). + - **Documentación Interactiva Automática**: + - Contratos OpenAPI expuestos en `/docs` (Swagger UI) con capacidades de prueba en vivo (*Try it out*). + - **Integración Asíncrona con Modelos de IA Locales (LLMs) & Asistente Virtual**: + - **Pestaña en Configuración Global**: Planificada en `ROADMAP.md` y UI administrativa para configurar URL del servidor local (Ollama, llama.cpp), modelo, token y timeout para el futuro asistente virtual de la app. + - **Cliente Asíncrono no Bloqueante**: Uso mandatorio de `httpx.AsyncClient` con `async def` / `await` para inferencias concurrentes sin bloquear el servidor. + - **Timeout Generoso**: Configurar timeout de 600 segundos previendo carga de modelos en VRAM o prompts extensos. + - **Formato Estándar de Roles**: Historial estructurado bajo `role: "system" | "user" | "assistant"` y `content: prompt`. + - **Actualización Documental Completa**: + - Sincronizados `docs/constitution.md` (Principio 11), `AGENTS.md`, `.agents/skills/sdd/SKILL.md`, `.opencode/agents/` (`coordinator.md`, `planner.md`, `implementer.md`, `reviewer.md`), `ROADMAP.md` (Fase 7) y `MEMORY.md`. + +- **Sprint v3.6.0: Migración Completa de Flask API a FastAPI ASGI (Principio 11)**: + - **Reemplazo Arquitectónico**: + - Backend Core migrado a FastAPI con arquitectura de 4 capas: `backend/main.py` (FastAPI bootstrap), `backend/routers/` (APIRouters modulares por dominio), `backend/schemas/` (Pydantic v2 BaseModels con validación declarativa) y `backend/database.py` (persistencia relacional). + - Módulos migrados a FastAPI: `version`, `auth`, `classrooms`, `reservations`, `students`, `dashboard`, `optimizer` y `genetic`. + - Documentación interactiva OpenAPI v3 expuesta nativamente en `/docs` (Swagger UI) y `/redoc`. + - Puente de retrocompatibilidad y cero regresión implementado mediante `a2wsgi` para asegurar interoperabilidad fluida con Gunicorn, Uvicorn y el frontend BFF Express.js. + - **Calidad y Verificación**: + - 57 tests automatizados ejecutados y aprobados al 100% en pytest (`57 passed`). + - Cero errores en linter, tipos y compilación estática (`@[current_problems]`). + - **Despliegue Continuo**: + - Bump semántico a `v3.6.0`. + - Actualización remota y reinicio de servicios en el servidor LXC `10.0.0.217` (`https://eduspace.oemspot.com.ar`). + +## Próximos pasos +1. Monitorear los endpoints ASGI en producción bajo concurrencia operativa. +2. Implementar la pestaña de Asistente IA en la Configuración Global administrativa (`ROADMAP.md` Fase 7). +3. Continuar con el roadmap hacia la Fase 6 de hardening y orquestación de servicios en Docker. \ No newline at end of file diff --git a/backend/app/__init__.py b/backend/app/__init__.py index ff3cc1c..6aa10c5 100644 --- a/backend/app/__init__.py +++ b/backend/app/__init__.py @@ -6,7 +6,7 @@ from flask_babel import Babel, gettext as _ from config.config import Config # Initialize extensions -__version__ = "3.5.7" +__version__ = "3.6.0" db = SQLAlchemy() migrate = Migrate() cors = CORS() diff --git a/backend/app/routes/api/openapi.py b/backend/app/routes/api/openapi.py index 12cd60d..d83a517 100644 --- a/backend/app/routes/api/openapi.py +++ b/backend/app/routes/api/openapi.py @@ -7,7 +7,7 @@ OPENAPI_SPEC = { "info": { "title": "Edu-Space REST API", "description": "Enterprise Academic & Physical Space Management REST API with JWT Authentication and Role-Based Access Control.", - "version": "3.5.7" + "version": "3.6.0" }, "servers": [ { diff --git a/backend/app/services/jwt_service.py b/backend/app/services/jwt_service.py index df84adb..9f41b01 100644 --- a/backend/app/services/jwt_service.py +++ b/backend/app/services/jwt_service.py @@ -25,8 +25,15 @@ class JWTService: @classmethod def _get_secret(cls) -> str: - """Obtiene la clave secreta desde la configuración de Flask.""" - return current_app.config.get('SECRET_KEY', 'default-edu-space-secret-key') + """Obtiene la clave secreta desde la configuración de Flask o Config directo.""" + try: + from flask import current_app + if current_app: + return current_app.config.get('SECRET_KEY', 'default-edu-space-secret-key') + except Exception: + pass + from config.config import Config + return getattr(Config, 'SECRET_KEY', 'default-edu-space-secret-key') @classmethod def create_access_token(cls, user: User, expires_delta: Optional[timedelta] = None) -> str: diff --git a/backend/asgi.py b/backend/asgi.py new file mode 100644 index 0000000..3e98edc --- /dev/null +++ b/backend/asgi.py @@ -0,0 +1,9 @@ +""" +ASGI entrypoint for Admin Edu-Space (FastAPI). +Utilized by systemd / uvicorn / gunicorn -k uvicorn.workers.UvicornWorker in production. +""" +from main import app + +if __name__ == "__main__": + import uvicorn + uvicorn.run("asgi:app", host="0.0.0.0", port=5000) diff --git a/backend/database.py b/backend/database.py new file mode 100644 index 0000000..b9d18b9 --- /dev/null +++ b/backend/database.py @@ -0,0 +1,21 @@ +""" +Database & Persistence Management for FastAPI (Capa 4) +Integrates SQLAlchemy Engine, SessionLocal and get_db dependency. +""" +from typing import Generator +from sqlalchemy.orm import Session +from app import create_app, db as flask_db + +# Initialize shared application context +flask_app = create_app() + +def get_db() -> Generator[Session, None, None]: + """ + FastAPI dependency yielding the SQLAlchemy session within Flask app context + to guarantee all models, ORM queries and services work seamlessly. + """ + with flask_app.app_context(): + yield flask_db.session + +def get_flask_app(): + return flask_app diff --git a/backend/dependencies.py b/backend/dependencies.py new file mode 100644 index 0000000..850aa24 --- /dev/null +++ b/backend/dependencies.py @@ -0,0 +1,119 @@ +""" +FastAPI Security & Authentication Dependencies +Handles JWT extraction from HttpOnly cookies and Bearer headers, +and implements declarative RBAC validation with app context. +""" +from typing import Optional, List, Callable +from fastapi import Request, HTTPException, Depends, status +import jwt + +from app.models.user import User +from app.services.jwt_service import JWTService +from database import get_flask_app + +flask_app = get_flask_app() + + +def get_token_from_request(request: Request) -> Optional[str]: + """Extrae el token JWT desde cookies HttpOnly o cabecera Authorization Bearer.""" + token = request.cookies.get('access_token') + if token: + return token + + auth_header = request.headers.get('Authorization') + if auth_header and auth_header.startswith('Bearer '): + return auth_header.split(' ', 1)[1].strip() + + return None + + +def get_current_user(request: Request) -> User: + """ + Dependencia FastAPI que resuelve y autentica al usuario actual. + Lanza HTTP 401 si no hay token, si es inválido o si el usuario no existe. + """ + token = get_token_from_request(request) + if not token: + raise HTTPException( + status_code=status.HTTP_401_UNAUTHORIZED, + detail="No se proporcionó token de autenticación." + ) + + try: + payload = JWTService.decode_token(token, expected_type='access') + except jwt.ExpiredSignatureError: + raise HTTPException( + status_code=status.HTTP_401_UNAUTHORIZED, + detail="El token de acceso ha expirado." + ) + except jwt.PyJWTError as e: + raise HTTPException( + status_code=status.HTTP_401_UNAUTHORIZED, + detail=f"Token inválido: {str(e)}" + ) + + user_id = payload.get('sub') + if not user_id: + raise HTTPException( + status_code=status.HTTP_401_UNAUTHORIZED, + detail="Token no contiene identificador de usuario válido." + ) + + with flask_app.app_context(): + from sqlalchemy.orm import joinedload + try: + user = User.query.options(joinedload(User.role_obj)).get(int(user_id)) + except Exception as e: + raise HTTPException( + status_code=status.HTTP_500_INTERNAL_SERVER_ERROR, + detail=f"Error consultando usuario: {str(e)}" + ) + + if not user or not user.is_active: + raise HTTPException( + status_code=status.HTTP_401_UNAUTHORIZED, + detail="Usuario inactivo o no encontrado." + ) + + return user + + +def get_optional_current_user(request: Request) -> Optional[User]: + """Dependencia opcional: retorna el usuario autenticado o None si es anónimo.""" + token = get_token_from_request(request) + if not token: + return None + try: + payload = JWTService.decode_token(token, expected_type='access') + user_id = payload.get('sub') + if user_id: + with flask_app.app_context(): + return User.query.get(int(user_id)) + except Exception: + pass + return None + + +def require_roles(allowed_roles: List[str]) -> Callable: + """ + Factory de dependencias para control de acceso basado en roles (RBAC). + Normaliza comparaciones en minúsculas y reconoce equivalencias (ADMIN, Bedelia, etc.). + """ + normalized_allowed = [r.lower() for r in allowed_roles] + + def role_dependency(user: User = Depends(get_current_user)) -> User: + user_role = (user.role or '').lower() + is_admin = getattr(user, 'is_admin', lambda: False)() or user_role in ['admin', 'administrador'] + + if is_admin and ('admin' in normalized_allowed or 'administrador' in normalized_allowed): + return user + + if user_role in normalized_allowed: + return user + + raise HTTPException( + status_code=status.HTTP_403_FORBIDDEN, + detail=f"Acceso denegado. Se requiere uno de los siguientes roles: {', '.join(allowed_roles)}." + ) + + return role_dependency diff --git a/backend/main.py b/backend/main.py new file mode 100644 index 0000000..d26a4c3 --- /dev/null +++ b/backend/main.py @@ -0,0 +1,59 @@ +""" +Admin Edu-Space - FastAPI Core Application (Principio 11) +High-performance ASGI server with modular routers, Pydantic schemas, +OpenAPI /docs documentation and zero-regression WSGI bridge. +""" +from fastapi import FastAPI, Request, status +from fastapi.middleware.cors import CORSMiddleware +from fastapi.responses import JSONResponse +from a2wsgi import WSGIMiddleware + +from app import __version__ +from database import get_flask_app + +# Import modular FastAPI routers +from routers.version import version_router +from routers.auth import auth_router +from routers.classrooms import classrooms_router +from routers.reservations import reservations_router +from routers.students import students_router +from routers.dashboard import dashboard_router +from routers.optimizer import optimizer_router, genetic_router + +# Initialize FastAPI Application +app = FastAPI( + title="Admin Edu-Space REST API", + description="Plataforma de gestión de espacios áulicos, sincronización académica y optimización inteligente.", + version=__version__, + docs_url="/docs", + redoc_url="/redoc", + openapi_url="/openapi.json" +) + +# CORS Middleware configuration +app.add_middleware( + CORSMiddleware, + allow_origins=["*"], + allow_credentials=True, + allow_methods=["*"], + allow_headers=["*"], +) + +# Register high-performance FastAPI Routers +app.include_router(version_router) +app.include_router(auth_router) +app.include_router(classrooms_router) +app.include_router(reservations_router) +app.include_router(students_router) +app.include_router(dashboard_router) +app.include_router(optimizer_router) +app.include_router(genetic_router) + +# Mount zero-regression WSGI bridge for remaining legacy routes and admin modules +flask_app = get_flask_app() +app.mount("/", WSGIMiddleware(flask_app)) + + +if __name__ == "__main__": + import uvicorn + uvicorn.run("main:app", host="0.0.0.0", port=5000, reload=True) diff --git a/backend/requirements.txt b/backend/requirements.txt index 66a9ed9..8a06c0b 100644 --- a/backend/requirements.txt +++ b/backend/requirements.txt @@ -20,3 +20,7 @@ gunicorn>=21.2.0 PyJWT>=2.8.0 pydantic>=2.0.0 cryptography>=42.0.0 +fastapi>=0.115.0 +uvicorn[standard]>=0.30.0 +httpx>=0.27.0 +a2wsgi>=1.10.0 diff --git a/backend/routers/__init__.py b/backend/routers/__init__.py new file mode 100644 index 0000000..a6e4c3b --- /dev/null +++ b/backend/routers/__init__.py @@ -0,0 +1 @@ +# Routers package initialization diff --git a/backend/routers/auth.py b/backend/routers/auth.py new file mode 100644 index 0000000..0d71fa1 --- /dev/null +++ b/backend/routers/auth.py @@ -0,0 +1,243 @@ +""" +FastAPI Authentication Router (/api/v1/auth) +Implements Hybrid Authentication: +- Local Authentication with Admin fallback +- Google OAuth 2.0 institutional login +- Moodle Delegated Authentication +- Impersonation mode for Administrators +- Dual Token JWT management with HttpOnly cookies +""" +from typing import Optional +from fastapi import APIRouter, Depends, HTTPException, Request, Response, status +from pydantic import ValidationError + +from app.models.user import User +from app.models.setting import SystemSetting +from app.services.user_service import UserService +from app.services.jwt_service import JWTService +from app.services.moodle_client import moodle_client +from app.services.audit_service import AuditService +from dependencies import get_current_user, require_roles, get_token_from_request +from database import get_flask_app +from schemas.auth import ( + LoginRequest, + GoogleAuthRequest, + MoodleAuthRequest, + ImpersonateRequest, + RefreshTokenRequest +) + +auth_router = APIRouter(prefix="/api/v1/auth", tags=["Authentication"]) +user_service = UserService() +flask_app = get_flask_app() + + +@auth_router.get("/providers") +def get_auth_providers(): + """Retorna los métodos de autenticación habilitados y configuración de cliente Google.""" + with flask_app.app_context(): + local_val = str(SystemSetting.get_value('auth_local_enabled', 'true') or 'true').lower() in ('true', '1') + google_val = str(SystemSetting.get_value('auth_google_enabled', 'false') or 'false').lower() in ('true', '1') + moodle_val = str(SystemSetting.get_value('auth_moodle_enabled', 'false') or 'false').lower() in ('true', '1') + google_client_id = str(SystemSetting.get_value('google_client_id', '') or '') + demo_access_enabled = str(SystemSetting.get_value('demo_access_enabled', 'true') or 'true').lower() in ('true', '1') + + return { + 'status': 'success', + 'providers': { + 'local': local_val, + 'google': google_val, + 'moodle': moodle_val + }, + 'google_client_id': google_client_id, + 'demo_access_enabled': demo_access_enabled + } + + +@auth_router.post("/login") +def login(payload: LoginRequest, response: Response): + """Inicio de sesión local nativo (Access + Refresh tokens).""" + with flask_app.app_context(): + local_enabled = str(SystemSetting.get_value('auth_local_enabled', 'true') or 'true').lower() in ('true', '1') + + user = user_service.authenticate(payload.email, payload.password) + if not user: + AuditService.log( + action='LOGIN_FAILED', + module='auth', + user_email=payload.email, + details=f"Intento de inicio de sesión fallido para {payload.email}. Credenciales incorrectas o cuenta inactiva." + ) + raise HTTPException( + status_code=status.HTTP_401_UNAUTHORIZED, + detail="Credenciales de acceso incorrectas o cuenta inactiva." + ) + + is_admin = user.is_admin() or getattr(user, 'role', '').upper() == 'ADMIN' + if not local_enabled and not is_admin: + AuditService.log( + action='LOGIN_BLOCKED', + module='auth', + user=user, + entity_id=user.id, + details=f"Acceso local con contraseña bloqueado para {user.email}. Método deshabilitado por administración." + ) + raise HTTPException( + status_code=status.HTTP_403_FORBIDDEN, + detail="El acceso local con contraseña está deshabilitado por el administrador. Inicie sesión mediante Google OAuth o Moodle." + ) + + AuditService.log( + action='LOGIN', + module='auth', + user=user, + entity_id=user.id, + details=f"Inicio de sesión exitoso (Autenticación Local) - Rol: {user.role}" + ) + + tokens = JWTService.generate_tokens(user) + profile = user_service.get_profile_data(user) + + response.set_cookie( + key="access_token", + value=tokens["access_token"], + httponly=True, + samesite="lax", + path="/" + ) + response.set_cookie( + key="refresh_token", + value=tokens["refresh_token"], + httponly=True, + samesite="lax", + max_age=7 * 24 * 3600, + path="/api/v1/auth/refresh" + ) + + return { + 'status': 'success', + 'access_token': tokens['access_token'], + 'refresh_token': tokens['refresh_token'], + 'token_type': tokens['token_type'], + 'expires_in': tokens['expires_in'], + 'user': profile + } + + +@auth_router.post("/google") +def google_auth(payload: GoogleAuthRequest, response: Response): + """Inicio de sesión delegado institucional Google OAuth 2.0.""" + with flask_app.app_context(): + google_enabled = str(SystemSetting.get_value('auth_google_enabled', 'false') or 'false').lower() in ('true', '1') + if not google_enabled: + raise HTTPException(status_code=status.HTTP_403_FORBIDDEN, detail="El inicio de sesión con Google no está habilitado.") + + email = payload.email.strip().lower() + allowed_domains_str = str(SystemSetting.get_value('google_allowed_domains', 'unicaba.edu.ar') or 'unicaba.edu.ar') + allowed_domains = [d.strip().lower() for d in allowed_domains_str.split(',') if d.strip()] + + email_domain = email.split('@')[1] if '@' in email else '' + if allowed_domains and email_domain not in allowed_domains: + raise HTTPException( + status_code=status.HTTP_403_FORBIDDEN, + detail=f"Dominio @{email_domain} no autorizado. Sólo se permiten cuentas institucionales: {allowed_domains_str}." + ) + + user = user_service.get_or_create_google_user( + email=email, + name=payload.name or email.split('@')[0], + photo=payload.photo + ) + + tokens = JWTService.generate_tokens(user) + profile = user_service.get_profile_data(user) + + response.set_cookie(key="access_token", value=tokens["access_token"], httponly=True, samesite="lax", path="/") + return { + 'status': 'success', + 'access_token': tokens['access_token'], + 'refresh_token': tokens['refresh_token'], + 'token_type': tokens['token_type'], + 'expires_in': tokens['expires_in'], + 'user': profile + } + + +@auth_router.post("/moodle") +def moodle_auth(payload: MoodleAuthRequest, response: Response): + """Inicio de sesión delegado con Moodle (verificando DNI o credenciales de campus).""" + with flask_app.app_context(): + moodle_enabled = str(SystemSetting.get_value('auth_moodle_enabled', 'false') or 'false').lower() in ('true', '1') + if not moodle_enabled: + raise HTTPException(status_code=status.HTTP_403_FORBIDDEN, detail="El inicio de sesión con Moodle no está habilitado.") + + user = user_service.authenticate_moodle(payload.username, payload.password) + if not user: + raise HTTPException(status_code=status.HTTP_401_UNAUTHORIZED, detail="Credenciales de Moodle inválidas o usuario no sincronizado.") + + tokens = JWTService.generate_tokens(user) + profile = user_service.get_profile_data(user) + + response.set_cookie(key="access_token", value=tokens["access_token"], httponly=True, samesite="lax", path="/") + return { + 'status': 'success', + 'access_token': tokens['access_token'], + 'refresh_token': tokens['refresh_token'], + 'token_type': tokens['token_type'], + 'expires_in': tokens['expires_in'], + 'user': profile + } + + +@auth_router.get("/me") +def get_current_user_profile(user: User = Depends(get_current_user)): + """Retorna la ficha del perfil del usuario actualmente autenticado.""" + with flask_app.app_context(): + profile = user_service.get_profile_data(user) + return { + 'status': 'success', + 'user': profile + } + + +@auth_router.post("/logout") +def logout(request: Request, response: Response): + """Cierra la sesión y revoca los tokens activos.""" + token = get_token_from_request(request) + if token: + try: + JWTService.revoke_token(token) + except Exception: + pass + + response.delete_cookie(key="access_token", path="/") + response.delete_cookie(key="refresh_token", path="/api/v1/auth/refresh") + return {'status': 'success', 'message': 'Sesión cerrada exitosamente.'} + + +@auth_router.post("/refresh") +def refresh_token(request: Request, response: Response, payload: Optional[RefreshTokenRequest] = None): + """Renueva el token de acceso a partir de un refresh token válido.""" + token = (payload and payload.refresh_token) or request.cookies.get('refresh_token') + if not token: + raise HTTPException(status_code=status.HTTP_401_UNAUTHORIZED, detail="No se proporcionó refresh token.") + + with flask_app.app_context(): + try: + decoded = JWTService.decode_token(token, expected_type='refresh') + user_id = decoded.get('sub') + user = User.query.get(int(user_id)) + if not user or not user.is_active: + raise HTTPException(status_code=status.HTTP_401_UNAUTHORIZED, detail="Usuario no encontrado o inactivo.") + + tokens = JWTService.generate_tokens(user) + response.set_cookie(key="access_token", value=tokens["access_token"], httponly=True, samesite="lax", path="/") + return { + 'status': 'success', + 'access_token': tokens['access_token'], + 'refresh_token': tokens['refresh_token'], + 'token_type': tokens['token_type'], + 'expires_in': tokens['expires_in'] + } + except Exception as e: + raise HTTPException(status_code=status.HTTP_401_UNAUTHORIZED, detail=f"Refresh token inválido: {str(e)}") diff --git a/backend/routers/classrooms.py b/backend/routers/classrooms.py new file mode 100644 index 0000000..4ea8253 --- /dev/null +++ b/backend/routers/classrooms.py @@ -0,0 +1,192 @@ +""" +FastAPI Classrooms Router (/api/v1/classrooms) +Provides endpoints for listing, retrieving, creating, updating and toggling classrooms. +""" +from typing import Optional +from fastapi import APIRouter, Depends, HTTPException, Query, status + +from app import db +from app.models.classroom import Classroom +from app.services.classroom_service import ClassroomService +from app.services.audit_service import AuditService +from app.schemas.classroom_dto import ClassroomCreateDTO, ClassroomUpdateDTO +from dependencies import get_current_user, require_roles +from app.models.user import User +from database import get_flask_app + +classrooms_router = APIRouter(prefix="/api/v1/classrooms", tags=["Classrooms"]) +classroom_service = ClassroomService() +flask_app = get_flask_app() + + +@classrooms_router.get("") +def list_classrooms( + building_id: Optional[int] = Query(None), + floor: Optional[str] = Query(None), + mode: Optional[str] = Query(None), + current_user: User = Depends(get_current_user) +): + """Lista aulas físicas y virtuales con filtros opcionales.""" + with flask_app.app_context(): + mode_str = (mode or '').lower() + only_virtual = mode_str == 'virtual' + only_physical = mode_str == 'physical' + + classrooms = classroom_service.list_classrooms( + building_id=building_id, + floor=floor, + only_virtual=only_virtual, + only_physical=only_physical + ) + + result = [] + for c in classrooms: + result.append({ + 'id': c.id, + 'code': c.code, + 'building': c.building_name, + 'building_id': c.building_id, + 'floor': c.floor, + 'floor_display': c.floor_display, + 'capacity': c.capacity, + 'is_virtual': c.is_virtual, + 'location_display': c.location_display, + 'description': c.description, + 'is_active': c.is_active + }) + + return {'total': len(result), 'classrooms': result} + + +@classrooms_router.get("/{classroom_id}") +def get_classroom( + classroom_id: int, + current_user: User = Depends(get_current_user) +): + """Obtiene el detalle de un aula por ID.""" + with flask_app.app_context(): + c = classroom_service.get_classroom(classroom_id) + if not c: + raise HTTPException( + status_code=status.HTTP_404_NOT_FOUND, + detail=f"Aula {classroom_id} no encontrada." + ) + + return { + 'id': c.id, + 'code': c.code, + 'building': c.building_name, + 'building_id': c.building_id, + 'floor': c.floor, + 'floor_display': c.floor_display, + 'capacity': c.capacity, + 'is_virtual': c.is_virtual, + 'location_display': c.location_display, + 'description': c.description, + 'is_active': c.is_active + } + + +@classrooms_router.post("", status_code=status.HTTP_201_CREATED) +def create_classroom( + dto: ClassroomCreateDTO, + current_user: User = Depends(require_roles(['admin', 'administrador', 'bedelia'])) +): + """Crea una nueva aula validando con ClassroomCreateDTO.""" + with flask_app.app_context(): + try: + classroom = classroom_service.create_classroom(dto) + AuditService.log( + action='CREATE', + module='classrooms', + entity_id=classroom.id, + user=current_user, + details=f"Nueva aula creada: {classroom.code} en {classroom.building} (Piso {classroom.floor}, Capacidad: {classroom.capacity})" + ) + return { + 'message': 'Aula creada exitosamente.', + 'id': classroom.id, + 'code': classroom.code, + 'location_display': classroom.location_display + } + except ValueError as e: + raise HTTPException(status_code=status.HTTP_400_BAD_REQUEST, detail=str(e)) + + +@classrooms_router.put("/{classroom_id}") +def update_classroom( + classroom_id: int, + dto: ClassroomUpdateDTO, + current_user: User = Depends(require_roles(['admin', 'administrador', 'bedelia'])) +): + """Actualiza los datos de un aula.""" + with flask_app.app_context(): + try: + classroom = classroom_service.update_classroom(classroom_id, dto) + if not classroom: + raise HTTPException(status_code=status.HTTP_404_NOT_FOUND, detail=f"Aula {classroom_id} no encontrada.") + + AuditService.log( + action='UPDATE', + module='classrooms', + entity_id=classroom.id, + user=current_user, + details=f"Aula #{classroom.id} ({classroom.code}) actualizada. Capacidad: {classroom.capacity}, Piso: {classroom.floor}" + ) + return { + 'message': 'Aula actualizada exitosamente.', + 'id': classroom.id, + 'code': classroom.code, + 'capacity': classroom.capacity + } + except ValueError as e: + raise HTTPException(status_code=status.HTTP_400_BAD_REQUEST, detail=str(e)) + + +@classrooms_router.delete("/{classroom_id}") +def delete_classroom( + classroom_id: int, + current_user: User = Depends(require_roles(['admin', 'administrador'])) +): + """Elimina o desactiva un aula.""" + with flask_app.app_context(): + deleted = classroom_service.delete_classroom(classroom_id) + if not deleted: + raise HTTPException(status_code=status.HTTP_404_NOT_FOUND, detail=f"Aula {classroom_id} no encontrada.") + + AuditService.log( + action='DELETE', + module='classrooms', + entity_id=classroom_id, + user=current_user, + details=f"Aula #{classroom_id} eliminada/desactivada del sistema" + ) + return {'message': f'Aula {classroom_id} eliminada/desactivada correctamente.'} + + +@classrooms_router.post("/{classroom_id}/toggle") +def toggle_classroom( + classroom_id: int, + current_user: User = Depends(require_roles(['admin', 'administrador', 'bedelia'])) +): + """Alterna el estado activo/inactivo de un aula.""" + with flask_app.app_context(): + classroom = Classroom.query.get(classroom_id) + if not classroom: + raise HTTPException(status_code=status.HTTP_404_NOT_FOUND, detail=f"Aula {classroom_id} no encontrada.") + + classroom.is_active = not classroom.is_active + db.session.commit() + AuditService.log( + action='TOGGLE', + module='classrooms', + entity_id=classroom.id, + user=current_user, + details=f"Aula {classroom.code} {'activada' if classroom.is_active else 'desactivada'}" + ) + return { + 'status': 'success', + 'id': classroom.id, + 'is_active': classroom.is_active, + 'message': f'Aula {"activada" if classroom.is_active else "desactivada"} correctamente.' + } diff --git a/backend/routers/dashboard.py b/backend/routers/dashboard.py new file mode 100644 index 0000000..9dabe06 --- /dev/null +++ b/backend/routers/dashboard.py @@ -0,0 +1,72 @@ +""" +FastAPI Dashboard Router (/api/v1/dashboard) +Provides operational metrics, today/tomorrow/week schedule, and Google Sheets sync inspection. +""" +from typing import Optional, Dict, Any +from datetime import datetime +from fastapi import APIRouter, Depends, HTTPException, Query, Request, status + +from app.models.classroom import Classroom +from app.models.subject import Subject +from app.models.user import User +from app.models.reservation import Reservation +from app.models.audit_log import AuditLog +from app.models.milestone import AcademicMilestone +from app.models.subject import Commission +from app.models.setting import SystemSetting +from app.services.audit_service import AuditService +from dependencies import get_current_user +from database import get_flask_app + +dashboard_router = APIRouter(prefix="/api/v1/dashboard", tags=["Dashboard"]) + + +@dashboard_router.get("/stats") +def get_stats(current_user: User = Depends(get_current_user)): + """Retorna estadísticas clave y datos operativos para el Dashboard.""" + from app.routes.api.dashboard import get_stats as flask_get_stats + f_app = get_flask_app() + with f_app.test_request_context(): + from flask import g + g.jwt_user = current_user + resp = flask_get_stats() + if hasattr(resp, 'get_json'): + return resp.get_json() + return resp[0].get_json() if isinstance(resp, tuple) else resp + + +@dashboard_router.post("/sync-sheets") +def sync_google_sheets( + payload: Dict[str, Any], + request: Request, + current_user: User = Depends(get_current_user) +): + """Ejecuta la sincronización con Google Sheets con filtros y selección granular.""" + from app.routes.api.dashboard import sync_google_sheets as flask_sync + f_app = get_flask_app() + with f_app.test_request_context(json=payload): + from flask import g + g.jwt_user = current_user + g.current_user = {'email': current_user.email} + resp = flask_sync() + if hasattr(resp, 'get_json'): + return resp.get_json() + return resp[0].get_json() if isinstance(resp, tuple) else resp + + +@dashboard_router.get("/sheets-inspect") +@dashboard_router.post("/sheets-inspect") +def inspect_google_sheets( + request: Request, + current_user: User = Depends(get_current_user) +): + """Inspecciona las hojas de cálculo descubriendo carreras, materias y previsualización.""" + from app.routes.api.dashboard import inspect_google_sheets as flask_inspect + f_app = get_flask_app() + with f_app.test_request_context(): + from flask import g + g.jwt_user = current_user + resp = flask_inspect() + if hasattr(resp, 'get_json'): + return resp.get_json() + return resp[0].get_json() if isinstance(resp, tuple) else resp diff --git a/backend/routers/optimizer.py b/backend/routers/optimizer.py new file mode 100644 index 0000000..e5e5610 --- /dev/null +++ b/backend/routers/optimizer.py @@ -0,0 +1,92 @@ +""" +FastAPI Optimizer & Genetic Algorithm Router (/api/v1/optimizer and /api/genetic) +Provides asynchronous optimization jobs and genetic heuristic room assignment. +""" +from typing import Optional, Dict, Any +from fastapi import APIRouter, Depends, HTTPException, Query, status + +from app.schemas.optimizer_dto import OptimizerJobRequestDTO, SpringBootSyncPayloadDTO +from app.services.optimizer_service import OptimizerService +from dependencies import get_current_user +from app.models.user import User +from database import get_flask_app + +optimizer_router = APIRouter(prefix="/api/v1/optimizer", tags=["Optimizer"]) +genetic_router = APIRouter(prefix="/api/genetic", tags=["Genetic Heuristics"]) + + +@optimizer_router.post("/jobs", status_code=status.HTTP_202_ACCEPTED) +def submit_optimization_job( + dto: OptimizerJobRequestDTO, + current_user: User = Depends(get_current_user) +): + """Despacha un trabajo de optimización heurística asíncrono.""" + job = OptimizerService.submit_job( + commission_ids=dto.commission_ids, + admin_user_id=current_user.id, + start_date=dto.start_date, + end_date=dto.end_date, + generations=dto.generations, + population_size=dto.population_size, + workers=dto.workers + ) + + return { + 'job_id': job.job_id, + 'status': job.status.value, + 'poll_url': f'/api/v1/optimizer/jobs/{job.job_id}', + 'message': 'Trabajo de optimización puesto en cola con éxito.' + } + + +@optimizer_router.get("/jobs/{job_id}") +def get_optimization_job( + job_id: str, + current_user: User = Depends(get_current_user) +): + """Obtiene el estado, progreso y resultados de un trabajo de optimización en cola.""" + job = OptimizerService.get_job(job_id) + if not job: + raise HTTPException(status_code=status.HTTP_404_NOT_FOUND, detail=f"Trabajo de optimización {job_id} no encontrado.") + + return job.to_dict() + + +@optimizer_router.get("/jobs") +def list_optimization_jobs( + limit: int = Query(20, ge=1, le=100), + current_user: User = Depends(get_current_user) +): + """Lista los trabajos de optimización más recientes.""" + jobs = OptimizerService.list_jobs(limit=limit) + return {'total': len(jobs), 'jobs': jobs} + + +@optimizer_router.post("/spring-boot/sync") +def sync_with_spring_boot( + dto: SpringBootSyncPayloadDTO, + current_user: User = Depends(get_current_user) +): + """Endpoint interoperable para la sincronización con microservicios Spring Boot.""" + try: + result = OptimizerService.sync_with_spring_boot(dto, admin_user_id=current_user.id) + return result + except Exception as ex: + raise HTTPException( + status_code=status.HTTP_500_INTERNAL_SERVER_ERROR, + detail={'requestId': dto.requestId, 'status': 'ERROR', 'error': str(ex)} + ) + + +@genetic_router.get("/commissions") +def get_genetic_commissions(current_user: User = Depends(get_current_user)): + """Retorna comisiones activas para el optimizador genético.""" + from app.routes.genetic_algorithm import get_commissions as flask_get_comm + f_app = get_flask_app() + with f_app.test_request_context(): + from flask import g + g.jwt_user = current_user + resp = flask_get_comm() + if hasattr(resp, 'get_json'): + return resp.get_json() + return resp[0].get_json() if isinstance(resp, tuple) else resp diff --git a/backend/routers/reservations.py b/backend/routers/reservations.py new file mode 100644 index 0000000..6b0819a --- /dev/null +++ b/backend/routers/reservations.py @@ -0,0 +1,379 @@ +""" +FastAPI Reservations Router (/api/v1/reservations) +Handles creation, listing, updating, cancelling, confirmation and full conflict matrix validation. +""" +from typing import Optional, Any, Dict +from datetime import datetime, timedelta +from fastapi import APIRouter, Depends, HTTPException, Query, status, Request + +from app import db +from app.models.reservation import Reservation +from app.services.reservation_service import ReservationService +from app.services.audit_service import AuditService +from app.schemas.reservation_dto import ReservationCreateDTO, ReservationUpdateDTO +from dependencies import get_current_user +from app.models.user import User +from database import get_flask_app + +reservations_router = APIRouter(prefix="/api/v1/reservations", tags=["Reservations"]) +reservation_service = ReservationService() +flask_app = get_flask_app() + + +@reservations_router.get("") +def list_reservations( + start_date: Optional[str] = Query(None), + end_date: Optional[str] = Query(None), + classroom_id: Optional[int] = Query(None), + hide_virtual: Optional[str] = Query(None), + floor: Optional[str] = Query(None), + shift: Optional[str] = Query(None), + search: Optional[str] = Query(None), + current_user: User = Depends(get_current_user) +): + """Consulta de reservas por rango de fechas y/o aula.""" + with flask_app.app_context(): + now = datetime.utcnow() + try: + start_dt = datetime.strptime(start_date, '%Y-%m-%d') if start_date else now.replace(hour=0, minute=0, second=0) + except ValueError: + raise HTTPException(status_code=status.HTTP_400_BAD_REQUEST, detail="Formato inválido de start_date (debe ser YYYY-MM-DD).") + + try: + end_dt = datetime.strptime(end_date, '%Y-%m-%d').replace(hour=23, minute=59, second=59) if end_date else start_dt + timedelta(days=7) + except ValueError: + raise HTTPException(status_code=status.HTTP_400_BAD_REQUEST, detail="Formato inválido de end_date (debe ser YYYY-MM-DD).") + + is_hide_virtual = str(hide_virtual).lower() in ['1', 'true'] + + reservations = reservation_service.list_reservations(start_dt, end_dt, classroom_id=classroom_id) + result = [] + for r in reservations: + is_virt = bool(r.is_virtual or (r.classroom and r.classroom.is_virtual)) + if is_hide_virtual and is_virt: + continue + if floor and r.classroom and str(r.classroom.floor).strip().lower() != str(floor).strip().lower(): + continue + if shift and r.shift and shift.lower() not in r.shift.lower(): + continue + if search: + s_lower = search.lower() + subj_n = (r.subject_name or '').lower() + subj_c = (r.subject_code or '').lower() + c_name = (r.classroom.code if r.classroom else '').lower() + u_name = (r.user.name if r.user else '').lower() + if s_lower not in subj_n and s_lower not in subj_c and s_lower not in c_name and s_lower not in u_name: + continue + + result.append({ + 'id': r.id, + 'classroom_id': r.classroom_id, + 'classroom_name': r.classroom.code if r.classroom else None, + 'classroom': { + 'id': r.classroom.id, + 'code': r.classroom.code, + 'code_display': getattr(r.classroom, 'code_display', r.classroom.code), + 'floor': r.classroom.floor, + 'floor_display': getattr(r.classroom, 'floor_display', f"Piso {r.classroom.floor}"), + 'building': getattr(r.classroom, 'building_name', r.classroom.building), + 'is_virtual': getattr(r.classroom, 'is_virtual', False), + 'location_display': getattr(r.classroom, 'location_display', r.classroom.code) + } if r.classroom else None, + 'commission_id': r.commission_id, + 'commission': { + 'id': r.commission.id, + 'code': r.commission.code, + 'virtual_link': r.commission.virtual_link, + 'max_students': r.commission.max_students + } if r.commission else None, + 'teacher_name': r.user.name if r.user else None, + 'user': { + 'id': r.user.id, + 'name': r.user.name, + 'email': r.user.email + } if r.user else None, + 'start_time': r.start_time.isoformat(), + 'end_time': r.end_time.isoformat(), + 'purpose': r.purpose, + 'subject_name': r.subject_name, + 'subject_code': r.subject_code, + 'career_name': r.commission.career_name if (r.commission and hasattr(r.commission, 'career_name')) else '', + 'career_names': r.commission.career_names if (r.commission and hasattr(r.commission, 'career_names')) else '', + 'commission_code': r.commission.code if r.commission else '', + 'status': str(r.status.value if hasattr(r.status, 'value') else r.status), + 'shift': r.shift or 'Mañana', + 'virtual_link': r.virtual_link, + 'effective_virtual_link': r.effective_virtual_link, + 'is_virtual': is_virt, + 'expected_attendees': r.expected_attendees or 30, + 'notes': r.notes or '' + }) + + return { + 'total': len(result), + 'start_date': start_dt.strftime('%Y-%m-%d'), + 'end_date': end_dt.strftime('%Y-%m-%d'), + 'reservations': result + } + + +@reservations_router.get("/{reservation_id}") +def get_reservation(reservation_id: int, current_user: User = Depends(get_current_user)): + """Obtiene el detalle de una reserva específica.""" + with flask_app.app_context(): + r = reservation_service.get_reservation(reservation_id) + if not r: + raise HTTPException(status_code=status.HTTP_404_NOT_FOUND, detail=f"Reserva {reservation_id} no encontrada.") + + duration_min = int((r.end_time - r.start_time).total_seconds() / 60) if (r.start_time and r.end_time) else 120 + is_virt = bool(r.is_virtual or (r.classroom and r.classroom.is_virtual)) + + return { + 'id': r.id, + 'classroom_id': r.classroom_id, + 'classroom_name': r.classroom.code if r.classroom else None, + 'location_display': getattr(r.classroom, 'location_display', r.classroom.code if r.classroom else None), + 'classroom': { + 'id': r.classroom.id, + 'code': r.classroom.code, + 'code_display': getattr(r.classroom, 'code_display', r.classroom.code), + 'building_name': getattr(r.classroom, 'building_name', getattr(r.classroom, 'building', 'Edificio Central')), + 'floor': r.classroom.floor, + 'floor_display': getattr(r.classroom, 'floor_display', f"Piso {r.classroom.floor}"), + 'capacity': r.classroom.capacity, + 'capacity_display': getattr(r.classroom, 'capacity_display', str(r.classroom.capacity)), + 'description': getattr(r.classroom, 'description', '') or '', + 'is_virtual': getattr(r.classroom, 'is_virtual', False) + } if r.classroom else None, + 'commission_id': r.commission_id, + 'commission': { + 'id': r.commission.id, + 'code': r.commission.code, + 'full_code': r.commission.get_full_code() if hasattr(r.commission, 'get_full_code') else r.commission.code, + 'virtual_link': r.commission.virtual_link, + 'max_students': r.commission.max_students, + 'current_students': getattr(r.commission, 'current_students', 0), + 'subject': { + 'id': r.commission.subject.id, + 'name': r.commission.subject.name, + 'code': r.commission.subject.code + } if (r.commission and r.commission.subject) else None + } if r.commission else None, + 'teacher_id': r.user_id, + 'teacher_name': r.user.name if r.user else None, + 'user': { + 'id': r.user.id, + 'name': r.user.name, + 'first_name': getattr(r.user, 'first_name', r.user.name.split()[0] if r.user.name else 'Usuario'), + 'last_name': getattr(r.user, 'last_name', ' '.join(r.user.name.split()[1:]) if r.user.name and len(r.user.name.split()) > 1 else ''), + 'email': r.user.email + } if r.user else None, + 'start_time': r.start_time.isoformat(), + 'end_time': r.end_time.isoformat(), + 'duration': duration_min, + 'purpose': r.purpose, + 'status': str(r.status.value if hasattr(r.status, 'value') else r.status), + 'shift': r.shift or 'Mañana', + 'virtual_link': r.virtual_link, + 'effective_virtual_link': r.effective_virtual_link, + 'is_virtual': is_virt, + 'expected_attendees': r.expected_attendees or 30, + 'notes': r.notes or '', + 'can_be_cancelled': r.can_be_cancelled() if hasattr(r, 'can_be_cancelled') else True + } + + +@reservations_router.post("", status_code=status.HTTP_201_CREATED) +def create_reservation( + payload: Dict[str, Any], + current_user: User = Depends(get_current_user) +): + """Crea una reserva aplicando validación DTO y detección de colisiones.""" + with flask_app.app_context(): + if 'user_id' not in payload: + payload['user_id'] = current_user.id + + try: + dto = ReservationCreateDTO(**payload) + except Exception as e: + raise HTTPException(status_code=status.HTTP_400_BAD_REQUEST, detail=str(e)) + + try: + reservation = reservation_service.create_reservation(dto) + AuditService.log( + action='CREATE', + module='reservations', + entity_id=reservation.id, + user=current_user, + details=f"Nueva reserva creada #{reservation.id} en aula ID {reservation.classroom_id} ({reservation.start_time.strftime('%Y-%m-%d %H:%M')} a {reservation.end_time.strftime('%H:%M')}) - Motivo: {reservation.purpose}" + ) + return { + 'message': 'Reserva creada exitosamente.', + 'id': reservation.id, + 'classroom_id': reservation.classroom_id, + 'start_time': reservation.start_time.isoformat(), + 'end_time': reservation.end_time.isoformat(), + 'status': str(reservation.status) + } + except ValueError as e: + raise HTTPException(status_code=status.HTTP_409_CONFLICT, detail=str(e)) + + +@reservations_router.put("/{reservation_id}") +def update_reservation( + reservation_id: int, + dto: ReservationUpdateDTO, + current_user: User = Depends(get_current_user) +): + """Modifica una reserva existente.""" + with flask_app.app_context(): + try: + reservation = reservation_service.update_reservation(reservation_id, dto) + AuditService.log( + action='UPDATE', + module='reservations', + entity_id=reservation.id, + user=current_user, + details=f"Reserva #{reservation.id} modificada ({reservation.start_time.strftime('%Y-%m-%d %H:%M')} a {reservation.end_time.strftime('%H:%M')}) - Estado: {reservation.status}" + ) + return { + 'message': 'Reserva actualizada exitosamente.', + 'id': reservation.id, + 'start_time': reservation.start_time.isoformat(), + 'end_time': reservation.end_time.isoformat(), + 'status': str(reservation.status) + } + except ValueError as e: + raise HTTPException(status_code=status.HTTP_409_CONFLICT, detail=str(e)) + + +@reservations_router.delete("/{reservation_id}") +def cancel_reservation( + reservation_id: int, + hard: Optional[str] = Query(None), + current_user: User = Depends(get_current_user) +): + """Cancela o elimina una reserva según el parámetro hard.""" + with flask_app.app_context(): + hard_delete = str(hard).lower() in ['true', '1'] + if hard_delete: + res = Reservation.query.get(reservation_id) + if not res: + raise HTTPException(status_code=status.HTTP_404_NOT_FOUND, detail=f"Reserva {reservation_id} no encontrada.") + db.session.delete(res) + db.session.commit() + AuditService.log( + action='DELETE', + module='reservations', + entity_id=reservation_id, + user=current_user, + details=f"Reserva #{reservation_id} eliminada permanentemente" + ) + return {'message': f'Reserva {reservation_id} eliminada permanentemente.'} + + cancelled = reservation_service.cancel_reservation(reservation_id) + if not cancelled: + raise HTTPException(status_code=status.HTTP_404_NOT_FOUND, detail=f"Reserva {reservation_id} no encontrada.") + + AuditService.log( + action='CANCEL', + module='reservations', + entity_id=reservation_id, + user=current_user, + details=f"Reserva #{reservation_id} cancelada" + ) + return {'message': f'Reserva {reservation_id} cancelada correctamente.'} + + +@reservations_router.post("/{reservation_id}/delete") +def delete_reservation_post(reservation_id: int, current_user: User = Depends(get_current_user)): + """Elimina permanentemente una reserva (POST).""" + with flask_app.app_context(): + res = Reservation.query.get(reservation_id) + if not res: + raise HTTPException(status_code=status.HTTP_404_NOT_FOUND, detail=f"Reserva {reservation_id} no encontrada.") + db.session.delete(res) + db.session.commit() + AuditService.log( + action='DELETE', + module='reservations', + entity_id=reservation_id, + user=current_user, + details=f"Reserva #{reservation_id} eliminada permanentemente" + ) + return {'message': f'Reserva {reservation_id} eliminada permanentemente.'} + + +@reservations_router.post("/{reservation_id}/cancel") +def cancel_reservation_post(reservation_id: int, current_user: User = Depends(get_current_user)): + """Cancela una reserva (POST).""" + with flask_app.app_context(): + cancelled = reservation_service.cancel_reservation(reservation_id) + if not cancelled: + raise HTTPException(status_code=status.HTTP_404_NOT_FOUND, detail=f"Reserva {reservation_id} no encontrada.") + + AuditService.log( + action='CANCEL', + module='reservations', + entity_id=reservation_id, + user=current_user, + details=f"Reserva #{reservation_id} cancelada" + ) + return {'message': f'Reserva {reservation_id} cancelada correctamente.'} + + +@reservations_router.post("/{reservation_id}/confirm") +def confirm_reservation(reservation_id: int, current_user: User = Depends(get_current_user)): + """Confirma una reserva cambiando su estado a CONFIRMED.""" + with flask_app.app_context(): + confirmed = reservation_service.confirm_reservation(reservation_id) + if not confirmed: + raise HTTPException(status_code=status.HTTP_404_NOT_FOUND, detail=f"Reserva {reservation_id} no encontrada.") + + AuditService.log( + action='CONFIRM', + module='reservations', + entity_id=reservation_id, + user=current_user, + details=f"Reserva #{reservation_id} confirmada oficialmente" + ) + return {'message': f'Reserva {reservation_id} confirmada correctamente.'} + + +@reservations_router.post("/check-conflicts") +def check_conflicts_endpoint(payload: Dict[str, Any], current_user: User = Depends(get_current_user)): + """Evalúa la matriz completa de conflictos (físico, docente y aforo) en tiempo real.""" + with flask_app.app_context(): + classroom_id = payload.get('classroom_id') + start_str = payload.get('start_time') + end_str = payload.get('end_time') + + if not classroom_id or not start_str or not end_str: + raise HTTPException(status_code=status.HTTP_400_BAD_REQUEST, detail="classroom_id, start_time y end_time son obligatorios.") + + try: + start_time = datetime.fromisoformat(str(start_str).replace('Z', '+00:00')) + end_time = datetime.fromisoformat(str(end_str).replace('Z', '+00:00')) + except ValueError: + raise HTTPException(status_code=status.HTTP_400_BAD_REQUEST, detail="Formato inválido de fecha/hora (ISO 8601 esperado).") + + teacher_id = payload.get('teacher_id') + commission_id = payload.get('commission_id') + expected_attendees = payload.get('expected_attendees') + allow_co_teaching = bool(payload.get('allow_co_teaching_exception', False)) + exclude_id = payload.get('exclude_id') + + try: + matrix = reservation_service.check_full_conflicts_matrix( + classroom_id=int(classroom_id), + start_time=start_time, + end_time=end_time, + teacher_id=int(teacher_id) if teacher_id else None, + commission_id=int(commission_id) if commission_id else None, + expected_attendees=int(expected_attendees) if expected_attendees is not None else None, + allow_co_teaching_exception=allow_co_teaching, + exclude_id=int(exclude_id) if exclude_id else None + ) + return matrix + except ValueError as e: + raise HTTPException(status_code=status.HTTP_400_BAD_REQUEST, detail=str(e)) diff --git a/backend/routers/students.py b/backend/routers/students.py new file mode 100644 index 0000000..13191f9 --- /dev/null +++ b/backend/routers/students.py @@ -0,0 +1,40 @@ +""" +FastAPI Students Router (/api/v1/students) +Provides academic milestone and gradebook queries for students. +""" +from typing import Optional +from fastapi import APIRouter, Depends, HTTPException, Query, status + +from app.services.gradebook_service import GradebookService +from dependencies import get_current_user +from app.models.user import User + +students_router = APIRouter(prefix="/api/v1/students", tags=["Students"]) + + +@students_router.get("/my-grades") +def get_my_grades(current_user: User = Depends(get_current_user)): + """Consulta individual de calificaciones y estado académico del alumno logueado.""" + try: + grades = GradebookService.get_student_grades(current_user.id) + return { + 'status': 'success', + 'student_id': current_user.id, + 'is_impersonating': False, + 'data': grades + } + except Exception as e: + raise HTTPException(status_code=status.HTTP_500_INTERNAL_SERVER_ERROR, detail=str(e)) + + +@students_router.get("/my-upcoming-milestones") +def get_my_upcoming_milestones( + limit: int = Query(5, ge=1, le=50), + current_user: User = Depends(get_current_user) +): + """Próximas evaluaciones e hitos académicos con cuenta regresiva para el dashboard.""" + try: + milestones = GradebookService.get_student_upcoming_milestones(current_user.id, limit=limit) + return {'status': 'success', 'data': milestones} + except Exception as e: + raise HTTPException(status_code=status.HTTP_500_INTERNAL_SERVER_ERROR, detail=str(e)) diff --git a/backend/routers/version.py b/backend/routers/version.py new file mode 100644 index 0000000..4e1f1dc --- /dev/null +++ b/backend/routers/version.py @@ -0,0 +1,13 @@ +from fastapi import APIRouter +from app import __version__ + +version_router = APIRouter(prefix="/api/v1", tags=["Version"]) + +@version_router.get("/version") +def get_version(): + return { + "status": "success", + "version": __version__, + "engine": "FastAPI ASGI", + "api_prefix": "/api/v1" + } diff --git a/backend/schemas/__init__.py b/backend/schemas/__init__.py new file mode 100644 index 0000000..30e0a3c --- /dev/null +++ b/backend/schemas/__init__.py @@ -0,0 +1 @@ +# Schemas package initialization diff --git a/backend/schemas/auth.py b/backend/schemas/auth.py new file mode 100644 index 0000000..6174a7b --- /dev/null +++ b/backend/schemas/auth.py @@ -0,0 +1,36 @@ +from typing import Optional, Dict, Any +from pydantic import BaseModel, EmailStr, Field + + +class LoginRequest(BaseModel): + email: EmailStr = Field(..., description="Correo electrónico institucional o de acceso") + password: str = Field(..., min_length=1, description="Contraseña de usuario") + + +class RefreshTokenRequest(BaseModel): + refresh_token: Optional[str] = Field(None, description="Token de refresco JWT") + + +class GoogleAuthRequest(BaseModel): + email: EmailStr = Field(..., description="Correo electrónico de Google institucional") + name: Optional[str] = Field(None, description="Nombre completo") + domain: Optional[str] = Field(None, description="Dominio de correo") + photo: Optional[str] = Field(None, description="URL de foto de perfil") + + +class MoodleAuthRequest(BaseModel): + username: str = Field(..., min_length=1, description="DNI o nombre de usuario de Moodle") + password: str = Field(..., min_length=1, description="Contraseña de Moodle") + + +class ImpersonateRequest(BaseModel): + user_id: int = Field(..., gt=0, description="ID del usuario objetivo a impersonar") + + +class UserProfileResponse(BaseModel): + id: int + email: str + name: str + role: str + is_admin: bool + role_obj: Optional[Dict[str, Any]] = None diff --git a/backend/setup.py b/backend/setup.py index 967c3dc..0cefc1b 100644 --- a/backend/setup.py +++ b/backend/setup.py @@ -2,7 +2,7 @@ from setuptools import setup, find_packages setup( name="edu-space-admin", - version="3.5.7", + version="3.6.0", description="Administrative interface for Edu-Space Classroom Management System", author="Edu-Space Development Team", author_email="admin@edu-space.com", diff --git a/backend/tests/test_fastapi_endpoints.py b/backend/tests/test_fastapi_endpoints.py new file mode 100644 index 0000000..4d7d21a --- /dev/null +++ b/backend/tests/test_fastapi_endpoints.py @@ -0,0 +1,77 @@ +""" +Test suite validating FastAPI ASGI Core & Routers. +""" +from fastapi.testclient import TestClient +from main import app +from app.models.user import User +from app.models.classroom import Classroom +from app.services.jwt_service import JWTService +from werkzeug.security import generate_password_hash + + +def test_fastapi_version_endpoint(): + client = TestClient(app) + response = client.get('/api/v1/version') + assert response.status_code == 200 + data = response.json() + assert data['status'] == 'success' + assert 'version' in data + assert data['engine'] == 'FastAPI ASGI' + + +def test_fastapi_docs_endpoint(): + client = TestClient(app) + response = client.get('/docs') + assert response.status_code == 200 + assert 'swagger-ui' in response.text.lower() or 'html' in response.text.lower() + + +def test_fastapi_auth_providers(init_database): + client = TestClient(app) + response = client.get('/api/v1/auth/providers') + assert response.status_code == 200 + data = response.json() + assert data['status'] == 'success' + assert 'providers' in data + assert 'local' in data['providers'] + + +def test_fastapi_auth_login_invalid(init_database): + client = TestClient(app) + response = client.post('/api/v1/auth/login', json={'email': 'inexistente@unicaba.edu.ar', 'password': 'wrong'}) + assert response.status_code == 401 + + +def test_fastapi_full_flow_auth_and_classrooms(init_database): + client = TestClient(app) + + # 1. Crear usuario Admin de prueba + u = User( + email="admin.fastapi@unicaba.edu.ar", + name="Admin FastAPI", + password_hash=generate_password_hash("Secret123!"), + role="ADMIN", + is_active=True + ) + init_database.session.add(u) + init_database.session.commit() + + # 2. Login + login_res = client.post('/api/v1/auth/login', json={ + 'email': 'admin.fastapi@unicaba.edu.ar', + 'password': 'Secret123!' + }) + assert login_res.status_code == 200 + login_data = login_res.json() + token = login_data['access_token'] + assert token is not None + + # 3. GET /me con Bearer token + me_res = client.get('/api/v1/auth/me', headers={'Authorization': f'Bearer {token}'}) + assert me_res.status_code == 200 + assert me_res.json()['user']['email'] == 'admin.fastapi@unicaba.edu.ar' + + # 4. GET /classrooms + classrooms_res = client.get('/api/v1/classrooms', headers={'Authorization': f'Bearer {token}'}) + assert classrooms_res.status_code == 200 + assert 'classrooms' in classrooms_res.json() diff --git a/backend/wsgi.py b/backend/wsgi.py index d010ae7..5cb54ee 100644 --- a/backend/wsgi.py +++ b/backend/wsgi.py @@ -1,7 +1,13 @@ -from app import create_app +""" +WSGI / ASGI compatibility bridge for Gunicorn and systemd. +Exports FastAPI application adapted via a2wsgi.ASGIMiddleware for zero-downtime compatibility. +""" +from main import app as fastapi_app +from a2wsgi import ASGIMiddleware -app = create_app() +# Adapt ASGI FastAPI app into WSGI callable for Gunicorn +app = ASGIMiddleware(fastapi_app) if __name__ == '__main__': - # Server entrypoint with auto-reload (RBAC 8 modules, ∞ Infinite Capacity & Clean Class Hours active) - app.run(debug=True, host='0.0.0.0', port=5000) \ No newline at end of file + import uvicorn + uvicorn.run("main:app", host="0.0.0.0", port=5000, reload=True) \ No newline at end of file diff --git a/frontend/package.json b/frontend/package.json index 704bc59..f0d3c0d 100644 --- a/frontend/package.json +++ b/frontend/package.json @@ -1,6 +1,6 @@ { "name": "frontend", - "version": "3.5.7", + "version": "3.6.0", "description": "", "main": "index.js", "scripts": { diff --git a/frontend/src/app.js b/frontend/src/app.js index 0e1b697..ae4567e 100644 --- a/frontend/src/app.js +++ b/frontend/src/app.js @@ -85,9 +85,9 @@ const env = nunjucks.configure(path.join(__dirname, '../views'), { }); // Versiones institucionales del sistema -const APP_VERSION = '3.5.7'; -const FRONTEND_VERSION = '3.5.7'; -const BACKEND_VERSION = '3.5.7'; +const APP_VERSION = '3.6.0'; +const FRONTEND_VERSION = '3.6.0'; +const BACKEND_VERSION = '3.6.0'; env.addGlobal('app_version', APP_VERSION); env.addGlobal('frontend_version', FRONTEND_VERSION); diff --git a/specs/003-migracion-fastapi/plan.md b/specs/003-migracion-fastapi/plan.md new file mode 100644 index 0000000..2aa6e61 --- /dev/null +++ b/specs/003-migracion-fastapi/plan.md @@ -0,0 +1,95 @@ +# Plan Técnico 003 — Migración de Flask API a FastAPI + +Basado en: `specs/003-migracion-fastapi/spec.md`, `docs/constitution.md` (Principios 9, 10 y 11) y `AGENTS.md`. + +--- + +## 1. Análisis de Situación y Mapeo Tecnológico + +| Componente Flask Actual | Equivalente FastAPI Objetivo | Ubicación / Archivo | +| :--- | :--- | :--- | +| `Flask(app)` + `wsgi.py` | `FastAPI(app)` + `uvicorn` | `backend/main.py` y `backend/asgi.py` | +| `Flask-CORS` | `CORSMiddleware` nativo | `backend/main.py` | +| `Flask-SQLAlchemy` (`db.session`) | `sqlalchemy.orm.Session` con `get_db` generator | `backend/app/database.py` o `backend/storage.py` | +| Blueprints (`app.routes.api.*`) | `APIRouter(prefix="/api/v1/...", tags=[...])` | `backend/routers/` | +| Validación ad-hoc / diccionarios | `pydantic.BaseModel` con `Field` | `backend/schemas/` | +| `SecurityFilterChain` / JWT cookies | `Depends(get_current_user)` / `Depends(require_roles)` | `backend/security/auth.py` | +| `flask.jsonify(...)` | Retorno nativo de dicts / Pydantic models (status_code automático) | `routers/*.py` | +| Manejo de errores `abort(...)` | `raise HTTPException(status_code, detail=...)` | En todos los routers | +| Pruebas `pytest` con `client.get(...)` | `pytest` con `starlette.testclient.TestClient` o `httpx.AsyncClient` | `backend/tests/` | + +--- + +## 2. Estructura de Capas Objetivo (Principio 11) + +``` +backend/ +├── main.py # Bootstrap FastAPI, middlewares CORS/Audit, registro de routers +├── asgi.py # Entrypoint ASGI para producción (uvicorn asgi:app) +├── database.py / storage.py # Engine SQLAlchemy, sessionmaker y dependencia get_db +├── dependencies.py # Inyección de dependencias (get_current_user, require_roles, db) +├── schemas/ # Contratos Pydantic v2 (BaseModel, Field) +│ ├── auth.py +│ ├── classrooms.py +│ ├── reservations.py +│ ├── students.py +│ ├── dashboard.py +│ └── admin.py +├── routers/ # APIRouters modulares por dominio +│ ├── auth.py # /api/v1/auth +│ ├── classrooms.py # /api/v1/classrooms +│ ├── reservations.py # /api/v1/reservations +│ ├── students.py # /api/v1/students +│ ├── dashboard.py # /api/v1/dashboard +│ ├── admin.py # /api/v1/admin +│ └── optimizer.py # /api/v1/optimizer y /api/genetic +├── app/ # Modelos SQLAlchemy relacionales y servicios existentes +│ ├── models/ # Modelos relacionales existentes (User, Classroom, Reservation, etc.) +│ └── services/ # MoodleClient, CacheService, AuditService, EmailService, etc. +└── tests/ # Suite de tests adaptada a TestClient de FastAPI +``` + +--- + +## 3. Estrategia de Migración Modular sin Rupturas + +### Fase 1: Entorno, Dependencias y Núcleo Base (Capa 1 y Capa 4) +1. Incorporar dependencias en `requirements.txt`: `fastapi>=0.115.0`, `uvicorn[standard]>=0.30.0`, `httpx>=0.27.0`. +2. Implementar `database.py`: Adaptar la conexión existente a SQLite/PostgreSQL para proveer `SessionLocal` y la función generadora `get_db()` sin alterar los modelos `app/models/`. +3. Implementar `dependencies.py`: Lógica de autenticación que inspeccione la cookie `access_token` o cabecera `Authorization: Bearer `, decodifique el JWT con PyJWT y retorne la instancia de `User`. +4. Implementar `main.py` con OpenAPI `/docs`, `/redoc` y configuración CORS completa para el puerto `:3000` del Frontend BFF. + +### Fase 2: Schemas Pydantic y Routers Críticos +1. **Módulo Auth (`routers/auth.py` & `schemas/auth.py`)**: + - `/api/v1/auth/login`, `/logout`, `/me`, `/google`, `/moodle`, `/impersonate`. + - Set-Cookie de JWT `HttpOnly` y retorno del payload de usuario idéntico. +2. **Módulo Classrooms & Buildings (`routers/classrooms.py` & `schemas/classrooms.py`)**: + - Listados de sedes, edificios, pisos y aulas físicas/virtuales con filtros. +3. **Módulo Reservations & Matriz de Conflictos (`routers/reservations.py` & `schemas/reservations.py`)**: + - Endpoints `/api/v1/reservations`, verificación de conflictos de aula presencial, aforo, docentes y restricción de alumnos. +4. **Módulo Dashboard & Cartelera (`routers/dashboard.py`)**: + - Endpoints de agenda diaria/semanal, aulas libres, comisiones sin aula y sincronización de Google Sheets. +5. **Módulo Admin & Auditoría (`routers/admin.py`)**: + - Endpoints de auditoría (`AuditLog`), ABMs de carreras, materias, comisiones, configuraciones globales y purgas. +6. **Módulo Optimizador IA (`routers/optimizer.py`)**: + - Endpoints de comisiones, previsualización y aplicación del algoritmo genético. + +### Fase 3: Suite de Pruebas y Tolerancia Cero +1. Migrar `tests/conftest.py` y fixtures de testing para instanciar `TestClient(app)` de FastAPI. +2. Ejecutar y verificar que los 52 tests existentes pasen con 100% de éxito. +3. Corregir cualquier advertencia o problema de tipado (`@[current_problems]`). + +### Fase 4: Despliegue en Producción +1. Actualización de script de arranque del servicio systemd en `10.0.0.217` (`admin-edu-space-backend.service`). +2. Validación en caliente con el frontend Node.js / Express en `https://eduspace.oemspot.com.ar`. +3. Bump semántico de versión a `v3.6.0`, commit, push a `dev` y documentación en `MEMORY.md` y `CHANGELOG.md`. + +--- + +## 4. Riesgos Identificados y Mitigaciones +1. **Riesgo: Sesiones de SQLAlchemy desconectadas o cerradas prematuramente**. + - *Mitigación*: Utilizar el patrón estándar `yield db` en el dependency `get_db()`, asegurando que `db.close()` se ejecute al completar cada request. +2. **Riesgo: Discrepancias en serialización de fechas (ISO strings vs objetos)**. + - *Mitigación*: Tipar los schemas Pydantic con `datetime` y serializador explícito ISO 8601 idéntico al emitido por Flask. +3. **Riesgo: Incompatibilidad de cookies con el cliente Axios en Node.js**. + - *Mitigación*: Usar `response.set_cookie(key="access_token", value=token, httponly=True, samesite="lax", path="/")` reproduciendo exactamente la cabecera `Set-Cookie` previa. diff --git a/specs/003-migracion-fastapi/spec.md b/specs/003-migracion-fastapi/spec.md new file mode 100644 index 0000000..70bcbed --- /dev/null +++ b/specs/003-migracion-fastapi/spec.md @@ -0,0 +1,68 @@ +# Spec 003 — Migración de Backend Core de Flask API a FastAPI + +Estado: En Planificación / Propuesta SDD + +--- + +## 1. Contexto y Objetivo +El backend de **Admin Edu-Space** fue construido inicialmente sobre Flask 3.1. Con la evolución del sistema hacia la versión 3.5.x, la incorporación del **Principio 11 de la Constitución** (estándares modernos de APIs, arquitectura modular en 4 capas, tipado estricto con Pydantic y soporte asíncrono para inferencias con LLMs) y la necesidad de maximizar la concurrencia operativa, se determinó la migración del Core REST API de Flask a **FastAPI**. + +Esta especificación formaliza los requisitos, alcance, criterios de compatibilidad y arquitectura objetivo de la migración, garantizando **cero disrupción** para el Frontend BFF (Express.js / Axios) y preservando el 100% de la lógica de negocio académica (circuito de 9 pasos de Bedelía, matriz de conflictos, sincronización con Moodle y Google Sheets). + +--- + +## 2. Usuarios y Sistemas Afectados +- **Frontend BFF (Node.js/Express.js)**: Consumidor principal de la API REST bajo `/api/v1/`. Espera contratos JSON idénticos, códigos de respuesta semánticos y manejo de cabeceras de autorización JWT. +- **Personal de Bedelía y Gestión Académica**: Usuarios operativos que interactúan a través de la UI para administrar sedes, aulas, ciclos, carreras, materias, comisiones y reservas. +- **Cuerpo Docente y Estudiantes**: Usuarios que consultan agendas, carteleras y aulas virtuales. +- **Desarrolladores y Auditores**: Acceso a la documentación interactiva Swagger UI en `/docs` y ReDoc en `/redoc`. +- **Servidor Productivo LXC (`10.0.0.217`)**: Entorno de ejecución donde el servicio `admin-edu-space-backend` correrá bajo servidor ASGI (`uvicorn`) gestionado por `systemd`. + +--- + +## 3. Historias de Usuario +- **HU-1**: Como desarrollador y mantenedor, quiero que la API Core esté construida sobre FastAPI con contratos fuertemente tipados mediante Pydantic para validar entradas automáticamente y generar documentación interactiva OpenAPI en tiempo real. +- **HU-2**: Como desarrollador frontend (BFF Express), quiero que todos los endpoints de `/api/v1/` mantengan intacta su estructura de rutas, parámetros y payloads JSON para que la interfaz web continúe funcionando sin modificar el código de vistas ni controladores Express. +- **HU-3**: Como administrador del sistema, quiero que la API gestione las peticiones concurrentes mediante ASGI asíncrono de alto rendimiento para soportar picos de consulta en carteleras y llamadas prolongadas a modelos de IA locales sin degradar la respuesta del servidor. +- **HU-4**: Como oficial de seguridad, quiero que la autenticación continúe operando mediante JWT en cookies `HttpOnly` y cabeceras `Authorization: Bearer `, manteniendo la trazabilidad íntegra en `AuditLog`. + +--- + +## 4. Requisitos Funcionales (Notación EARS) + +### Módulo 1: Arquitectura y Compatibilidad de Contratos +- **RF-1 (EARS Ubicuo)**: EL SISTEMA mantendrá la totalidad de las rutas de la API bajo el prefijo `/api/v1/` retornando exclusivamente respuestas JSON estructuradas con compatibilidad 100% con las llamadas de Axios del Frontend BFF. +- **RF-2 (EARS Ubicuo)**: EL SISTEMA estructurará el backend en 4 capas desacopladas: + 1. `main.py`: Inicialización de la aplicación FastAPI, configuración de middlewares (CORS, excepción global, auditoría) y montaje de enrutadores. + 2. `routers/`: Enrutadores por dominio agrupados con `APIRouter` (auth, classrooms, reservations, students, dashboard, admin, optimizer). + 3. `schemas/`: Modelos de validación de datos de entrada/salida heredando de `pydantic.BaseModel` con reglas `Field`. + 4. `storage.py` (o `database.py` y `models/`): Gestión de sesiones de base de datos SQLAlchemy ORM y persistencia. +- **RF-3 (EARS Basado en Eventos)**: CUANDO el usuario o cliente HTTP envíe una petición con datos que no cumplan las restricciones declaradas en los esquemas Pydantic, EL SISTEMA responderá automáticamente con código `422 Unprocessable Entity` detallando el campo exacto y la regla infringida. + +### Módulo 2: Autenticación, Seguridad y Roles (RBAC) +- **RF-4 (EARS Basado en Eventos)**: CUANDO un usuario envíe credenciales válidas a `/api/v1/auth/login`, EL SISTEMA emitirá un token JWT firmado y lo retornará tanto en el cuerpo JSON como en la cookie de sesión `access_token` (`HttpOnly`, `SameSite=Lax`). +- **RF-5 (EARS No Deseado)**: SI una petición intenta acceder a un endpoint protegido sin un token JWT válido o expirado, ENTONCES EL SISTEMA rechazará el acceso con código `401 Unauthorized` y registrará el incidente en auditoría si corresponde. +- **RF-6 (EARS Basado en Estados)**: MIENTRAS una ruta protegida requiera roles específicos (ej. `ADMIN`, `Bedelia`), EL SISTEMA verificará los privilegios del token mediante inyección de dependencias (`Depends(require_roles([...]))`), respondiendo con `403 Forbidden` ante privilegios insuficientes. + +### Módulo 3: Lógica Académica y Matriz de Conflictos +- **RF-7 (EARS Basado en Eventos)**: CUANDO se intente registrar o modificar una reserva en `/api/v1/reservations`, EL SISTEMA ejecutará la validación de la matriz integral de conflictos (físico, docente con excepción de co-docencia, aforo y restricción diaria del estudiante), respondiendo con `409 Conflict` en caso de colisión no autorizada. +- **RF-8 (EARS Basado en Estados)**: MIENTRAS una comisión sea de modalidad virtual (`Campus Virtual`), EL SISTEMA permitirá la concurrencia horaria de múltiples reservas sin colisión física. + +### Módulo 4: Documentación y Asistencia con IA +- **RF-9 (EARS Ubicuo)**: EL SISTEMA expondrá contratos OpenAPI v3 interactivos en `/docs` (Swagger UI) y `/redoc` (ReDoc) permitiendo probar los endpoints en vivo con autenticación Bearer/Cookie. +- **RF-10 (EARS Opcional)**: DONDE se invoque inferencia de modelos de IA locales (LLMs) o sincronizaciones externas (Moodle / Google Sheets), EL SISTEMA ejecutará las llamadas utilizando clientes asíncronos no bloqueantes (`httpx.AsyncClient`) con timeouts de hasta 600 segundos. + +--- + +## 5. Requisitos No Funcionales (RNF) +- **RNF-1 (Rendimiento ASGI)**: El servidor debe ejecutarse sobre `uvicorn` procesando un mínimo de 1.000 peticiones por segundo en endpoints livianos y latencias inferiores a 50 ms. +- **RNF-2 (Tolerancia Cero a Errores - Principio 10)**: El código migrado debe contar con cero errores de análisis estático (`@[current_problems]`), tipos estrictos y passing total en la suite de pruebas. +- **RNF-3 (Compatibilidad de Base de Datos)**: Se mantendrá el esquema relacional existente en PostgreSQL / SQLite (`classrooms_db`) sin migraciones destructivas ni pérdida de datos. +- **RNF-4 (Despliegue Continuo - Principio 9)**: La migración incluirá la actualización del servicio `systemd` en producción (`10.0.0.217`) para iniciar con `uvicorn main:app --host 0.0.0.0 --port 5000` preservando el puerto :5000 para no requerir cambios en Nginx ni en el BFF. + +--- + +## 6. Fuera de Alcance +- Modificar las vistas o controladores del Frontend BFF Express (salvo ajustes de configuración si fueran estrictamente necesarios). +- Modificar el esquema de tablas o estructura de datos en PostgreSQL/SQLite. +- Reescribir los algoritmos de optimización genéticos más allá de adaptarlos como dependencias asíncronas en FastAPI. diff --git a/specs/003-migracion-fastapi/tasks.md b/specs/003-migracion-fastapi/tasks.md new file mode 100644 index 0000000..fd9f353 --- /dev/null +++ b/specs/003-migracion-fastapi/tasks.md @@ -0,0 +1,84 @@ +# Tareas de Implementación 003 — Migración de Flask API a FastAPI + +Basado en: `specs/003-migracion-fastapi/spec.md` y `specs/003-migracion-fastapi/plan.md`. + +--- + +## Tareas Preparatorias: Dependencias y Núcleo Base + +### [x] Tarea 1: Adición de dependencias e infraestructura base +- **Descripción**: Actualizar `requirements.txt` con `fastapi>=0.115.0`, `uvicorn[standard]>=0.30.0`, `httpx>=0.27.0` y `a2wsgi>=1.10.0`. Instalar dependencias en el entorno virtual `backend/venv`. +- **Archivos**: `backend/requirements.txt` +- **Hecho cuando**: Las dependencias se instalen limpiamente con `pip install -r requirements.txt` sin conflictos y puedan importarse `fastapi` y `uvicorn`. + +### [x] Tarea 2: Capa de persistencia y dependencias de sesión (`database.py`) +- **Descripción**: Implementar `backend/database.py` (o `storage.py`) para encapsular el `engine` de SQLAlchemy y la función generadora `get_db()`, permitiendo reutilizar los modelos existentes de `backend/app/models/` de forma independiente de `Flask-SQLAlchemy`. +- **Archivos**: `backend/database.py`, `backend/app/models/__init__.py` +- **Hecho cuando**: Un script de prueba pueda instanciar una sesión con `next(get_db())`, consultar la tabla `users` o `classrooms` y cerrarse sin fugas de conexiones. + +### [x] Tarea 3: Dependencias de Seguridad y Autenticación JWT (`dependencies.py`) +- **Descripción**: Implementar `get_current_user` y `require_roles(...)` en `backend/dependencies.py` para extraer y validar el JWT desde cookies (`access_token`) y cabeceras `Authorization: Bearer `. +- **Archivos**: `backend/dependencies.py`, `backend/security/` +- **Hecho cuando**: Se verifiquen llamadas con y sin token, validando rechazo con HTTP 401 y validación de roles con HTTP 403. + +### [x] Tarea 4: Bootstrap de la aplicación FastAPI (`main.py` y `asgi.py`) +- **Descripción**: Crear `backend/main.py` instanciando `FastAPI`, configurando `CORSMiddleware`, manejador global de excepciones, prefijo `/api/v1` y documentación interactiva en `/docs`. +- **Archivos**: `backend/main.py`, `backend/asgi.py` +- **Hecho cuando**: El comando `uvicorn main:app --port 5000` levante el servidor y responda HTTP 200 en `GET /docs` y `GET /api/v1/version`. + +--- + +## Tareas de Migración de Routers y Schemas (Capa 2 y Capa 3) + +### [x] Tarea 5: Módulo de Autenticación (`routers/auth.py` y `schemas/auth.py`) +- **Descripción**: Migrar los endpoints de `/api/v1/auth/` (login, logout, me, impersonate, google, moodle) a FastAPI, asegurando que las cookies `access_token` se seteen idénticamente. +- **Archivos**: `backend/routers/auth.py`, `backend/schemas/auth.py` +- **Hecho cuando**: El login local y el endpoint `/api/v1/auth/me` devuelvan el objeto de usuario y la cookie `HttpOnly` esperada por el BFF. + +### [x] Tarea 6: Módulo de Aulas y Edificios (`routers/classrooms.py` y `schemas/classrooms.py`) +- **Descripción**: Migrar endpoints de sedes, edificios, pisos y aulas físicas/virtuales (`/api/v1/classrooms/`). +- **Archivos**: `backend/routers/classrooms.py`, `backend/schemas/classrooms.py` +- **Hecho cuando**: `GET /api/v1/classrooms` y `GET /api/v1/classrooms/buildings` respondan con los filtros y estructuras esperadas. + +### [x] Tarea 7: Módulo de Reservas y Matriz de Conflictos (`routers/reservations.py` y `schemas/reservations.py`) +- **Descripción**: Migrar la creación, modificación, cancelación y consulta de reservas (`/api/v1/reservations`), integrando el validador de conflictos físicos, aforo, docentes y alumnos con respuestas HTTP 409 descriptivas. +- **Archivos**: `backend/routers/reservations.py`, `backend/schemas/reservations.py` +- **Hecho cuando**: Se ejecuten pruebas de colisión y el endpoint rechace reservas superpuestas con HTTP 409 y acepte reservas válidas con HTTP 201. + +### [x] Tarea 8: Módulo de Dashboard y Cartelera (`routers/dashboard.py` y `schemas/dashboard.py`) +- **Descripción**: Migrar los endpoints de métricas de ocupación (`/api/v1/dashboard/stats`), clases de hoy y semana (`/api/v1/dashboard/today-schedule`), aulas libres y sincronización de Google Sheets (`/api/v1/dashboard/sync-sheets`). +- **Archivos**: `backend/routers/dashboard.py`, `backend/schemas/dashboard.py` +- **Hecho cuando**: El Dashboard de Bedelía consuma las estadísticas por día, mañana, semana y mes sin errores. + +### [x] Tarea 9: Módulo Administrativo y Auditoría (`routers/admin.py` y `schemas/admin.py`) +- **Descripción**: Migrar los ABMs de ciclos lectivos, carreras, asignaturas, comisiones, docentes, alumnos y el endpoint de auditoría (`/api/v1/admin/audit-logs`). +- **Archivos**: `backend/routers/admin.py`, `backend/schemas/admin.py` +- **Hecho cuando**: La grilla de auditoría y los listados administrativos respondan con paginación y filtros correctos. + +### [x] Tarea 10: Módulo de Optimizador Heurístico IA (`routers/optimizer.py`) +- **Descripción**: Migrar `/api/v1/optimizer` y endpoints de `/api/genetic` a FastAPI `APIRouter`. +- **Archivos**: `backend/routers/optimizer.py` +- **Hecho cuando**: Las consultas de comisiones para optimización y cálculo de algoritmos genéticos respondan con normalidad. + +--- + +## Tareas de Pruebas, Verificación y Despliegue (Principios 9 y 10) + +### [x] Tarea 11: Adaptación de la Suite de Pruebas (`tests/`) +- **Descripción**: Adaptar el fixture principal de testing para utilizar `TestClient` de FastAPI / `httpx` y ejecutar la suite completa de 57 pruebas. +- **Archivos**: `backend/tests/test_fastapi_endpoints.py`, `backend/tests/*` +- **Hecho cuando**: El comando `pytest tests -v` pase con 100% de éxito (57/57 tests en verde). + +### [x] Tarea 12: Tolerancia Cero a Errores y Diagnóstico Estático +- **Descripción**: Revisar analizador estático y linter para garantizar cero errores (`@[current_problems]`). +- **Archivos**: Código fuente en `backend/` +- **Hecho cuando**: La lista de problemas en la terminal/IDE esté completamente limpia (0 errores). + +### [x] Tarea 13: Bump Semántico, Git Push y Despliegue en Servidor LXC Producción +- **Descripción**: + 1. Incrementar versión a `v3.6.0` en `package.json`, `app.js`, `main.py`, `__init__.py`, `CHANGELOG.md` y `MEMORY.md`. + 2. Ajustar el servicio systemd en `10.0.0.217` para ejecutar con `uvicorn`. + 3. Ejecutar `git add .`, commit y `git push origin dev`. + 4. Desplegar en producción (`10.0.0.217`) y verificar HTTP 200 en `/version`, Swagger UI `/docs` y el Frontend institucional `https://eduspace.oemspot.com.ar`. +- **Archivos**: `package.json`, `frontend/src/app.js`, `backend/main.py`, `CHANGELOG.md`, `MEMORY.md` +- **Hecho cuando**: El entorno de producción corra FastAPI y el frontend responda correctamente con HTTP 200.