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, una descripción breve y su categoría. La categoría es la familia de informe por la que un consumidor enruta. 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 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 self-hosted 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 los filtros que acotan los datos subyacentes. Envía un objeto
filters vacío cuando no necesites ninguno. Los filtros se anidan en tres niveles (fuente de datos, luego tabla y luego campo):
eq, gt, gte, lt, lte, between, in, nin, startsWith, notStartsWith, isNull y notNull.
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 mantiene un artefacto 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.
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 llegó a un estado terminal, y no lo genera de nuevo.
La operación de descarga entrega el artefacto de un informe Finished o Final, y de un Draft sin campo obligatorio en blanco. 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.
Instituciones y presentaciones regulatorias
Una institución es una entidad regulada de un tenant, identificada por su CNPJ. Su alcance nombra las filas que le pertenecen en cada fuente de datos. Un informe lee para una institución, o para
all.
Una presentación regulatoria parte de un documento curado que incluye el despliegue. El tenant se suscribe al documento y asigna sus campos a tablas en un mapeo YAML. El mapeo parte del mapeo de referencia de Lerian cuando el catálogo publica uno, o de un mapeo en blanco.
Una consulta del mapeo lee fuentes de datos PostgreSQL o MongoDB. Cualquier consulta puede hacer join con otras tablas y calcular columnas. En MongoDB, una consulta también puede leer campos anidados y convertir cada elemento de una lista en una fila. Cuando el contrato del documento lo permite, un conjunto lee de más de una fuente de datos, y las reglas del contrato combinan sus filas. Puedes previsualizar las filas de una consulta antes de guardar el mapeo.
Cada generación produce un Draft. Una persona corrige el borrador campo por campo, y una persona con el permiso de aprobación lo convierte en Final. La presentación conserva un registro de procedencia de la versión del documento, el mapeo, los parámetros y el SHA-256 del archivo.
Cada presentación también registra su período y, cuando el contrato del documento declara uno, su tipo de remesa: original o sustitución. Una presentación que no está en Final nombra, en supersededBy, la generación de su período que prevalece en su lugar. Cuando el contrato lo exige, Reporter rechaza una presentación de un período que no terminó en el calendario de informes, o de un día que no es hábil. Consulta API REST de Reporter para ver las operaciones.
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.
Un despliegue self-hosted no necesita ninguna configuración de tenant.
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.