# 10 — Boletines PDF *(Entregable J)* > El boletín es **el producto visible del sistema**. Es el documento que sale del colegio, que la familia guarda y > que representa institucionalmente. Su calidad gráfica determina en buena medida la percepción del sistema > completo (§42, §66). --- ## Elección del motor de PDF La especificación menciona TCPDF "o una alternativa libre y técnicamente superior" (§4). El equipo evaluó tres opciones reales: | Motor | Ventajas | Desventajas | Veredicto | |---|---|---|---| | **TCPDF** | Muy maduro · control absoluto de posicionamiento · sin dependencias | El maquetado se programa coordenada por coordenada · soporte de CSS muy limitado · cambiar el diseño del boletín exige reprogramar | Alternativa | | **mPDF** | **Soporta HTML y CSS reales** · UTF-8 completo · tablas complejas · encabezados y pies repetidos · numeración de páginas · importa SVG | Mayor consumo de memoria | ✅ **Recomendado** | | **Dompdf** | Simple | Soporte de CSS más pobre que mPDF · tablas complejas problemáticas | Descartado | | Navegador sin interfaz | Fidelidad total | Requiere instalar un navegador en el servidor — **inviable en hosting compartido** (§4) | Descartado | ### Recomendación: **mPDF** [RT] La razón decisiva no es técnica sino de mantenimiento: **con mPDF, el boletín es una plantilla HTML con CSS.** Ajustar un margen, cambiar el color del encabezado o mover el bloque de firmas es editar una plantilla, no reprogramar coordenadas. Un colegio pide ese tipo de ajuste varias veces al año. Además, mPDF importa **SVG**, lo que permite incrustar la gráfica de evolución (§44) sin generar imágenes de mapa de bits ni depender de JavaScript. **Mitigación de su desventaja:** el mayor consumo de memoria se controla con la generación por lotes descrita más abajo, que es necesaria de todos modos. > El diseño desacopla el motor detrás de una interfaz propia. Si el colegio prefiere TCPDF, se cambia la > implementación sin tocar las plantillas de contenido ni la lógica de negocio. --- ## Estructura del boletín Los 17 elementos exigidos por §42, distribuidos en el documento: ``` ╔══════════════════════════════════════════════════════════════════════════════╗ ║ ┌──────┐ INSTITUCIÓN EDUCATIVA SAN JOSÉ ┌──────┐ ║ ① ② ③ ║ │ LOGO │ NIT 800.123.456-7 · DANE 105001000123 │ESCUDO│ ║ ║ └──────┘ Resolución 4521 de 2018 · Secretaría de Educación └──────┘ ║ ║ Calle 45 #12-30 · Medellín, Antioquia · (604) 123 4567 ║ ╠══════════════════════════════════════════════════════════════════════════════╣ ║ INFORME ACADÉMICO · PERIODO 2 · 2026 ║ ⑥ ⑦ ╠══════════════════════════════════════════════════════════════════════════════╣ ║ Estudiante: ACOSTA RIVERA JUAN CARLOS Documento: TI 1035478921 ║ ④ ║ Curso: 6°A Director: MARÍA GONZÁLEZ Jornada: Mañana ║ ⑤ ║ Puesto en el periodo: 7 de 32 Puesto acumulado: 9 de 32 ║ ⑫ ╠══════════════════════════════════════════════════════════════════════════════╣ ║ ÁREA / ASIGNATURA P1 P2 P3 P4 PROM DESEMPEÑO ║ ⑧ ⑨ ⑩ ║ ──────────────────────────────────────────────────────────────────────── ║ ║ ▸ MATEMÁTICAS ║ ║ Matemáticas 3.5 4.0 - - 3.75 ALTO ║ ║ Geometría 4.0 4.2 - - 4.10 ALTO ║ ║ ▸ HUMANIDADES ║ ║ Lengua Castellana 4.0 4.5 - - 4.25 ALTO ║ ║ Inglés 3.2 3.0 - - 3.10 BÁSICO ║ ║ ▸ CIENCIAS NATURALES ║ ║ Ciencias Naturales 2.8 3.4 - - 3.10 BÁSICO ║ ║ ──────────────────────────────────────────────────────────────────────── ║ ║ PROMEDIO GENERAL DEL PERIODO 3.82 ALTO ACUMULADO 3.66 BÁSICO ║ ╠══════════════════════════════════════════════════════════════════════════════╣ ║ DESEMPEÑOS DEL PERIODO ║ ⑪ ║ ▸ Matemáticas ║ ║ • Resuelve operaciones con fracciones homogéneas y heterogéneas. ║ ║ • Aplica el concepto de mínimo común múltiplo en la solución de problemas.║ ║ ▸ Lengua Castellana ║ ║ • Identifica la estructura del texto narrativo. ║ ╠══════════════════════════════════════════════════════════════════════════════╣ ║ EVOLUCIÓN DEL RENDIMIENTO ║ ⑭ ⑮ ║ 5.0┤ ║ ║ 4.0┤ ●━━━━━● ← Estudiante ║ ║ 3.0┤ ●━━━━╯ ╰┈┈┈○ ┈ Promedio del curso ║ ║ 2.0┤ ║ ║ └───P1────P2────P3────P4 ║ ║ Tendencia: ▲ Mejora sostenida ║ ╠══════════════════════════════════════════════════════════════════════════════╣ ║ OBSERVACIONES ║ ⑬ ║ Juan Carlos ha mostrado un avance importante en su desempeño académico. ║ ║ Se recomienda reforzar la comprensión lectora en Inglés. ║ ╠══════════════════════════════════════════════════════════════════════════════╣ ║ ESCALA DE VALORACIÓN ║ ║ Superior 4.6–5.0 · Alto 4.0–4.5 · Básico 3.0–3.9 · Bajo 0.0–2.9 ║ ╠══════════════════════════════════════════════════════════════════════════════╣ ║ ║ ⑯ ║ ______________________ ______________________ ║ ║ MARÍA GONZÁLEZ CARLOS RAMÍREZ ║ ║ Director de curso Rector ║ ╠══════════════════════════════════════════════════════════════════════════════╣ ║ Generado el 12/06/2026 10:42 · SIGA · Página 1 de 1 MAT-2026-000123 ║ ⑰ ╚══════════════════════════════════════════════════════════════════════════════╝ ``` | # | Elemento (§42) | Origen | Notas | |---|---|---|---| | ① | Encabezado institucional | Módulo Colegio | Texto configurable | | ② | Logo | Archivo institucional | Opcional; el diseño se adapta si falta | | ③ | Datos del colegio | Módulo Colegio | Solo los campos diligenciados | | ④ | Datos del estudiante | Estudiante + Persona | | | ⑤ | Curso | Matrícula + Curso | Curso **actual**; si hubo traslado, se puede indicar | | ⑥ | Año | Contexto | | | ⑦ | Periodo | Contexto o "Informe final" | | | ⑧ | Tabla académica | Consolidado | Agrupada por área (ver DP-05) | | ⑨ | Histórico de notas | Notas de todos los periodos | Los no calificados aparecen como `-` | | ⑩ | Promedio por asignatura | Consolidado | Solo periodos calificados (RN-CALC-02) | | ⑪ | Desempeños / logros | Desempeños del periodo | Iguales para el curso (ver DP-07) | | ⑫ | Puesto | Consolidado | Del periodo y acumulado | | ⑬ | Observaciones | Observaciones del boletín | General y, si existen, por asignatura | | ⑭ | Gráfica de evolución | Consolidado histórico | SVG incrustado | | ⑮ | Análisis visual | Calculado | Tendencia y comparación con el curso | | ⑯ | Firmas | Institución + firmas configuradas | Con imagen de firma si se cargó | | ⑰ | Pie de página | Sistema | Fecha, paginación, código de matrícula | --- ## La tabla académica Es el elemento con más peso visual y donde más se nota la calidad del diseño. | Decisión | Justificación | |---|---| | **Agrupación por área con las asignaturas dentro** | Es la estructura del sistema educativo colombiano y facilita la lectura. Sin nota de área en la v1 — [DP-05](00-hallazgos-y-decisiones.md#dp-05--el-boletín-se-organiza-por-área-o-por-asignatura) | | **Columnas de periodo fijas** (tantas como tenga el año) | Un boletín del periodo 2 en un año de 4 periodos muestra las 4 columnas, con `-` en las futuras. Da contexto y evita que el boletín "crezca" entre periodos | | **Nota del periodo actual destacada** | Fondo suave en la columna del periodo del informe | | **Números tabulares alineados a la derecha** | Sin esto, las columnas de notas no se alinean y se ven descuidadas | | **Color en la columna de desempeño** | Verde / azul / ámbar / rojo, **con el texto del nivel** — nunca solo color ([accesibilidad](08-ux-ui.md#accesibilidad)) | | **Fila de totales destacada** | Promedio general del periodo y acumulado | | **Recuperaciones marcadas** | Un asterisco junto a la nota indica que hubo recuperación, con nota al pie: *"* Nota obtenida mediante actividad de recuperación"* | --- ## La gráfica de evolución *(§44)* **Propósito:** permitir identificar tendencia, mejora, estabilidad o disminución. ### Diseño propuesto - **Línea sólida:** promedio general del estudiante por periodo. - **Línea punteada:** promedio general del curso por periodo — la comparación que §44 permite explícitamente, y que **no revela información individual de ningún otro estudiante**. - **Bandas de fondo** con los colores de la escala, para leer el nivel sin consultar el eje. - **Puntos etiquetados** con el valor. - **Etiqueta de tendencia** calculada. ### Cálculo de la tendencia [RT] Comparando el promedio del periodo con el anterior: | Diferencia | Etiqueta | |---|---| | ≥ +0.30 | ▲ Mejora significativa | | +0.10 a +0.29 | ▲ Mejora | | −0.09 a +0.09 | ● Estable | | −0.10 a −0.29 | ▼ Desciende | | ≤ −0.30 | ▼ Desciende significativamente | Con tres o más periodos, se evalúa la tendencia global además de la variación puntual, para distinguir un bache aislado de un descenso sostenido. ### Implementación técnica La gráfica se genera como **SVG en el servidor** —no como imagen de mapa de bits, no con JavaScript— y se incrusta en el HTML que mPDF convierte a PDF. Ventajas: nítida a cualquier resolución de impresión · sin dependencia de navegador · sin archivos temporales de imagen · el mismo generador sirve para la pantalla y para el PDF, garantizando que **la gráfica que ve el coordinador en pantalla es exactamente la que sale impresa**. --- ## Modos de generación ### Individual Estudiante → Periodo → Generar. Respuesta inmediata, PDF en el navegador con opción de descargar o imprimir. ### Masiva por curso — con generación por lotes **El problema:** 35 boletines en un proceso sincrónico superan el tiempo máximo de ejecución de un hosting compartido y fallan a mitad, sin dejar nada útil ([RG-03](00-hallazgos-y-decisiones.md#rg-03--generación-masiva-de-boletines-tiempo-de-ejecución-y-memoria)). **La solución:** ``` Navegador Servidor │ │ ├── Iniciar generación (curso, per.) ─►│ Crea el trabajo, calcula │ │ el consolidado si hace falta │◄── id del trabajo, total: 35 ────────┤ │ │ ├── Procesar lote 1 (1–5) ────────────►│ Genera 5 PDF en temporal │◄── 5/35 ─────────────────────────────┤ ├── Procesar lote 2 (6–10) ───────────►│ │◄── 10/35 ────────────────────────────┤ │ … │ ├── Finalizar ────────────────────────►│ Une los 35 en un solo PDF │◄── enlace de descarga ───────────────┤ y limpia los temporales ``` Cada petición procesa 5 estudiantes: bien por debajo de cualquier límite de tiempo. El usuario ve progreso real, puede cancelar, y si algo falla se sabe exactamente en qué estudiante. **Salida:** un **PDF único paginado**, listo para imprimir de una vez. Opcionalmente, un comprimido con los archivos individuales, útil cuando se entregan por separado. **Precondición:** el consolidado del periodo debe estar calculado. Si está desactualizado —por ejemplo tras una reapertura de periodo— el sistema lo recalcula al iniciar el trabajo y lo informa. --- ## Tipos de boletín | Tipo | Contenido | Cuándo | |---|---|---| | **De periodo** | Notas del periodo + histórico de los anteriores | Al cierre de cada periodo | | **Acumulado / final** | Todos los periodos + promedio anual + estado de promoción | Al cierre del año | | **Constancia de desempeño** [FF] | Versión resumida para trámites | Fuera de alcance en v1 | --- ## Plantillas configurables El boletín se compone de **bloques activables** desde la configuración, lo que permite adaptarlo sin reprogramar: | Bloque | Por defecto | Nota | |---|---|---| | Encabezado institucional | Activo | | | Foto del estudiante | Inactivo | Se activa si el colegio carga fotos | | Puesto | Activo | Configurable — algunos colegios no lo publican | | Desempeños | Activo | | | Gráfica de evolución | Activo | | | Comparación con el curso | Activo | | | Observaciones por asignatura | Inactivo | Se activa si los docentes las usan | | Escala de valoración | Activo | | | **Columna de inasistencias** | **Inactivo** | Reservada para el módulo futuro de asistencia ([AMB-14](00-hallazgos-y-decisiones.md#amb-14--asistencia-no-está-en-alcance-pero-el-boletín-suele-exigirla)) | | Firmas | Activo | Cantidad y cargos configurables | --- ## Especificaciones del documento | Aspecto | Valor | |---|---| | **Tamaño** | Carta (216 × 279 mm) — estándar colombiano | | **Orientación** | Vertical | | **Márgenes** | 15 mm laterales, 12 mm superior e inferior | | **Objetivo de extensión** | Una página por estudiante. Con muchas asignaturas o logros extensos, dos | | **Fuentes** | Incrustadas en el PDF, con cobertura completa de caracteres del español | | **Tamaño de archivo** | Objetivo: < 300 KB por boletín individual | | **Metadatos** | Título, autor (la institución), asunto y fecha de creación | | **Encabezado y pie repetidos** | En caso de segunda página | | **Numeración** | "Página X de Y" | | **Codificación** | UTF-8 con verificación explícita de `ÑÁÉÍÓÚÜ` como criterio de aceptación ([RG-06](00-hallazgos-y-decisiones.md#rg-06--mayúsculas-y-caracteres-del-español)) | **Consideración de seguridad [RT]:** el PDF puede incluir un **código de verificación** en el pie, que permita a la secretaría confirmar la autenticidad de un boletín impreso frente al sistema. Es de bajo costo y previene la alteración de boletines físicos. --- ## Rendimiento — objetivos | Escenario | Objetivo | |---|---| | Boletín individual | < 2 segundos | | Curso de 35 estudiantes | < 60 segundos con progreso visible | | Colegio completo (847) | Procesado por curso, no en un solo trabajo | | Memoria por boletín | < 32 MB | **Optimizaciones aplicadas:** consolidado precalculado (nunca se recalculan promedios durante la generación) · una sola consulta por curso en lugar de una por estudiante · logo y escudo cargados una vez y reutilizados · plantilla compilada una vez por lote · liberación explícita de memoria entre estudiantes. --- ## Criterios de aceptación - [ ] El boletín incluye los 17 elementos de §42 - [ ] Los caracteres `ÑÁÉÍÓÚÜ` se imprimen correctamente en todos los bloques - [ ] Un estudiante sin nota en una asignatura muestra `-`, no `0.0` - [ ] El promedio coincide **exactamente** con el mostrado en pantalla y en los reportes - [ ] La gráfica refleja los mismos datos que la tabla - [ ] El puesto coincide con el del consolidado - [ ] Un colegio sin logo genera un boletín correcto, sin espacios rotos - [ ] La generación de 35 boletines completa sin agotar tiempo ni memoria - [ ] El PDF unificado tiene los estudiantes en el orden de la lista del curso - [ ] El boletín de un año cerrado se genera igual que el de un año activo - [ ] El boletín imprime correctamente en blanco y negro (los niveles se distinguen sin color)