5.7 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 blindajeSecurityFilterChain. - 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:
- Conflicto Físico: Doble asignación horaria en una misma aula presencial para el mismo día y bloque horario.
- Conflicto de Aforo: Asignación de una comisión cuyo cupo estimado supere la capacidad física del aula.
- 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. - 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é (
CacheServiceen 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 en Compilación 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__.pyyCHANGELOG.md). - Subida Inmediata y Obligatoria al Servidor: 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/eduspace.oemspot.com.ar), reiniciando los servicios y verificando el estado operativo en vivo antes de dar cualquier tarea por concluida.