# 11 — Reportes y exportaciones *(Entregable K)*

> Todos los reportes comparten la misma arquitectura: **filtros → resultados → exportación**. Un solo componente
> de reportería, muchas configuraciones. Eso garantiza comportamiento uniforme y hace que agregar un reporte nuevo
> cueste horas, no días.

---

## Arquitectura común

```
┌───────────────────────────────────────────────────────────────────────────┐
│  REPORTE: Estudiantes por curso                                           │
├───────────────────────────────────────────────────────────────────────────┤
│  FILTROS                                                                  │
│  Año [2026 ▼]  Curso [Todos ▼]  Estado [Activa ▼]  Jornada [Todas ▼]     │
│  Grado [Todos ▼]           [Limpiar]              [Generar reporte]       │
├───────────────────────────────────────────────────────────────────────────┤
│  847 registros · Generado el 22/08/2026 14:30                             │
│                              [⬇ Excel] [⬇ CSV] [⬇ PDF] [🖨 Imprimir]      │
├───────────────────────────────────────────────────────────────────────────┤
│  Tabla de resultados — ordenable, paginada, buscable                      │
├───────────────────────────────────────────────────────────────────────────┤
│  Totales y subtotales                                                     │
└───────────────────────────────────────────────────────────────────────────┘
```

**Reglas comunes a todos los reportes:**

