feat(api): migracion completa de Flask API a FastAPI ASGI con arquitectura en 4 capas v3.6.0

This commit is contained in:
2026-10-16 17:36:44 -03:00
parent 5057d648c9
commit 37c21e1cd8
28 changed files with 1956 additions and 309 deletions
+16
View File
@@ -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)**:
+309 -296
View File
@@ -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 `<datalist>` 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 (`<input type="date">`) 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.
# 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 `<datalist>` 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 (`<input type="date">`) 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.␍
+1 -1
View File
@@ -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()
+1 -1
View File
@@ -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": [
{
+9 -2
View File
@@ -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:
+9
View File
@@ -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)
+21
View File
@@ -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
+119
View File
@@ -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
+59
View File
@@ -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)
+4
View File
@@ -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
+1
View File
@@ -0,0 +1 @@
# Routers package initialization
+243
View File
@@ -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)}")
+192
View File
@@ -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.'
}
+72
View File
@@ -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
+92
View File
@@ -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
+379
View File
@@ -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))
+40
View File
@@ -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))
+13
View File
@@ -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"
}
+1
View File
@@ -0,0 +1 @@
# Schemas package initialization
+36
View File
@@ -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
+1 -1
View File
@@ -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",
+77
View File
@@ -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()
+10 -4
View File
@@ -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)
import uvicorn
uvicorn.run("main:app", host="0.0.0.0", port=5000, reload=True)
+1 -1
View File
@@ -1,6 +1,6 @@
{
"name": "frontend",
"version": "3.5.7",
"version": "3.6.0",
"description": "",
"main": "index.js",
"scripts": {
+3 -3
View File
@@ -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);
+95
View File
@@ -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 <token>`, 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.
+68
View File
@@ -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 <token>`, 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.
+84
View File
@@ -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 <token>`.
- **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.