Files
admin-edu-space/AGENTS.md
T

9.8 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/3.14, FastAPI 0.115+ (100% Nativo ASGI puro con Uvicorn, routers modulares y OpenAPI /docs), SQLAlchemy ORM 2.0, PostgreSQL 15 / SQLite, Pydantic v2 DTOs (BaseModel), PyJWT (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), capa de caché híbrida (CacheService en Redis / memoria) y resolución transparente de IDs de usuario en update_users.
    • 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 (FastAPI / ASGI :5000):
    cd backend
    .\venv\Scripts\activate
    uvicorn main:app --host 0.0.0.0 --port 5000 --reload
    
  • 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 utilizando APIRouter (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 con Pydantic (BaseModel).
    • storage.py (o capa de persistencia models/): Centralización del acceso a datos y base de datos.
  • Validación de Datos con Pydantic y Tipado Fuerte:
    • Heredar de BaseModel para el cuerpo (body) de las peticiones.
    • Uso mandatorio de Field para 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 Entity detallando el atributo exacto y la falla.
  • Códigos de Estado HTTP y Manejo de Excepciones:
    • Códigos de estado HTTP semánticos: 201 Created en POST exitosos, 200 OK en lecturas/actualizaciones, 204 No Content en eliminaciones sin cuerpo.
    • Prohibido retornar null o respuestas vacías ante fallos lógicos: levantar siempre excepciones controladas (HTTPException) con código adecuado (ej. 404 Not Found con detail="Recurso no encontrado", 400 Bad Request, 409 Conflict).
  • 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.

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.
  • 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.AsyncClient con async 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/ 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 (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 BaseModel y Field, retornar códigos de estado HTTP semánticos (201, 204, 404, 422), exponer contratos en OpenAPI /docs y emplear httpx así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 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.