96 lines
9.6 KiB
Markdown
96 lines
9.6 KiB
Markdown
# 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 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. |