# 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)**: ```powershell cd backend .\venv\Scripts\activate flask run --port 5000 ``` - **Levantar Frontend BFF (Express :3000)**: ```powershell cd frontend npm run dev ``` - **Ejecutar Suite de Pruebas Automatizadas (Backend)**: ```powershell cd backend .\venv\Scripts\activate pytest tests -v ``` - **Auditoría Automatizada de Seguridad (SAST / SCA / DAST)**: ```powershell .\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. - **Asignaturas Compartidas entre Carreras**: Una asignatura puede pertenecer a más de una carrera mediante la tabla asociativa relacional `subject_careers` (Many-to-Many), preservando `career_id` principal por compatibilidad. Las comisiones y asignaturas exponen todas las carreras asociadas en UI y filtros de búsqueda. - **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`. ## Metodología SDD (Spec-Driven Development) y Arnés de Agentes - **La especificación manda**: Ninguna feature se codifica sin su carpeta `specs/NNN-nombre/` conteniendo `spec.md` (requisitos en sintaxis **EARS** en español: Ubicuo, Eventos, Estado, No Deseado, Opcional), `plan.md` y `tasks.md` (skill `.agents/skills/sdd/SKILL.md`). - **Flujo de Roles**: - `Coordinator`: Conduce la interacción con el usuario y orquesta a los subagentes sin tocar código. - `Planner`: Redacta specs, planes y tareas atómicas (20-30 min) con criterios verificables "Hecho cuando:". - `Implementer`: Ejecuta tareas una a una con enfoque Test-First (`backend/tests/`). - `Reviewer`: Clarifica specs como QA y valida la implementación emitiendo veredicto formal (`VEREDICTO: APROBADO / CAMBIOS NECESARIOS`). ## Despliegue en Producción y Git Push (Innegociable por Principio 9) - Al completar cualquier tarea o hito verificado: 1. Incrementar versión semántica (`package.json`, `app.js`, `__init__.py`, `setup.py`, `openapi.py`). 2. Registrar cambios en `CHANGELOG.md` y `MEMORY.md`. 3. Ejecutar `git add .`, commit y **`git push origin dev`** al repositorio remoto. 4. Desplegar inmediatamente en producción al servidor institucional LXC (`10.0.0.217` / `https://eduspace.oemspot.com.ar`) utilizando los accesos del archivo `.credenciales`, reiniciando los servicios `admin-edu-space-backend` y `admin-edu-space-frontend`, y verificando HTTP 200 en `/version`. ## Límites - **SIEMPRE**: Lee `docs/constitution.md` y la especificación activa (`specs/`) antes de proponer o modificar código. - **SIEMPRE**: Al finalizar la tarea, realizar bump de versión, `git push origin dev` y despliegue a producción con `.credenciales` (Skill `.agents/skills/deploy/SKILL.md`). - **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.