9.6 KiB
9.6 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 (CacheServiceen 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.
- Google OAuth 2.0 para autenticación institucional restringida a
- 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 y Buenas Prácticas de APIs
- 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.
- Arquitectura Modular en 4 Capas (Separación Estricta de Responsabilidades):
main.py: Inicialización de la aplicación y registro de routers. No colocar lógica de negocio en el archivo principal ni en el frontend.routers/: Endpoints agrupados por dominio utilizandoAPIRouter(o Blueprints) con prefijos comunes (prefix="/products",prefix="/llm") y etiquetas (tags=["..."]) para una documentación limpia en Swagger UI.schemas/(schemas.py): Modelos de datos y validaciones conPydantic(BaseModel).storage.py(o capa de persistenciamodels/): Centralización del acceso a datos y base de datos.
- Validación de Datos con Pydantic y Tipado Fuerte:
- Heredar de
BaseModelpara el cuerpo (body) de las peticiones. - Uso mandatorio de
Fieldpara restricciones de negocio:min_length,max_length,gt=0,ge=0, etc. - Manejo de parámetros: Path Parameters obligatorios en la URL y Query Parameters opcionales con defaults tipados (
limit: int = 10). - Validación y captura automática: ante datos inválidos responder con código
422 Unprocessable Entitydetallando el atributo exacto y la falla.
- Heredar de
- Códigos de Estado HTTP y Manejo de Excepciones:
- Códigos de estado HTTP semánticos:
201 Createden POST exitosos,200 OKen lecturas/actualizaciones,204 No Contenten eliminaciones sin cuerpo. - Prohibido retornar
nullo respuestas vacías ante fallos lógicos: levantar siempre excepciones controladas (HTTPException) con código adecuado (ej.404 Not Foundcondetail="Recurso no encontrado",400 Bad Request,409 Conflict).
- Códigos de estado HTTP semánticos:
- Documentación Interactiva Automática:
- Contratos OpenAPI expuestos en
/docs(Swagger UI) listos para pruebas en vivo (Try it out) y visualización de esquemas.
- Contratos OpenAPI expuestos en
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), preservandocareer_idprincipal 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
CacheServicepara lecturas y encolar enMoodleSyncTaskpara 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. - Integración Asíncrona con Modelos de IA Locales (LLMs) y Asistente en la App:
- Pestaña en Configuración Global: Incluir una pestaña específica en la Configuración Global de la app para gestionar la integración con modelos de IA (servidor/URL, modelo seleccionado, tokens y timeout), sentando las bases para el futuro asistente virtual que guiará al usuario en la plataforma.
- Cliente HTTP Asíncrono no Bloqueante (
httpx): Toda llamada a servidores de inferencia locales (Ollama, llama.cpp, vLLM) o APIs de IA debe realizarse de forma asíncrona (httpx.AsyncClientconasync def/await) para no bloquear el hilo de ejecución principal ni degradar la concurrencia. - Timeouts Generosos: Fijar un tiempo de espera (
timeout) amplio (mínimo 600 segundos en entornos locales) previendo la carga de modelos en VRAM o inferencias de prompts extensos. - Estructura de Roles Estándar: Formatear el payload JSON enviando el modelo y los mensajes con roles explícitos (
role: "system" | "user" | "assistant",content: prompt).
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/conteniendospec.md(requisitos en sintaxis EARS en español: Ubicuo, Eventos, Estado, No Deseado, Opcional),plan.mdytasks.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:
- Incrementar versión semántica (
package.json,app.js,__init__.py,setup.py,openapi.py). - Registrar cambios en
CHANGELOG.mdyMEMORY.md. - Ejecutar
git add ., commit ygit push origin deval repositorio remoto. - 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 serviciosadmin-edu-space-backendyadmin-edu-space-frontend, y verificando HTTP 200 en/version.
- Incrementar versión semántica (
Límites
- SIEMPRE: Lee
docs/constitution.mdy la especificación activa (specs/) antes de proponer o modificar código. - SIEMPRE (Principio 10 - Tolerancia Cero): Repara activamente todos los problemas y errores reportados en la terminal / Language Server (
@[current_problems]). Es estrictamente inadmisible decir que una tarea está terminada o completada si hay errores o problemas en el código. - SIEMPRE (Principio 11 - Contratos Fuertes e IA): Implementar endpoints desacoplados en routers modulares, validar payloads con Pydantic
BaseModelyField, retornar códigos de estado HTTP semánticos (201, 204, 404, 422), exponer contratos en OpenAPI/docsy emplearhttpxasíncrono con timeouts generosos (600s) para integraciones con LLMs. - SIEMPRE: Al finalizar la tarea (con cero problemas en el código), realizar bump de versión,
git push origin devy despliegue a producción con.credenciales(Skill.agents/skills/deploy/SKILL.md). - PREGUNTA ANTES DE: Añadir nuevas dependencias a
requirements.txtopackage.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
.credencialesen el código fuente, commits o logs públicos.
Memoria
- Al empezar, lee
MEMORY.mdpara 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.