75 lines
9.9 KiB
Markdown
75 lines
9.9 KiB
Markdown
# Constitución de admin-edu-space
|
|
Principios innegociables y mandatorios del Software System Design (SSD). Toda especificación, diseño, plan y tarea del agente debe cumplirlos estrictamente sin excepción.
|
|
|
|
---
|
|
|
|
### 1. La Especificación y el SSD Mandan
|
|
Nada se implementa, refactoriza o modifica en la plataforma si no está documentado en la especificación activa o alineado con el Software System Design (SSD). Si se detecta un caso de uso no previsto o una ambigüedad en los requerimientos, se detiene la ejecución y se consulta al responsable del proyecto antes de avanzar.
|
|
|
|
### 2. Arquitectura Desacoplada (Backend RESTful + Frontend BFF)
|
|
El sistema opera bajo una arquitectura desacoplada de dos capas:
|
|
- **Backend Core API (Python / Flask + SQLAlchemy)**: Expone exclusivamente servicios RESTful bajo el prefijo `/api/v1/`, retornando respuestas JSON estructuradas con serializadores/DTOs. Gestiona la autenticación stateless mediante tokens JWT (HS256), la integridad referencial en base de datos y el pipeline de blindaje `SecurityFilterChain`.
|
|
- **Frontend BFF (Node.js / Express + Nunjucks)**: Orquesta la presentación y la experiencia de usuario (UX), mantiene la sesión mediante cookies seguras `HttpOnly`, inyecta encabezados de autorización Bearer en llamadas Axios hacia el backend y adapta las vistas según el rol del usuario autenticado.
|
|
|
|
### 3. Reemplazo Definitivo del Excel como Herramienta Operativa
|
|
El objetivo primordial del sistema es erradicar el uso del archivo Excel/planilla como herramienta de gestión cotidiana de Bedelía, convirtiendo a la plataforma en la **única fuente de verdad** (Single Source of Truth) para la administración de espacios, comisiones y cursadas a través del ciclo estructurado de 9 pasos (Sedes -> Aulas -> Ciclos Lectivos -> Carreras -> Asignaturas -> Comisiones -> Profesores -> Alumnos -> Reservas). Toda asignatura debe pertenecer a su carrera y toda comisión hereda y expone esta pertenencia institucional para filtros y reportes académicos.
|
|
- La importación desde Google Sheets / planillas externas se mantiene exclusivamente como mecanismo de **ingesta masiva inicial y compatibilidad**, mientras que todas las altas, modificaciones, cancelaciones y reubicaciones deben realizarse directamente en la plataforma.
|
|
|
|
### 4. Matriz Infranqueable de Conflictos Académicos y Espaciales
|
|
La asignación de reservas de aulas debe validar en tiempo real e impedir de forma determinística:
|
|
1. **Conflicto Físico**: Doble asignación horaria en una misma aula presencial para el mismo día y bloque horario.
|
|
2. **Conflicto de Aforo**: Asignación de una comisión cuyo cupo estimado supere la capacidad física del aula.
|
|
3. **Conflicto Docente**: Superposición horaria de un profesor en múltiples espacios simultáneos, permitiendo excepción **únicamente** cuando la comisión cuenta con co-docencia activa registrada en `CommissionTeacher`.
|
|
4. **Restricción Diaria del Alumno**: Bloqueo de cursada de dos asignaturas regulares en el mismo día de la semana, exceptuando talleres/cursos cortos (`is_short_course`) o autorización expresa y justificada de Bedelía (`allow_same_day_exception`).
|
|
|
|
### 5. Caché First y Resiliencia en Servicios Externos (Moodle 4.1 & SMTP)
|
|
- Toda consulta de datos o perfiles provenientes de Moodle 4.1 debe consultar en primer término la capa de caché (`CacheService` en Redis o memoria).
|
|
- Toda operación de sincronización hacia Moodle debe encolarse de forma asíncrona no bloqueante (`MoodleSyncTask`) utilizando reintentos exponenciales (*Exponential Backoff*) y derivación a Dead Letter Queue (DLQ) ante indisponibilidad.
|
|
- Prohibidas las peticiones síncronas bloqueantes a servicios externos dentro de las transacciones de los controladores web.
|
|
- El servicio de correo transaccional (`EmailService`) debe utilizar credenciales dinámicas descifradas con Fernet sin impactar los tiempos de respuesta.
|
|
|
|
### 6. Privacidad Estricta, Blindaje RBAC y Trazabilidad
|
|
- Los datos de alumnos, docentes y credenciales de acceso son de máxima confidencialidad. Ningún endpoint debe exponer contraseñas, secretos o información privada a roles no autorizados.
|
|
- La autenticación institucional de Google Workspace debe validar estrictamente los dominios institucionales autorizados (`@unicaba.edu.ar`).
|
|
- Toda acción sensible (reseteo de sistema, impersonación de usuarios, reapertura/cierre de actas de notas) debe quedar registrada de forma inmutable en la tabla de auditoría (`AuditLog`).
|
|
|
|
### 7. Convenciones de Código e Idioma
|
|
- **Código Fuente**: Nombres de variables, clases, métodos, commits y pruebas en **inglés**.
|
|
- **Interfaz y Documentación**: Vistas, mensajes de error, respuestas al usuario, correos electrónicos y documentación operativa en **español**.
|
|
|
|
### 8. Testing Automatizado como Puerta de Enlace (Quality Gate)
|
|
- La suite de pruebas automatizadas (`pytest backend/tests`) y los controles de seguridad SAST/DAST/SCA (`security_audit.bat`) son mandatorios.
|
|
- Queda terminantemente prohibido cerrar una tarea o fusionar cambios a la rama de integración con pruebas fallando o vulnerabilidades críticas no remediadas.
|
|
|
|
### 9. Control de Versiones, Git Push y Despliegue Obligatorio a Servidor
|
|
- **Control de Versión al Compilar**: Siempre actualizar y guardar el control de la nueva versión semántica de forma estricta e ineludible al momento de compilar, empaquetar o consolidar una nueva entrega (actualizando `package.json`, `app.js`, `__init__.py`, `setup.py`, `openapi.py` y `CHANGELOG.md`).
|
|
- **Git Push Obligatorio**: Ejecutar siempre `git push origin dev` al repositorio remoto una vez que los tests automatizados (`pytest tests -v`) estén 100% aprobados.
|
|
- **Subida y Despliegue Inmediato al Servidor de Producción**: Al finalizar la compilación o empaquetado, **siempre** subir y desplegar la nueva versión al servidor institucional de producción (`10.0.0.217` / `https://eduspace.oemspot.com.ar`) utilizando los accesos y claves definidos en el archivo `.credenciales`, reiniciando los servicios del sistema (`systemctl restart admin-edu-space-backend admin-edu-space-frontend`) y verificando el estado operativo en vivo (HTTP 200 en `/version`) antes de dar cualquier tarea por concluida.
|
|
|
|
### 10. Tolerancia Cero a Errores de Código y Diagnóstico (`@[current_problems]`)
|
|
- **Prohibición de Cierre con Errores**: Es estrictamente inadmisible declarar una tarea, plan o sprint como "terminado", "completado" o "finalizado" si existen errores en el código, advertencias críticas de tipado, o problemas reportados por el analizador estático / terminal (`@[current_problems]`).
|
|
- **Remediación Mandatoria Previa**: Toda tarea se considera incompleta por definición hasta que el agente verifique activamente y repare al 100% todos los errores de sintaxis, imports, resolución de módulos, estrechamiento de tipos (type narrowing) y accesos a `NoneType`.
|
|
- **Quality Gate Infranqueable**: Ningún commit, bump de versión o despliegue a producción puede ser ejecutado mientras existan problemas o errores no resueltos en `@[current_problems]`.
|
|
|
|
### 11. Estándares Modernos de APIs, Contratos Fuertes (FastAPI / Pydantic) e Integración con Modelos de IA (LLMs)
|
|
- **Arquitectura Modular y Separación de Responsabilidades**:
|
|
- Prohibido el código monolítico o ubicar lógica de negocio en el frontend o en archivos únicos de arranque.
|
|
- Estructuración estricta en 4 capas desacopladas:
|
|
1. **Entrada / Bootstrap (`main.py`)**: Inicialización de la aplicación y registro de routers.
|
|
2. **Rutas y Controladores (`routers/`)**: Agrupación de endpoints por dominio con prefijos (`prefix="/..."`) y etiquetas (`tags=["..."]`) para OpenAPI/Swagger limpio.
|
|
3. **Contratos y Validación (`schemas/` o `schemas.py`)**: Definición de esquemas de datos de entrada/salida mediante `pydantic.BaseModel`.
|
|
4. **Capa de Persistencia / Almacenamiento (`storage.py` / `models/`)**: Conexión a bases de datos y persistencia desacoplada.
|
|
- **Tipado Fuerte y Contratos con Pydantic**:
|
|
- Toda entrada (Body) debe heredar de `BaseModel` con validaciones explícitas usando `Field` (`min_length`, `max_length`, `gt`, `ge`, regex).
|
|
- Manejo diferenciado de parámetros: Path Parameters (obligatorios en la URL) y Query Parameters (opcionales con valores tipados por defecto).
|
|
- Manejo de errores de validación automático (422 Unprocessable Entity con detalle preciso del atributo).
|
|
- **Semántica HTTP y Excepciones Controladas**:
|
|
- Uso estricto de códigos HTTP: `201 Created` para creación vía POST, `200 OK` para consultas/actualizaciones, `204 No Content` para borrados sin cuerpo.
|
|
- Prohibido retornar valores nulos (`null`) o respuestas vacías ante fallos lógicos: siempre levantar excepciones controladas (`HTTPException`) con código de estado semántico (ej. `404 Not Found` con `detail="Recurso no encontrado"`, `400 Bad Request`, `409 Conflict`).
|
|
- **Documentación Interactiva Automática**:
|
|
- Los contratos de API deben exponerse de forma nativa vía Swagger UI (`/docs`), permitiendo pruebas interactivas en vivo (*Try it out*) y visualización de esquemas.
|
|
- **Integración Asíncrona con Modelos de Lenguaje (LLMs) y Asistente en la App**:
|
|
- **Pestaña en Configuración Global**: La aplicación debe disponer en su configuración global de una pestaña dedicada a la configuración del Asistente de IA (URL del proveedor/servidor local, modelo, timeout, token y activación).
|
|
- **Cliente HTTP Asíncrono no Bloqueante**: Utilizar exclusivamente clientes asíncronos (`httpx.AsyncClient` con `async def` y `await`) para conectar con motores de inferencia locales (Ollama, llama.cpp, vLLM) o externos sin bloquear el bucle de eventos ni los hilos del servidor.
|
|
- **Configuración de Timeouts Generosos**: Configurar tiempos de espera adecuados para LLMs (ej. timeout por defecto de 600 segundos para dar soporte a inferencias locales en GPU/VRAM compartida).
|
|
- **Formato Estándar de Roles**: Toda comunicación con modelos de lenguaje debe emplear el estándar de historial estructurado por roles (`{"role": "system" | "user" | "assistant", "content": "..."}`). |