Files
admin-edu-space/docs/constitution.md
T

9.9 KiB

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": "..."}).