02 — Modelo de dominio
Enfoque: DDD soft — entidades, value objects y repositorios abstractos, sin sobre-ingeniería (no event sourcing, no agregados monumentales) mientras el lenguaje del dominio no esté validado con el colegio. Los términos de este documento son la propuesta de lenguaje ubicuo; se ajustan con el cliente.
⚠️ Las reglas normativas (umbrales de supletorio, escalas, estructura de períodos) cambian por acuerdo ministerial. Se modelan configurables y los valores por defecto se validan con el colegio contra la normativa vigente antes de producción.
Contextos y entidades
Institución y estructura académica
- Colegio (configuración): nombre, logo, colores, régimen (Costa/Sierra — configurable), timezone (Galápagos es UTC-6), datos AMIE/legales.
- AñoLectivo: ciclo de vida con estados:
planificación → matrícula → en_curso → cierre → cerrado. Nada se borra al cerrar; el modelo es multi-año desde el día 1. - PeríodoAcadémico: subdivisión configurable del año (trimestres o quimestres) con Parciales dentro. Cada período cierra individualmente (ver bloqueo de notas).
- Nivel/Grado: Inicial, EGB (Preparatoria, Elemental, Media, Superior — 1° a 10°) y BGU (1° a 3°). Configurable qué niveles ofrece el colegio.
- Paralelo: grupo dentro de un grado (p. ej. "8vo A"), con aula y tutor.
- Materia y AsignaciónDocente (docente ↔ materia ↔ paralelo ↔ año lectivo).
- Horario: bloques por paralelo/materia/docente/aula; validación de choques al guardar (mismo docente, misma aula o mismo paralelo en el mismo bloque).
Personas y cuentas
- Alumno: datos personales, cédula, ficha de matrícula ecuatoriana. Existe independientemente del año (su historia lo atraviesa).
- Representante: cuenta propia vinculada N:M con alumnos (un padre con tres hijos = una cuenta; un alumno puede tener varios representantes autorizados).
- Staff: admin, coordinación, secretaría, inspección, DECE, docente. Una persona puede tener varios roles.
- Cuentas: sin registro abierto. El colegio genera credenciales (usuario = cédula, contraseña temporal, cambio obligatorio al primer ingreso) al matricular o importar por Excel. Al aprovisionar Moodle se generan ambas credenciales juntas para entregarlas en un solo documento.
Matrícula
- Matrícula: alumno ↔ año lectivo ↔ grado ↔ paralelo, con estados (
inscrito, retirado, trasladado, promovido, no_promovido). Los traslados y retiros son transiciones con fecha y motivo, no borrados. - Importación masiva por Excel (plantilla oficial del sistema) con reporte de errores por fila; también importación de histórico básico (promedios finales por año/materia de años previos al sistema).
Evaluación
- Calificación: nota por alumno/materia/parcial. Escala 0–10, mínimo 7 para aprobar, con equivalencia cualitativa (DAR/AAR/PAR/NAR) — escala y umbrales configurables.
- Promedios: parcial → período → anual, con redondeo según normativa (configurable).
- Exámenes de recuperación: supletorio / remedial / de gracia como flujos propios posteriores al cierre del año, con umbrales configurables.
- Comportamiento: escala A–E por período (va en la boleta), separada de lo académico.
- Boleta: PDF por parcial/período con formato del colegio, generada en cola. Es un documento derivado — nunca fuente de verdad.
Bloqueo y auditoría (crítico)
- Al cerrar un parcial/período las notas y asistencia de ese rango se congelan. Corregir después exige una rectificación: flujo autorizado por coordinación que registra motivo, autorizador y valores anterior/nuevo.
- Audit log de todo cambio en notas, asistencia, matrícula y pagos: quién, cuándo, valor anterior, valor nuevo. Innegociable para que las actas sean defendibles ante padres y ministerio.
Asistencia
- Registro por bloque u día (configurable):
presente, atraso, falta_justificada, falta_injustificada. - Justificaciones con documento adjunto, gestionadas por inspección.
- Alertas de inasistencia al representante (push/email vía outbox).
Conducta y seguimiento
- Observación: por alumno, con categoría y visibilidad:
interna_docentes | visible_representante | solo_DECE. Las observaciones sensibles son exclusivas del DECE. - Citación a representante: registro de convocatoria, asistencia y acuerdos.
Pagos
- Rubro (matrícula, pensión mensual, otros) y Obligación por alumno con vencimiento.
- RegistroDePago manual (secretaría) con recibo; estado de cuenta por alumno y por representante (consolidado de sus hijos).
- Carga por Excel y API de integración para sistemas contables externos. Sin pasarela en MVP.
Comunicación
- Comunicado: del colegio o por paralelo/grado, con adjuntos; entrega vía app (push FCM) + email. Registro de envío por destinatario (vía outbox).
Matriz de roles (resumen)
| Capacidad | Admin | Coord. | Secretaría | Inspección | DECE | Docente | Representante/Alumno (app) |
|---|---|---|---|---|---|---|---|
| Configuración colegio/año | ✔ | ✔ | – | – | – | – | – |
| Estructura académica y horarios | ✔ | ✔ | – | – | – | – | consulta |
| Matrícula / Excel | ✔ | ✔ | ✔ | – | – | – | consulta |
| Asistencia | ✔ | ✔ | – | ✔ | – | ✔ (sus paralelos) | consulta |
| Notas | ✔ | ✔ | – | – | – | ✔ (sus materias) | consulta |
| Cierre de período / rectificaciones | ✔ | ✔ | – | – | – | solicita | – |
| Observaciones visibles / citaciones | ✔ | ✔ | – | ✔ | ✔ | ✔ | consulta (las visibles) |
| Observaciones sensibles | – | – | – | – | ✔ | – | – |
| Pagos | ✔ | – | ✔ | – | – | – | consulta |
| Comunicados | ✔ | ✔ | ✔ | ✔ | – | ✔ (sus paralelos) | consulta |
Identificadores
Toda entidad expone un UUID v7 como identificador público (APIs, logs, interconexión con Moodle y sistemas externos). Nunca se exponen ids secuenciales.