| Regla | Detalle |
|---|---|
| **Filtro de contexto siempre presente** | Año y, cuando aplique, periodo. Nunca se genera un reporte sin saber de qué año es |
| **Filtro de ámbito automático** | Un docente solo obtiene datos de sus asignaciones, aunque el reporte sea el mismo |
| **La exportación respeta los filtros** | Lo exportado es exactamente lo mostrado. Es un error frecuente y muy irritante que no sea así |
| **Sello de generación** | Todo reporte exportado lleva fecha, hora, usuario y filtros aplicados |
| **Paginación del lado del servidor** | Nunca se cargan miles de filas en el navegador |
| **Datos sensibles excluidos** | Salvo que el reporte los requiera y el rol lo permita ([RG-02](00-hallazgos-y-decisiones.md#rg-02--datos-sensibles-de-menores--ley-1581-de-2012)) |
| **Filtros persistentes** | Al volver desde un detalle, los filtros se conservan |

---

# Reportes administrativos *(§54)*

### R-ADM-01 · Estudiantes por curso
**Filtros:** año, curso, grado, jornada, estado de matrícula, sexo
**Columnas:** documento, nombre completo, curso, fecha de matrícula, código, estado, acudiente principal, celular
**Totales:** por curso y general
**Uso:** listas de asistencia, entrega de boletines, planillas

### R-ADM-02 · Estudiantes activos / inactivos
**Filtros:** año, estado, rango de fechas, curso
**Columnas:** documento, nombre, curso, estado, fecha del último cambio, motivo, usuario que lo registró
**Uso:** conciliación de matrícula, reportes a Secretaría de Educación

### R-ADM-03 · Matrículas por año
**Filtros:** rango de años, grado, jornada
**Columnas:** año, grado, curso, matriculados, retirados, trasladados, promovidos, no promovidos, graduados
**Visualización:** tabla + gráfica de barras comparativa entre años
**Uso:** análisis de crecimiento y deserción institucional

### R-ADM-04 · Matrículas por curso
**Filtros:** año, jornada, sede
**Columnas:** curso, grado, director, cupo, matriculados, disponibles, % ocupación
**Uso:** planeación de cupos y apertura de grupos

### R-ADM-05 · Estudiantes retirados
**Filtros:** año, rango de fechas, curso, motivo
**Columnas:** documento, nombre, curso, fecha de retiro, motivo, usuario, acudiente, celular
**Uso:** seguimiento de deserción; el celular permite el contacto de retención

### R-ADM-06 · Traslados
**Filtros:** año, rango de fechas, curso origen, curso destino
**Columnas:** estudiante, curso origen, curso destino, fecha, motivo, usuario
**Uso:** control de movimientos internos

### R-ADM-07 · Promovidos y no promovidos
**Filtros:** año, grado, curso
**Columnas:** estudiante, curso, promedio anual, asignaturas en Bajo, estado, curso destino, quién decidió
**Totales:** tasa de promoción por curso y por grado
**Uso:** informe de fin de año y análisis de reprobación

### R-ADM-08 · Directorio de acudientes [RT]
**Filtros:** curso, grado, parentesco, responsable financiero
**Columnas:** estudiante, curso, acudiente, parentesco, celular, correo, principal
**Uso:** convocatoria a reuniones y contacto masivo. No está en §54, pero es de los listados que más se piden.

---

# Reportes académicos *(§54)*

### R-ACA-01 · Notas por curso
**Filtros:** año, periodo, curso
**Formato:** matriz — estudiantes en filas, asignaturas en columnas
**Incluye:** nota de cada asignatura, promedio, nivel, puesto
**Totales:** promedio por asignatura del curso, promedio general
**Uso:** el reporte de consolidación por excelencia; sustituye la planilla manual de la comisión de evaluación

```
  NOTAS · 6°A · PERIODO 2 · 2026
  ┌───────────────────────┬─────┬─────┬─────┬─────┬─────┬──────┬───────┬────┐
  │ Estudiante            │ MAT │ ESP │ CIE │ SOC │ ING │ PROM │ NIVEL │ P. │
  ├───────────────────────┼─────┼─────┼─────┼─────┼─────┼──────┼───────┼────┤
  │ ACOSTA RIVERA, JUAN   │ 4.0 │ 4.5 │ 3.4 │ 4.1 │ 3.0 │ 3.80 │ Básico│  7 │
  │ BERNAL LÓPEZ, ANA     │ 4.5 │ 4.8 │ 4.2 │ 4.6 │ 4.4 │ 4.50 │ Alto  │  1 │
  ├───────────────────────┼─────┼─────┼─────┼─────┼─────┼──────┼───────┼────┤
  │ PROMEDIO DEL CURSO    │3.92 │4.15 │3.61 │4.02 │3.44 │ 3.83 │       │    │
  └───────────────────────┴─────┴─────┴─────┴─────┴─────┴──────┴───────┴────┘
```

### R-ACA-02 · Notas por asignatura
**Filtros:** año, periodo, asignatura, curso, docente
**Columnas:** estudiante, curso, nota, nivel, tiene recuperación
**Totales:** promedio, distribución por nivel, cantidad de reprobados
**Uso:** análisis del docente y de la coordinación sobre una asignatura concreta

### R-ACA-03 · Promedios
**Filtros:** año, periodo o acumulado, curso, grado
**Columnas:** estudiante, curso, promedio del periodo, promedio acumulado, nivel, puesto del periodo, puesto acumulado
**Ordenamiento:** por promedio descendente (usa la precisión de 4 decimales, §34)
**Uso:** cuadro de honor, seguimiento del rendimiento

### R-ACA-04 · Rendimiento por periodo
**Filtros:** año, curso, grado
**Formato:** distribución de niveles de desempeño por periodo
**Visualización:** barras apiladas por periodo
**Uso:** ver si el colegio mejora o empeora a lo largo del año

### R-ACA-05 · Rendimiento acumulado
**Filtros:** año, grado, curso, área
**Columnas:** curso o área, promedio acumulado, distribución de niveles, variación respecto al periodo anterior
**Uso:** informe de la comisión de evaluación

### R-ACA-06 · Puestos
**Filtros:** año, periodo, curso
**Columnas:** puesto, estudiante, promedio (4 decimales visibles en la exportación), nivel
**Nota:** el reporte muestra la precisión real para hacer verificables los desempates
([AMB-04](00-hallazgos-y-decisiones.md#amb-04--reglas-de-empate-en-el-puesto))
**Uso:** cuadro de honor y verificación de reclamos

### R-ACA-07 · Bajo rendimiento
**Filtros:** año, periodo, curso, número mínimo de asignaturas en Bajo
**Columnas:** estudiante, curso, asignaturas en Bajo (con nombre), promedio, nivel, acudiente, celular
**Uso:** **el reporte más útil para la intervención pedagógica.** Identifica a quién hay que acompañar y con quién
hay que hablar, en una sola pantalla

### R-ACA-08 · Desempeños por asignatura
**Filtros:** año, periodo, curso, asignatura, docente
**Columnas:** asignatura, curso, periodo, cantidad de desempeños, docente, fecha del último registro
**Alerta:** resalta las combinaciones **sin desempeños registrados**
**Uso:** control de que los docentes registraron los logros antes del boletín

### R-ACA-09 · Recuperaciones [RT]
**Filtros:** año, periodo, curso, asignatura
**Columnas:** estudiante, asignatura, nota original, nota de recuperación, definitiva, fecha, docente
**Uso:** control y trazabilidad de las nivelaciones. No está listado en §54, pero se deriva directamente de §30.

---

# Reportes de docentes *(§54)*

### R-DOC-01 · Asignaturas asignadas
**Filtros:** año, docente, área
**Columnas:** docente, asignatura, curso, grado, número de estudiantes
**Uso:** verificación de asignación académica

### R-DOC-02 · Cursos asignados
**Filtros:** año, docente
**Columnas:** docente, cursos donde dicta, dirección de curso, total de estudiantes atendidos
**Uso:** visión general por docente

### R-DOC-03 · Carga académica
**Filtros:** año, docente, área
**Columnas:** docente, número de asignaturas, número de cursos, total de estudiantes, es director de curso
**Totales:** promedio y máximo institucional
**Alerta:** resalta a los docentes por encima del umbral configurado
**Uso:** equilibrio de cargas al planear el año siguiente

### R-DOC-04 · Cumplimiento de registro [RT]
**Filtros:** año, periodo
**Columnas:** docente, asignaturas asignadas, notas registradas / esperadas, % de avance, desempeños registrados,
observaciones pendientes
**Uso:** es el reporte que alimenta el bloque de avance del [dashboard del Coordinador](09-dashboards.md#dashboard-del-coordinador-39).
No está en §54, pero es indispensable para el cierre de periodo.

---

# Reportes de tareas *(§54)*

### R-TAR-01 · Tareas por docente
**Filtros:** año, periodo, docente, estado
**Columnas:** docente, asignatura, curso, título, fecha de asignación, fecha de entrega, estado

### R-TAR-02 · Tareas por curso
**Filtros:** año, periodo, curso, estado
**Columnas:** curso, asignatura, título, docente, fecha de entrega, estado
**Uso:** el director de curso detecta acumulación de entregas en la misma semana

### R-TAR-03 · Tareas por asignatura
**Filtros:** año, periodo, asignatura, curso
**Columnas:** asignatura, curso, cantidad de tareas, docente, próxima fecha de entrega

### R-TAR-04 · Tareas próximas
**Filtros:** curso, asignatura, rango de días (por defecto 7)
**Columnas:** título, asignatura, curso, fecha de entrega, días restantes, docente
**Ordenamiento:** por urgencia

### R-TAR-05 · Tareas vencidas
**Filtros:** año, periodo, curso, asignatura, rango de fechas
**Columnas:** título, asignatura, curso, fecha de entrega, días vencida, docente

---

# Reportes de control

### R-CTL-01 · Auditoría
Ver [12 — Auditoría](12-auditoria.md).

### R-CTL-02 · Accesos al sistema [RT]
**Filtros:** rango de fechas, usuario, rol, resultado
**Columnas:** usuario, rol, fecha y hora, IP, resultado
**Alerta:** resalta patrones de intentos fallidos repetidos
**Uso:** detección de intentos de acceso no autorizado ([DP-08](00-hallazgos-y-decisiones.md#dp-08--la-política-de-contraseñas-tiene-un-riesgo-de-seguridad-real))

### R-CTL-03 · Integridad de datos [RT]
Reporte de inconsistencias que requieren atención humana:

- Estudiantes matriculados sin acudiente
- Asignaturas de un curso sin docente titular
- Cursos sin director
- Estudiantes sin ninguna nota en un periodo cerrado
- Matrículas activas en años cerrados
- Personas con datos de contacto incompletos

**Uso:** revisión periódica de calidad de datos. Es barato de construir y evita descubrir problemas el día de la
entrega de boletines.

---

# Exportaciones *(§55)*

## Formatos y cuándo usar cada uno

| Formato | Tecnología | Cuándo | Límite |
|---|---|---|---|
| **CSV** | Generación directa, UTF-8 con marca de orden de bytes | Volúmenes grandes, importar a otro sistema | Sin límite práctico |
| **XLSX** | PhpSpreadsheet | Reportes con formato, colores, varias hojas | ~10 000 filas |
| **PDF** | mPDF | Documentos para archivar o firmar | ~2 000 filas |
| **Impresión** | CSS de impresión | Impresión inmediata | — |

**Detalle que importa:** el CSV se genera **con marca de orden de bytes UTF-8**. Sin ella, Excel en Windows abre
"MUÑOZ" como texto corrupto, y ese es el reporte que se entrega a Secretaría de Educación.

**Para volúmenes grandes**, la exportación se genera de forma incremental sin cargar todo en memoria, con el mismo
esquema de lotes usado en los boletines.

## Contenido de las exportaciones

Toda exportación incluye una cabecera con:

```
  INSTITUCIÓN EDUCATIVA SAN JOSÉ
  Reporte: Notas por curso
  Filtros: Año 2026 · Periodo 2 · Curso 6°A
  Generado: 22/08/2026 14:30 por MARÍA GONZÁLEZ (Coordinador)
  Registros: 32
```

Sin esa cabecera, un archivo exportado circula por el colegio sin que nadie sepa de qué año es ni quién lo generó.

## Comportamiento de las tablas *(§55)*

Todas las tablas de reportes soportan:

| Función | Detalle |
|---|---|
| **Buscar** | Sobre las columnas de texto, con retardo |
| **Filtrar** | Filtros específicos por reporte, combinables |
| **Ordenar** | Por cualquier columna, ascendente y descendente. Columnas validadas contra lista blanca ([seguridad](07-seguridad.md#4-protección-contra-inyección-sql)) |
| **Paginar** | 25 / 50 / 100 / 200 por página |
| **Exportar** | Respetando filtros, orden y búsqueda activos |
| **Selección múltiple** | En los reportes con acciones masivas |

---

# Reportes por rol

| Reporte | Superadmin | Coordinador | Docente |
|---|:---:|:---:|:---:|
| R-ADM-01 a R-ADM-08 (administrativos) | ✓ | ✓ | — |
| R-ACA-01 Notas por curso | ✓ | ✓ | Solo sus asignaturas |
| R-ACA-02 Notas por asignatura | ✓ | ✓ | Solo las suyas |
| R-ACA-03 a R-ACA-06 | ✓ | ✓ | Solo sus cursos |
| R-ACA-07 Bajo rendimiento | ✓ | ✓ | Solo sus asignaturas |
| R-ACA-08 Desempeños | ✓ | ✓ | Solo los suyos |
| R-ACA-09 Recuperaciones | ✓ | ✓ | Solo las suyas |
| R-DOC-01 a R-DOC-03 | ✓ | ✓ | Solo la propia |
| R-DOC-04 Cumplimiento | ✓ | ✓ | Solo el propio |
| R-TAR-01 a R-TAR-05 | ✓ | ✓ | Solo las suyas |
| R-CTL-01 Auditoría | ✓ | Lectura | — |
| R-CTL-02 Accesos | ✓ | — | — |
| R-CTL-03 Integridad | ✓ | ✓ | — |

**Acudientes y estudiantes no tienen acceso al módulo de reportes** (§9, §10).

---

# Consideraciones técnicas

| Aspecto | Decisión |
|---|---|
| **Origen de los datos académicos** | Del **consolidado** materializado, no recalculando ([RG-04](00-hallazgos-y-decisiones.md#rg-04--cálculo-de-puestos-y-promedios-en-cada-carga-de-pantalla)) |
| **Consultas** | Diseñadas contra los índices del documento 05. Ninguna consulta de reporte sin índice de apoyo |
| **Sin N+1** | Los datos relacionados se traen en una sola consulta, nunca una por fila |
| **Coherencia** | Un promedio en un reporte, en el boletín y en pantalla debe ser **idéntico**. Todos usan el mismo servicio de cálculo |
| **Tiempo objetivo** | < 3 segundos para reportes de hasta 1 000 filas |
| **Reportes pesados** | Aviso previo y generación por lotes con progreso |
| **Caché** | Los reportes de años cerrados se pueden cachear indefinidamente: sus datos no cambian |
| **Auditoría** | La exportación de reportes con datos personales se registra en la auditoría |