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

52 lines
6.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]`.