El modelo de un vistazo
Plantillas
Una plantilla es un archivo
.tpl en texto plano que subes como multipart/form-data, junto con el formato de salida que produce y una descripción breve. Reporter guarda el archivo en el almacenamiento de objetos y sus metadatos en MongoDB. El lenguaje de plantillas es Pongo2, por lo que una plantilla combina texto literal del documento con variables, bucles, condicionales, filtros y etiquetas de agregación.
Una plantilla declara un formato de salida: PDF, HTML, XML, TXT o CSV. El PDF se renderiza primero como HTML y luego se convierte mediante un pool de workers de navegador headless.
Una plantilla dirige los datos mediante configName, el nombre estable de una fuente de datos, y mediante la tabla: {{ midaz_onboarding.accounts }}. Cuando hay más de un esquema en juego, se califica como {{ midaz_onboarding:public.accounts }}.
Al subir la plantilla, Reporter lee su texto y deriva los campos que toca, por fuente de datos y por tabla. Luego verifica cada tabla y campo referenciado contra el esquema activo de esa fuente de datos. Una fuente de datos inalcanzable genera una advertencia en lugar de un rechazo, de modo que la plantilla se sube igual aunque una base de datos esté caída.
Consulta Referencia de plantillas para conocer las etiquetas, los filtros y las expresiones que ofrece el lenguaje.
Fuentes de datos
Una fuente de datos es una conexión a PostgreSQL o MongoDB almacenada en el registro de Reporter. La API crea y administra las entradas del registro. Un despliegue de un solo tenant también puede sembrarlas a partir de variables
DATASOURCE_* al iniciar. La extracción de datos es de solo lectura por diseño: Reporter emite sentencias SELECT y consultas find de MongoDB, y no tiene ninguna vía de escritura hacia la base de datos de origen.
Cada entrada tiene dos identificadores. dataSourceId es el UUID que usan las operaciones del registro. configName es el nombre estable que usan las plantillas y los filtros, así que mantenlo estable aunque cambien los hosts y las credenciales. Reporter cifra las contraseñas en reposo con DATASOURCE_CRED_ENC_KEY y nunca las devuelve.
El registro expone siete operaciones: listar, crear, obtener, actualizar parcialmente, eliminar de forma lógica, inspeccionar el esquema activo y probar la conexión. Reporter rechaza la eliminación mientras una plantilla activa siga referenciando la fuente.
Consulta Cómo conectar Reporter con Midaz para ver una configuración de ejemplo.
Informes
Una solicitud de informe indica una plantilla y, de forma opcional, los filtros que acotan los datos subyacentes. Los filtros se anidan en tres niveles (fuente de datos, luego tabla y luego campo), y cada campo lleva una condición:
eq, gt, gte, lt, lte, between, in y nin.
Un informe conserva su propia copia del formato de salida y la descripción que tenía la plantilla en el momento de su creación. Esa instantánea es lo que permite que un artefacto siga siendo descargable en su forma original después de que la plantilla cambie.
Los informes se crean y se conservan. Existen cuatro operaciones: crear uno, obtenerlo por identificador, listarlos y descargar el artefacto de uno finalizado. Un informe y su artefacto permanecen en su lugar una vez creados. La retención es una política de ciclo de vida en el bucket de almacenamiento de objetos, definida por quien opera el despliegue.
Los cuatro estados del informe
La creación es síncrona solo hasta que el trabajo llega a la cola. La operaciónPOST responde 201 Created con un informe que ya está en Processing, y un worker se hace cargo a partir de ahí.
Processing es el único estado de entrada, y nada vuelve a él una vez que el worker resuelve el informe. Una cola puede entregar el mismo comando dos veces, por lo que el worker lee el informe antes de iniciar una ejecución. El worker omite un informe que ya quedó resuelto como Finished o Error, y no lo genera de nuevo.
La operación de descarga entrega el artefacto una vez que un informe está Finished. Sondea GET /v1/reports/{id} hasta que el estado se resuelva, o suscríbete a los eventos terminales que emite Reporter y evita el sondeo.
Plazos
Un plazo modela una obligación: una fecha de vencimiento, una regla de recurrencia y, opcionalmente, la plantilla que la satisface. Su
type es regulatory o custom. Su frequency es once, daily, weekly, monthly, semiannual o annual, y las reglas semestral y anual también llevan los meses en que caen.
Reporter deriva el estado y nunca lo almacena. Un plazo está delivered una vez que alguien lo marca así, overdue una vez que su fecha de vencimiento pasa sin entrega, y pending en cualquier otro caso. Un plazo recurrente avanza al siguiente vencimiento en la primera lectura después de que pasa su fecha de vencimiento. Avanza al siguiente vencimiento solo cuando lleva la marca de entrega. Ese avance borra la marca de entrega, de modo que el registro vuelve a pending para la siguiente ocurrencia, y un solo registro cubre toda la serie.
La notificación funciona por consulta (pull). Una sola operación devuelve los plazos que están dentro de su ventana de alerta, ordenados primero los vencidos, luego los de advertencia y luego los informativos. Reporter no envía correo ni llama a ningún endpoint tuyo.
Consulta Gestión de plazos para conocer el ciclo de vida completo.
Tenants
El tenant es el límite de aislamiento en Reporter. Reporter lo resuelve a partir de la propia solicitud autenticada. El token bearer que autoriza la llamada lleva el tenant en su claim
tenantId. Ninguna operación de la API toma el tenant de un encabezado de la solicitud, y ningún valor proporcionado por el cliente puede ampliar el ámbito de una llamada.
El aislamiento recorre toda la profundidad del stack. Cada tenant tiene su propia base de datos de metadatos, su propio virtual host de message broker, sus propios pools de conexión y su propio outbox de eventos. La resolución es fail-closed. Reporter rechaza una solicitud cuando no puede resolver el tenant, y nada recurre a un pool compartido.
La operación de un solo tenant es la predeterminada y no necesita ninguna configuración de tenant. Consulta Multi-tenancy para conocer el modelo en el nivel de toda la plataforma.
Próximos pasos
Arquitectura
Un binario, dos superficies y la cola entre ellas.
Inicio rápido
Sube una plantilla y genera tu primer informe.
Referencia de plantillas
Las etiquetas, los filtros y las expresiones disponibles para una plantilla.
Gestión de plazos
Crea, rastrea y entrega una obligación de generación de informes.