Tipos de informe

Los informes listados se generan cada hora mediante un cron en ssea-report-worker, salvo ejecución on-demand vía POST /v1/tenants/:id/reports/jobs. Cada run escribe un artifact JSON+CSV en almacenamiento de objetos y publica un snapshot consultable vía GET /v1/tenants/:id/reports/:type/latest.

Catálogo

Tipo	Contenido	Capability lectura	Capability descarga
`retention_cohort`	Cohortes y retención semanal	`reports.snapshots.read` / `reports.latest.read`	`reports.download.csv` / `reports.download.json`
`activity_funnel`	Embudo de pasos de actividad	`reports.snapshots.read` / `reports.latest.read`	`reports.download.csv` / `reports.download.json`
`teacher_course_health`	Salud por curso (docentes)	`reports.snapshots.read` / `reports.latest.read`	`reports.download.csv` / `reports.download.json`
`student_learning_profile`	Perfil agregado por estudiante	`reports.snapshots.read` / `reports.latest.read` (students: solo su fila)	`reports.download.csv` / `reports.download.json`
`assessment_performance`	Rendimiento por ítem y curso	`reports.snapshots.read` / `reports.latest.read` (students: solo sus calificaciones)	`reports.download.csv` / `reports.download.json`
`early_warning_summary`	Resumen de alertas tempranas	`reports.snapshots.read` / `reports.latest.read`	`reports.download.csv` / `reports.download.json`

Reglas universales (delegadas a la superficie de política, ver Roles y permisos):

Los estudiantes nunca descargan archivos. Es estructural: ninguna capability reports.download.* admite el rol student.
Los estudiantes que leen student_learning_profile y assessment_performance reciben únicamente su propia fila.
Los docentes reciben filas filtradas a sus cursos. Si un docente no tiene cursos asignados, la respuesta es vacía (fail-closed).
Los administradores reciben todo el tenant. Los super-admins reciben todo el tenant que hayan seleccionado en tenant.switch.
Los artifacts pre-computados se re-filtran al entregar: aunque el archivo en almacenamiento contenga datos del tenant entero, el endpoint reduce las filas al alcance del solicitante antes del stream.

Versionado y schema drift

Los payloads incluyen schema_version. Si el shape cambia, incrementa la versión y actualiza los tipos en ssea-dashboard/src/api/reports.ts. La SPA degrada de forma elegante mostrando un mensaje “Esquema no soportado” en lugar de renderizar columnas vacías.

Cadencia y disponibilidad

Cron horario en ssea-report-worker recorre todos los tenants activos y encola un job por reporte y tenant.
Snapshots en KV tienen TTL 35 minutos para tolerar saltos puntuales del cron.
El endpoint GET /v1/tenants/:id/reports/:type/latest consulta KV primero; si está vacío (primer arranque), cae al artifact más reciente de almacenamiento.

Más contexto

Roles y permisos — quién puede ver qué reporte.
Arquitectura — dónde vive el report worker.
Flujo de datos — del evento al artifact.