# 00 — Hallazgos, contradicciones y decisiones pendientes > Este es el documento más importante de la propuesta. Antes de proponer arquitectura, el equipo analizó la > especificación completa buscando contradicciones internas, ambigüedades que cambian el diseño de base de datos, > y riesgos legales o de seguridad. Se encontraron **9 bloqueantes**, **14 ambigüedades relevantes** y > **7 riesgos técnicos o legales**. > > Ninguno de estos puntos se resolvió inventando un requisito. Cada uno tiene: *qué dice la especificación*, > *por qué importa*, y *qué recomienda el equipo*. --- # Parte 1 — Bloqueantes (requieren decisión del cliente) ## DP-01 · El padre y el estudiante no ven notas, pero sí ven "promedio general" y "puesto" **Qué dice la especificación.** §9 y §10: el acudiente y el estudiante **NO** pueden consultar notas individuales ni boletines. §41: su dashboard **SÍ** puede mostrar "promedio general", "puesto general si se determina conveniente", y una gráfica de evolución del rendimiento por periodo. **Por qué importa.** El promedio general es una función matemática directa de las notas. Si el sistema muestra `3.87` como promedio del periodo y el estudiante cursa 8 asignaturas, con el promedio de dos periodos consecutivos y un poco de aritmética es posible acotar fuertemente las notas individuales. Es decir: la regla "no mostrar notas" queda parcialmente anulada por la regla "mostrar promedio numérico". No es un problema de programación — es un problema de definición de producto: **hay dos reglas que se contradicen y hay que elegir el nivel real de opacidad deseado.** Adicionalmente, mostrar **el puesto** expone información comparativa del estudiante frente al grupo, lo cual es una decisión pedagógica del colegio, no técnica. **Recomendación del equipo [RT].** Definir el indicador visible como **cualitativo y en bandas**, no numérico: | Lo que se muestra | Lo que NO se muestra | |---|---| | Nivel de desempeño global del periodo (Superior / Alto / Básico / Bajo) | El número `3.87` | | Tendencia entre periodos (mejora / estable / desciende) | La nota de cada asignatura | | Gráfica de evolución con eje Y **etiquetado por nivel**, no por número | El eje Y con la escala 0.0–5.0 | | Semáforo por área (verde / amarillo / rojo), si el colegio lo aprueba | El detalle de la asignatura que causa el rojo | Y hacer que esto sea **parametrizable por el colegio** mediante tres interruptores en Configuración: `mostrar_promedio_numerico_a_familias` (por defecto **NO**), `mostrar_puesto_a_familias` (por defecto **NO**), `granularidad_indicador` (global / por área / por asignatura). Así el sistema cumple literalmente el requisito ("no ver notas") sin contradecirse, y el colegio decide después cuánto abrir sin necesidad de reprogramar. **Decisión requerida:** ¿indicador cualitativo en bandas (recomendado) o promedio numérico visible? --- ## DP-02 · Si la familia no ve el boletín en el sistema, ¿cómo lo recibe? **Qué dice la especificación.** §9 y §41: el acudiente **no puede consultar boletines**. §42: el sistema genera boletines PDF individuales y por curso. **Por qué importa.** En Colombia, el Decreto 1290 de 2009 (art. 11) establece como responsabilidad de la institución **entregar a los padres de familia informes periódicos de evaluación**. El sistema, tal como está especificado, genera el boletín pero **no tiene canal de entrega a la familia**: el acudiente no lo ve en línea, y no hay módulo de correo en esta versión (§59). El único camino que queda es la impresión física y la entrega presencial en reunión de padres. Eso puede ser exactamente lo que el colegio quiere (es la práctica tradicional). Pero si no lo es, se detectaría tarde — en la primera entrega de boletines del año — y obligaría a abrir un módulo nuevo a mitad de operación. **Recomendación del equipo [RT].** Mantener el requisito tal cual (la familia no ve boletines en línea) y **preparar** —sin construir— dos salidas alternativas: 1. **Impresión masiva por curso** con un único PDF paginado listo para imprimir y firmar. *(sí se construye, ya está en §42)* 2. **Entrega controlada por enlace temporal [FF]:** el coordinador genera un enlace de un solo uso con vencimiento para un boletín específico. La arquitectura deja el punto de extensión; no se implementa en v1. **Decisión requerida:** confirmar que la entrega del boletín a la familia es **100 % física / presencial** en la v1. --- ## DP-03 · ¿Una sola nota por asignatura y periodo, o notas parciales? **Qué dice la especificación.** §28: "Cada estudiante tendrá **una nota** por asignatura + periodo". §29 describe digitación rápida de un valor por estudiante. **Por qué importa.** Este es probablemente **el supuesto con mayor impacto de todo el sistema**. Un colegio que califica por actividades (talleres 30 %, evaluaciones 40 %, actitudinal 30 %) necesita registrar componentes y que el sistema calcule la nota del periodo. La especificación describe lo contrario: el docente **calcula por fuera** (en su propio cuaderno o Excel) y **digita el resultado final**. Ambos modelos son válidos y muy usados. Pero son **estructuralmente distintos**: cambiar de uno a otro después implica rehacer el módulo de notas, la digitación rápida, el boletín y los reportes. **Recomendación del equipo [RT].** Construir la v1 exactamente como está especificado (una nota definitiva por asignatura + periodo, digitada por el docente), pero **diseñar la entidad de notas desde ahora con la puerta abierta**: la nota del periodo vive en su propia entidad y se reserva —sin usar— la relación hacia una futura entidad `actividad_evaluativa`. Si el colegio adopta ponderación en 2027, se agrega la entidad nueva y se recalcula, sin migrar notas históricas ni tocar boletines. **Decisión requerida:** confirmar que en v1 el docente digita **una única nota final** por asignatura y periodo. --- ## DP-04 · Regla de la nota definitiva después de una recuperación **Qué dice la especificación.** §30 da un ejemplo: original 2.5 → recuperación 3.8 → definitiva 3.8. **Por qué importa.** El ejemplo muestra un caso donde la recuperación sube la nota, pero no define la regla general. Hay tres políticas usadas en Colombia y **producen resultados distintos**: | Política | Original 2.5, recuperación 3.8 | Original 2.5, recuperación 2.0 | |---|---|---| | **A. Reemplazo puro** | 3.8 | **2.0** (la recuperación empeoró la nota) | | **B. Máximo entre ambas** | 3.8 | 2.5 | | **C. Máximo con tope** (tope 3.0) | **3.0** | 2.5 | La política C es muy común: "aunque recupere con 5.0, la definitiva no pasa de 3.0" (la mínima aprobatoria). Con la política A, un estudiante que presenta la recuperación y le va peor **queda con peor nota que si no la hubiera presentado**, lo cual genera reclamos formales de los acudientes. **Recomendación del equipo [RT].** Implementarlo como **parámetro configurable del colegio**, con valor por defecto **B (máximo entre nota original y recuperación)** y campo opcional `tope_recuperacion` (vacío = sin tope). Las tres políticas quedan cubiertas con un solo desarrollo. **Decisión requerida:** política por defecto y si aplica tope. **Ambigüedad asociada [DP]:** la especificación no menciona **recuperaciones de fin de año / nivelaciones finales** (distintas de las de periodo). ¿Existen? Si existen, requieren su propia entidad y afectan la promoción. --- ## DP-05 · ¿El boletín se organiza por Área o por Asignatura? **Qué dice la especificación.** §16 establece la jerarquía Área → Asignatura. §43 muestra el histórico del boletín con filas de **asignatura** (Matemáticas). §54 pide reportes de "desempeños por asignatura". No se menciona en ningún punto una **nota de área**. **Por qué importa.** El boletín colombiano típico agrupa asignaturas dentro de su área y muestra **una nota de área** además de las notas de asignatura. Si se requiere nota de área hay que definir cómo se calcula: media simple de las asignaturas del área, o media ponderada por **intensidad horaria** — un concepto que la especificación **nunca menciona** y que no existe en el modelo propuesto. **Recomendación del equipo [RT].** v1: **el boletín reporta por asignatura, agrupadas visualmente bajo el título de su área, sin nota de área**. Se añade el campo `intensidad_horaria` (opcional, informativo) a la asignatura por curso, para no tener que alterar la estructura si el colegio decide después ponderar. **Decisión requerida:** ¿se requiere nota de área en el boletín de la v1? --- ## DP-06 · Criterio de promoción / reprobación **Qué dice la especificación.** §24 define los estados "Promovido" y "No promovido". §26 describe el proceso de promoción con selección masiva o individual. **No define en ningún punto la regla que determina si un estudiante aprueba el año.** **Por qué importa.** El Decreto 1290 de 2009 delega el criterio de promoción al **SIEE (Sistema Institucional de Evaluación de los Estudiantes)** de cada colegio. Es decir: **no existe una regla nacional que el sistema pueda asumir**. Ejemplos reales de criterios distintos entre colegios: - Reprueba con **1 o más** áreas en Bajo. - Reprueba con **3 o más** asignaturas en Bajo. - Reprueba con **2 áreas** en Bajo **o** promedio general inferior a 3.0. - Promoción anticipada, comisión de evaluación, casos especiales. **Recomendación del equipo [RT].** El sistema **no decide automáticamente** la promoción en la v1. En su lugar: - Calcula y **muestra los insumos**: asignaturas/áreas en Bajo, promedio acumulado anual, nivel de desempeño final. - **Sugiere** un estado usando una regla configurable simple (`maximo_asignaturas_en_bajo`, por defecto 2). - La decisión final es **siempre humana** (Coordinador/Superadmin) y queda auditada con el usuario que la tomó. Esto respeta el hecho de que la promoción es una decisión de la comisión de evaluación, no del software. **Decisión requerida:** ¿el colegio entrega su regla SIEE para configurarla, o prefiere decisión 100 % manual? --- ## DP-07 · Los desempeños del boletín: ¿iguales para todo el curso, o marcados por estudiante? **Qué dice la especificación.** §27: los desempeños pertenecen a **asignatura + curso + periodo**, y "**no son registros individuales por estudiante**". §42: el boletín del estudiante incluye "Desempeños/logros". **Por qué importa.** Con la definición de §27, **todos los estudiantes de 6°A tendrán exactamente el mismo texto de logros en su boletín de Matemáticas** — el boletín deja de ser individualizado en esa sección. Es una decisión válida y reduce muchísimo el trabajo del docente (que es un objetivo explícito, §62). Pero es distinta de lo que muchos colegios esperan: marcar cuáles logros alcanzó cada estudiante. **Recomendación del equipo [RT].** Respetar §27 literalmente en la v1 (logros a nivel de grupo) y dejar **preparada** la relación estudiante–desempeño con estado (alcanzado / en proceso / no alcanzado) como [FF]. El boletín se diseña de modo que esa columna pueda aparecer después sin rediseñar la plantilla. **Decisión requerida:** confirmar que los logros del boletín son **idénticos para todo el curso** en la v1. --- ## DP-08 · La política de contraseñas tiene un riesgo de seguridad real **Qué dice la especificación.** §11: contraseña inicial = primer nombre capitalizado + `@` + 4 dígitos aleatorios (ej. `Juan@4832`). §9 y §11: el estudiante y el acudiente **NO pueden cambiar su contraseña**; solo Superadmin y Coordinador pueden restablecerla. §10: el usuario es el número de documento y no es modificable. **Por qué importa.** Tres problemas concretos, en orden de gravedad: 1. **Espacio de búsqueda diminuto.** El primer nombre de un estudiante es información pública dentro del colegio. Quien lo conoce solo debe adivinar 4 dígitos: **10 000 combinaciones**. Sin bloqueo de intentos, un script las agota en segundos. Con esa contraseña se accede al dashboard del estudiante — y en el caso del acudiente, a la información de todos sus hijos. 2. **La contraseña nunca cambia.** Como el usuario no puede cambiarla, una credencial comprometida sigue comprometida durante todo el año escolar, hasta que alguien lo note y pida un restablecimiento manual. 3. **Carga operativa.** Cada olvido de contraseña de cualquiera de cientos de acudientes se convierte en una tarea manual de la coordinación. **Recomendación del equipo [RT].** Mantener el **formato** de contraseña inicial solicitado (es cómodo de dictar en la matrícula) y compensar con controles que **no contradicen** el requisito: | Control | Efecto | |---|---| | **Bloqueo progresivo:** 5 intentos fallidos → 15 min de bloqueo; contador por usuario **y** por IP | Convierte 10 000 intentos en semanas de trabajo. Neutraliza el problema 1. | | **Contraseña mostrada una sola vez** al generarla; nunca visible en listados ni exportaciones | Evita la filtración masiva por un Excel compartido | | **Interruptor de configuración** `permitir_cambio_password_familias` (por defecto **desactivado**, como pide §11) | El colegio puede activarlo sin desarrollo nuevo cuando quiera resolver el problema 2 | | **Bitácora de accesos** (último ingreso, IP, intentos fallidos) visible al Coordinador | Permite detectar cuentas comprometidas | | Aumentar el sufijo de **4 a 6 dígitos** *(opcional; cambia el ejemplo de §11)* | 100× más resistente, mismo formato | **Decisión requerida:** aprobar el bloqueo progresivo (recomendado sin reservas desde el punto de vista de seguridad) y decidir si el sufijo aleatorio pasa de 4 a 6 dígitos. --- ## DP-09 · El modelo confunde "Grado" con "Curso" — y eso rompe la promoción **Qué dice la especificación.** §17: los cursos son "1°A, 1°B, 6°A, 6°B, 11°A" y están ligados a un año académico. §26: la promoción debe mostrar "curso actual → **curso sugerido** → curso destino" (2026 5°A → 2027 6°A). **Por qué importa.** Para que el sistema pueda **sugerir** que 5°A pasa a 6°A, necesita saber que *5* y *6* son grados consecutivos. Si "5°A" es solo una cadena de texto en la tabla de cursos, el sistema no puede deducir nada: la sugerencia automática de §26 — que es el corazón del ahorro operativo — **no se puede construir**. Lo mismo aplica a: ordenar cursos en los reportes (11°A debe ir después de 2°A, no antes alfabéticamente), saber qué asignaturas corresponden a primaria vs. bachillerato, y agrupar por nivel (preescolar / primaria / secundaria / media) en los reportes institucionales. **Recomendación del equipo [RT].** Separar dos conceptos que hoy están fundidos: | Concepto | Qué es | Ejemplos | Vive en | |---|---|---|---| | **Grado** | El nivel académico. Catálogo estable, no cambia año a año. | Transición, 1°, 2°, … 11° | Catálogo institucional, con `orden` numérico y `nivel` | | **Curso (grupo)** | Una instancia concreta de un grado, en un año y jornada. | 6°A 2026 mañana | Ligado a año académico | Con esto, la sugerencia de promoción es trivial: *grado siguiente por `orden`, misma letra de grupo si existe*. Y el cierre del ciclo (11° → Graduado) se maneja marcando el grado como terminal. **Decisión requerida:** aprobar la separación Grado / Curso. **Es la decisión de modelo de datos más costosa de revertir** si se posterga. --- # Parte 2 — Ambigüedades relevantes (no bloquean, pero deben resolverse en su fase) ## AMB-01 · ¿Qué pasa con las notas cuando un estudiante se traslada de curso? §25 exige poder trasladar a un estudiante de 6°A a 6°B durante el mismo año, conservando el histórico. Si la nota estuviera anclada al curso, el traslado dejaría las notas del periodo 1 "colgadas" en 6°A. **Propuesta [RT]:** la nota se ancla a **estudiante + año + asignatura + periodo**, con el curso guardado como *dato de contexto* (fotografía para reportes), no como parte de la llave. Así el traslado **conserva automáticamente** todas las notas ya digitadas. Caso borde a resolver: si 6°B tiene una asignatura que 6°A no tenía, el estudiante queda sin nota de periodo 1 en esa asignatura — el sistema lo reporta como pendiente y el coordinador decide (ver [06 — Reglas de negocio](06-reglas-de-negocio.md), RN-TRA-03). ## AMB-02 · La escala de desempeño tiene huecos numéricos §35 propone: 4.6–5.0 Superior · 4.0–4.5 Alto · 3.0–3.9 Básico · 0.0–2.9 Bajo. Con un decimal es continua. Pero §34 exige calcular con **precisión real** (ej. 4.126), y un promedio de **3.95** o **4.55** **no cae en ninguna banda**. **Propuesta [RT]:** almacenar las bandas como intervalos semiabiertos `[min, max)` y validar en el formulario de configuración que **cubran 0.00 a 5.00 sin huecos ni solapamientos**. Con los valores del ejemplo: Bajo `[0.00, 3.00)`, Básico `[3.00, 4.00)`, Alto `[4.00, 4.60)`, Superior `[4.60, 5.01)`. La interfaz sigue mostrando "4.6 – 5.0" al usuario; el rigor está por dentro. ## AMB-03 · "Promedio general acumulado" tiene dos lecturas distintas §33 pide el promedio general acumulado "calculado con los promedios académicos disponibles". Hay dos formas: - **(a)** Promediar todas las notas de todos los periodos de todas las asignaturas. - **(b)** Calcular primero el promedio acumulado de **cada asignatura**, y luego promediar esos valores. Dan **resultados distintos** cuando alguna asignatura tiene menos periodos calificados que las demás — precisamente el caso que §32 dice que debe contemplarse. **Propuesta [RT]:** usar **(b)**, porque es la única coherente con "todas las asignaturas tienen el mismo peso" (§32). Con (a), una asignatura con 4 notas pesaría el doble que una con 2. ## AMB-04 · Reglas de empate en el puesto §34 exige precisión real para evitar empates artificiales, pero no define qué hacer con los empates **reales** (dos estudiantes con exactamente 4.1250). **Propuesta [RT]:** ranking competitivo estándar — mismo puesto para empatados y el siguiente puesto salta (1, 2, 2, 4). Orden de desempate solo para presentación en listados (no altera el puesto): apellidos, nombres. El puesto se calcula **dentro del curso**; puesto por grado o por colegio queda como [FF]. ## AMB-05 · ¿El cierre de periodo bloquea las tareas? §14 menciona que el docente no podrá "modificar tareas que estén restringidas por cierre, **según la regla definida**" — pero la regla nunca se define. **Propuesta [RT]:** el cierre de periodo bloquea **únicamente el registro académico** (notas, recuperaciones, desempeños, observaciones de boletín). Las tareas y los comunicados **no se bloquean**, porque no forman parte del registro evaluativo y bloquearlas impediría corregir un error de redacción en una tarea ya publicada. ## AMB-06 · ¿Quién escribe la observación del boletín? §45 dice "el docente autorizado". §40 lista "observaciones pendientes" en el dashboard del docente. No queda claro si es una observación **general por estudiante** (típicamente del director de curso) o **una por asignatura**. **Propuesta [RT]:** dos niveles, ambos opcionales: **(1)** observación general del periodo — la escribe el **director de curso**; **(2)** observación por asignatura — la escribe el **docente titular** de esa asignatura. El boletín imprime la general siempre, y las de asignatura solo si existen. ## AMB-07 · Validación de celular colombiano vs. acudientes extranjeros §52 exige aceptar únicamente 10 dígitos que empiecen por 3. Es correcto para móviles colombianos, pero §21 exige soportar **estudiantes extranjeros**, cuyos acudientes pueden tener número extranjero. **Propuesta [RT]:** validación estricta "10 dígitos iniciando en 3" **por defecto**, con una casilla "número internacional" que relaja la validación a formato E.164 y exige indicativo de país. No se bloquea la matrícula de una familia migrante por una validación pensada para el caso nacional. ## AMB-08 · El documento es el usuario, pero los documentos cambian §10, §19, §22: el nombre de usuario es el número de documento y **no es modificable**. En la práctica los documentos **sí cambian**: al cumplir 18 años se pasa de TI a CC, un PPT se convierte en cédula de extranjería, y en la matrícula se digitan documentos con errores de tipeo que hay que corregir. **Propuesta [RT]:** el usuario **no puede** cambiar su propio nombre de usuario (que es lo que pide §10), pero el Superadmin **sí** puede corregirlo desde la administración, con motivo obligatorio, auditoría del valor anterior y conservación del histórico de identificadores. Internamente, **todas** las relaciones usan un identificador inmutable, nunca el número de documento — de modo que corregir un documento no rompe matrículas ni notas. ## AMB-09 · Una misma persona con varios roles Un docente puede ser también acudiente de un estudiante del colegio. Con "usuario = documento", esa persona necesitaría dos cuentas con el mismo nombre de usuario, lo cual es imposible. **Propuesta [RT]:** separar **Persona** (los datos de un ser humano, única por tipo+número de documento) de **Usuario** (una credencial) y de **Rol** (varios por usuario). Una persona = un usuario = uno o varios roles, con un selector de contexto si tiene más de uno. Ver [05 — Modelo de datos](05-modelo-de-datos.md). ## AMB-10 · El Coordinador puede restablecer contraseñas — ¿de quién? §7 le permite restablecer contraseñas. Si eso incluye la del Superadmin, el Coordinador puede **escalar privilegios** tomando la cuenta del Superadmin. **Propuesta [RT]:** regla de jerarquía obligatoria — *nadie puede restablecer la contraseña de un usuario con nivel de rol igual o superior al propio*. El Coordinador restablece docentes, estudiantes y acudientes; nunca a un Superadmin ni a otro Coordinador. ## AMB-11 · "Datos institucionales sensibles" del colegio no está definido §7 prohíbe al Coordinador acceder a "la configuración/datos institucionales sensibles del colegio", sin listar cuáles son. **Propuesta [RT]:** el Coordinador tiene **lectura** de todo el módulo Colegio (la necesita para verificar el encabezado de los boletines) y **escritura de nada**. Sin campos ocultos y sin ambigüedad de implementación. ## AMB-12 · Estado del año: "Inactivo" vs "Cerrado" §13 propone cuatro estados sin definir la diferencia entre *Inactivo* y *Cerrado*, ni las transiciones válidas. **Propuesta [RT]:** tres estados con máquina de estados explícita — `EN_CONFIGURACION` → `ACTIVO` → `CERRADO` (irreversible salvo por Superadmin con auditoría). "Inactivo" se elimina por redundante: un año en configuración ya está inactivo a efectos operativos. Detalle en [06 — Reglas de negocio](06-reglas-de-negocio.md). ## AMB-13 · El código de matrícula tiene una condición de carrera §23 propone `MAT-2026-000123`. Si dos secretarias matriculan al mismo tiempo, un contador ingenuo ("buscar el máximo y sumar uno") asigna el mismo número a ambas. **Propuesta [RT]:** el consecutivo se obtiene de una entidad de secuencias por año con bloqueo de fila **dentro de la misma transacción** de la matrícula, o se deriva del identificador interno ya generado. Nunca de un conteo previo fuera de transacción. ## AMB-14 · Asistencia no está en alcance, pero el boletín suele exigirla §58 deja asistencia como funcionalidad futura. Muchos boletines colombianos incluyen la columna de fallas. **Propuesta [RT]:** la plantilla del boletín reserva el espacio de la columna de inasistencias, oculta por configuración. Cuando se construya el módulo de asistencia [FF], se activa sin rediseñar el PDF. --- # Parte 3 — Riesgos técnicos y legales detectados ## RG-01 · PHP 8.0 está fuera de soporte de seguridad — **crítico** §4 exige "PHP 8.0 o superior". **PHP 8.0 dejó de recibir correcciones de errores el 26 de noviembre de 2022 y parches de seguridad el 26 de noviembre de 2023.** Desplegar un sistema nuevo que maneja **datos personales de menores de edad** sobre una rama sin parches es un riesgo que el equipo no puede recomendar. **Recomendación [RT]:** exigir **PHP 8.2 como mínimo**, apuntando a 8.3. Está disponible en prácticamente todo hosting compartido y VPS actual, no añade costo, y no cambia una sola línea de la arquitectura propuesta. El requisito "8.0 o superior" se sigue cumpliendo — solo se sube el piso. ## RG-02 · Datos sensibles de menores — Ley 1581 de 2012 El sistema almacena **EPS, RH (grupo sanguíneo) y observaciones** de menores de edad. Bajo la Ley 1581 de 2012 y el Decreto 1377 de 2013, los datos de salud son **datos sensibles** y los datos de niños y adolescentes tienen protección reforzada (art. 7). Implicaciones concretas: - Se requiere **autorización del acudiente** para el tratamiento de datos, registrada y fechada. - Debe existir **política de tratamiento de datos** publicada y aceptada. - El acceso a campos sensibles debe ser **restringido por rol y auditado** (un docente no necesita ver el RH). - Deben definirse **retención y finalidad** de los datos. **Recomendación [RT]:** incluir en el wizard de matrícula la casilla de autorización de tratamiento de datos con fecha y usuario que la registró; marcar EPS / RH / observaciones médicas como campos de acceso restringido (Superadmin y Coordinador); y auditar su consulta. Es de bajo esfuerzo y evita un incumplimiento real. ## RG-03 · Generación masiva de boletines: tiempo de ejecución y memoria §42 exige generar los boletines de **todo un curso**. Con 35 estudiantes, cada boletín con tabla histórica y gráfica, un proceso sincrónico en hosting compartido choca contra el límite de tiempo de ejecución (típicamente 30 s) y el límite de memoria. Es una de las causas más frecuentes de fallo en sistemas de este tipo. **Recomendación [RT]:** generación **por lotes con progreso**: el navegador solicita bloques de 5 estudiantes en peticiones sucesivas, el servidor arma los PDF parciales en disco temporal, y al final los une en un único documento. El usuario ve una barra de progreso real. Detalle en [10 — Boletines](10-boletines.md). ## RG-04 · Cálculo de puestos y promedios en cada carga de pantalla Calcular el puesto de un estudiante exige promediar y ordenar a **todo el curso**. Hacerlo cada vez que alguien abre un dashboard o genera un boletín multiplica la carga innecesariamente. **Recomendación [RT]:** entidad de **consolidado** (promedio por asignatura, promedio general, puesto, nivel) que se recalcula cuando cambia una nota del curso o bajo demanda desde el cierre de periodo, **no en cada lectura**. Es la diferencia entre un boletín de curso que tarda 8 segundos y uno que tarda 4 minutos. ## RG-05 · Multi-colegio: el riesgo no es la columna, es el olvido §57 exige preparar el sistema para varios colegios. Añadir una columna `institucion_id` es trivial; **el riesgo real es que una sola consulta olvide filtrarla** y un colegio vea los datos de otro. Ese tipo de fuga se descubre tarde y es grave. MariaDB **no ofrece seguridad a nivel de fila** para protegerlo desde el motor. **Recomendación [RT]:** desde la v1, **todo** acceso a datos pasa por una capa de repositorio que inyecta el filtro de institución automáticamente; ninguna consulta se escribe suelta. Aunque haya un solo colegio, el hábito y la infraestructura quedan instalados. Detalle en [13 — Arquitectura técnica](13-arquitectura-tecnica.md). ## RG-06 · Mayúsculas y caracteres del español §52 exige convertir nombres a mayúsculas y **no deformar** Ñ, tildes ni diéresis. Es un error clásico: la función de mayúsculas por defecto de PHP no es consciente de UTF-8 y convierte "MUÑOZ" en un carácter roto, o deja "muñoz" → "MUñOZ". **Recomendación [RT]:** uso obligatorio de funciones multibyte con UTF-8 explícito en toda normalización de texto, cotejamiento `utf8mb4` en base de datos, y una prueba automatizada con el conjunto `ÑÁÉÍÓÚÜ` como criterio de aceptación de la Fase 1. Suena menor; en la práctica corrompe los nombres de decenas de estudiantes si se descuida. ## RG-07 · Concurrencia en la digitación de notas Dos docentes calificando el mismo curso, o un coordinador cerrando el periodo mientras un docente digita: sin control, la última escritura gana en silencio o se guardan notas en un periodo ya cerrado. **Recomendación [RT]:** el servidor **revalida el estado del periodo en el momento de guardar** (no confía en lo que el navegador cargó hace 20 minutos) y devuelve un error claro y recuperable si el periodo se cerró entretanto, conservando lo digitado en pantalla para que el docente no pierda el trabajo. --- # Parte 4 — Lo que la especificación NO dice y conviene decidir Puntos no mencionados en ningún apartado, que aparecerán inevitablemente durante el desarrollo: | Tema | Por qué aparecerá | Propuesta mínima [RT] | |---|---|---| | **Copias de seguridad** | Un sistema con el histórico académico de un colegio sin respaldo es un riesgo institucional | Respaldo diario automatizado + prueba de restauración documentada | | **Zona horaria** | Fechas de tareas y auditoría desfasadas si el servidor está en UTC | Fijar `America/Bogota` en la aplicación y en la sesión de base de datos | | **Jornadas** | §12 menciona la "Jornada" del colegio; un curso también tiene jornada (mañana/tarde) | Campo jornada en el curso, no solo en el colegio | | **Sedes** | Muchos colegios tienen sede principal y sedes anexas bajo el mismo DANE | Entidad `sede` opcional desde v1 (es barata ahora, cara después) | | **Certificados y constancias** | Se piden constantemente en secretaría | [FF], pero la información necesaria ya queda en el modelo | | **Estudiante repitente** | Un estudiante puede cursar el mismo grado dos años seguidos | El modelo lo soporta (matrícula por año); basta con no asumir unicidad estudiante–grado | | **Importación inicial masiva** | El colegio ya tiene sus estudiantes en Excel o SIMAT; digitarlos a mano es inviable | Importador CSV/Excel con validación previa y reporte de errores — **fuertemente recomendado en Fase 4** | > El importador masivo merece atención especial: sin él, la puesta en marcha exige digitar manualmente cientos de > estudiantes y acudientes. Es la diferencia entre arrancar en una semana o en dos meses. --- # Resumen: qué se necesita del cliente para desbloquear | Antes de iniciar | Decisiones requeridas | |---|---| | **Fase 1** | DP-08 (contraseñas), RG-01 (versión de PHP) | | **Fase 2** | DP-09 (Grado vs Curso), AMB-12 (estados del año) | | **Fase 5** | DP-03 (nota única), DP-04 (recuperación), DP-07 (logros), AMB-02, AMB-03 | | **Fase 6** | DP-01 (qué ve la familia) | | **Fase 7** | DP-02 (entrega del boletín), DP-05 (área vs asignatura), AMB-06 | | **Fase 8** | DP-06 (criterio de promoción) | Las **Fases 0 y 1 pueden comenzar de inmediato** una vez aprobados DP-08 y RG-01.