Files
admin-edu-space/AGENTS.md
T

4.2 KiB

AGENTS.md - admin-edu-space (Rama dev / MVP)

Plataforma web de gestión de espacios áulicos, sincronización académica y asignación de cursadas para UniCABA, diseñada para reemplazar el uso de planillas Excel en Bedelía, orquestar calendarios en tiempo real y conectarse con Moodle 4.1 y Google Workspace.

Stack y Estructura

  • Arquitectura: Desacoplada (Backend Core REST API + Frontend BFF).
  • Backend Core: Python 3.12, Flask 3.1, SQLAlchemy ORM, SQLite / PostgreSQL 15, Marshmallow/Pydantic DTOs, Flask-JWT-Extended (HS256 stateless).
  • Frontend BFF: Node.js v20+, Express.js, motor de plantillas Nunjucks, cliente Axios con interceptores de autorización Bearer, Bootstrap 5 + Vanilla CSS.
  • Integraciones Clave:
    • Google OAuth 2.0 para autenticación institucional restringida a @unicaba.edu.ar.
    • Moodle 4.1 REST API (core_webservice_*, enrol_*) con cola asíncrona resiliente (MoodleSyncTask), reintentos exponenciales, Dead Letter Queue (DLQ) y capa de caché híbrida (CacheService en Redis / memoria).
    • Motor de Notificaciones SMTP dinámico (EmailService) con credenciales cifradas con Fernet en base de datos.
    • Importador oficial de Google Sheets (sheets_importer.py) para ingesta masiva inicial.
  • Entorno de Ejecución: Contenedores Linux LXC en Proxmox con Nginx como proxy inverso y terminación SSL (entorno productivo institucional: eduspace.oemspot.com.ar).

Comandos de Desarrollo y Verificación

  • Levantar Backend (Flask API :5000):
    cd backend
    .\venv\Scripts\activate
    flask run --port 5000
    
  • Levantar Frontend BFF (Express :3000):
    cd frontend
    npm run dev
    
  • Ejecutar Suite de Pruebas Automatizadas (Backend):
    cd backend
    .\venv\Scripts\activate
    pytest tests -v
    
  • Auditoría Automatizada de Seguridad (SAST / SCA / DAST):
    .\security_audit.bat --no-pause
    

Convenciones de Desarrollo

  • Nombres de variables, funciones, clases, tablas, endpoints y commits estrictamente en inglés.
  • Los endpoints de la API deben seguir estándares RESTful puros bajo /api/v1/ retornando exclusivamente JSON.
  • Interfaz gráfica de usuario, etiquetas de formularios, mensajes de error y documentación operativa exclusivamente en español.

Reglas de Dominio y Trampas Conocidas

  • Reemplazo del Excel de Bedelía: La gestión operativa diaria debe realizarse en la app a través del circuito secuencial de 9 pasos (Sedes -> Aulas -> Ciclos Lectivos -> Carreras -> Asignaturas -> Comisiones -> Profesores -> Alumnos -> Reservas). Las comisiones heredan y exponen la Carrera de la asignatura para trazabilidad por plan de estudios. Las hojas de cálculo son únicamente para importación masiva de datos iniciales.
  • Sincronización con Moodle: Prohibido hacer peticiones directas y síncronas bloqueantes a Moodle dentro de los controladores de usuario. Utilizar siempre CacheService para lecturas y encolar en MoodleSyncTask para escrituras.
  • Matriz de Conflictos de Reservas: Una reserva no puede guardarse si genera superposición física de aula presencial, sobrepasa el aforo máximo o solapa al docente (salvo excepción justificada por co-docencia activa).
  • Restricción Diaria de Alumnos: Un alumno no puede matricularse en dos materias regulares en el mismo día, a menos que sea un curso corto (is_short_course) o posea autorización expresa de Bedelía (allow_same_day_exception).
  • Autenticación: Los flujos de acceso pasan por tokens JWT transportados en cookies seguras HttpOnly.

Límites

  • SIEMPRE: Lee docs/constitution.md y la especificación activa antes de proponer o modificar código.
  • PREGUNTA ANTES DE: Añadir nuevas dependencias a requirements.txt o package.json, alterar el esquema relacional de la base de datos o cambiar la estrategia de caché.
  • NUNCA: Expongas contraseñas, tokens de Moodle, secretos de API o el contenido del archivo .credenciales en el código fuente, commits o logs públicos.

Memoria

  • Al empezar, lee MEMORY.md para conocer el estado actual de la rama y los objetivos del sprint.
  • Al terminar cualquier tarea, actualízalo resumiendo las decisiones tomadas y los siguientes pasos.