Sistema Académico — Manual completo
Sistema de gestión académica para colegios de Ecuador: matrícula, asistencia, calificaciones oficiales, conducta, pagos, comunicados y horarios, con integración a Moodle como aula virtual.
Todo lo que ve en este manual es real
Cada captura y cada respuesta de API de este manual proviene del sistema en funcionamiento, ejecutado desde una base de datos vacía — sin datos de prueba precargados. La simulación crea al colegio completo desde el primer ingreso del administrador: personal, estructura, matrículas, notas, pagos y comunicados, con cada rol haciendo su trabajo por la interfaz.
Cómo está organizado
| Sección | Qué contiene |
|---|---|
| Recorrido completo | La puesta en marcha de un colegio desde cero, paso a paso, con cada rol |
| Casos de uso | Cada funcionalidad explicada para familias, docentes y coordinación — con su camino feliz y sus errores esperados |
| Errores y validaciones | Catálogo completo de lo que el sistema impide hacer, con evidencia |
| Sección técnica | Arquitectura, logs con trazabilidad, auditoría LOPDP y colas de integración |
Los roles del sistema
| Rol | Qué hace | Dónde |
|---|---|---|
| Administración | Configuración, personal, integraciones, auditoría | Panel web |
| Coordinación | Años lectivos, estructura, horarios, cierres, rectificaciones | Panel web |
| Secretaría | Matrícula (individual y Excel), pagos y cobros | Panel web |
| Inspección | Asistencia y justificación de faltas | Panel web |
| DECE | Observaciones sensibles de consejería estudiantil | Panel web |
| Docente | Asistencia, calificaciones, observaciones | Panel web |
| Representante | Consulta del progreso de todos sus hijos con una sola cuenta | App de consulta (API) |
| Estudiante | Consulta de su propio progreso | App de consulta (API) |
Reglas de oro del sistema
- Sin registro abierto: todas las cuentas las crea el colegio; usuario = cédula, contraseña temporal con cambio obligatorio al primer ingreso.
- Un solo año lectivo activo a la vez; los períodos y parciales se cierran en orden.
- El cierre de parcial congela las notas: después solo se corrige por rectificación autorizada por coordinación, y todo queda auditado.
- La importación por Excel es todo-o-nada: una fila mala y no entra nada.
- Los efectos críticos (notificaciones, Moodle, boletas) nunca se pierden: viajan por una cola transaccional con reintentos.
- Los datos de menores están protegidos (LOPDP): accesos auditados, logs enmascarados, y cada rol ve solo lo que le corresponde.
Cómo levantar el sistema
cd backend && docker compose up -d --build # nginx :8080 → bff → core → postgres
Con la base vacía, el sistema crea el usuario admin (clave inicial:
BOOTSTRAP_ADMIN_PASSWORD de backend/.env) que debe cambiarla al entrar.
Para reproducir este manual completo:
cd backend && ./scripts/reset-db.sh # BD vacía + admin de bootstrap
cd ../frontend && JOURNEY=1 E2E_BASE_URL=http://localhost:8080 \
npx playwright test journey sad-paths --workers=1 # 26 pasos automatizados