El modelo de un vistazo
Plantillas
Una plantilla es un archivo
.tpl de 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 almacenamiento de objetos y sus metadatos en MongoDB. El lenguaje de plantillas es Pongo2, así que una plantilla mezcla texto literal del documento con variables, bucles, condicionales, filtros y etiquetas de agregación.
Una plantilla declara un solo formato de salida: PDF, HTML, XML, TXT o CSV. El PDF se renderiza primero como HTML y después se convierte a través de un pool de workers con navegador headless.
Una plantilla direcciona los datos por configName, el nombre estable de una fuente de datos, y por tabla: {{ midaz_onboarding.accounts }}. Cuando hay más de un esquema en juego, califícalo como {{ midaz_onboarding:public.accounts }}.
Al subirla, Reporter lee el texto de la plantilla y deriva los campos que toca, por fuente de datos y por tabla. Después contrasta cada tabla y cada campo referenciado con el esquema en vivo de esa fuente de datos. Una fuente de datos inalcanzable produce una advertencia en lugar de un rechazo, así que una plantilla se sube igual mientras una base de datos está caída.
Lee Referencia de plantillas para las etiquetas, los filtros y las expresiones que ofrece el lenguaje.
Fuentes de datos
Una fuente de datos es una base de datos que Reporter lee, registrada por completo mediante configuración de entorno. Reporter se conecta a PostgreSQL y a MongoDB. El acceso es de solo lectura por construcción: el camino de extracción emite sentencias
SELECT y búsquedas de MongoDB, y no existe ningún camino de escritura hacia una fuente de datos.
DATASOURCE_<NAME>_CONFIG_NAME es la variable que hace que una fuente de datos exista. Su valor es el configName que usan las plantillas y los filtros, y se mantiene estable mientras los hosts y las credenciales cambian a su alrededor. El resto del bloque aporta la conexión en sí.
La superficie de API sobre las fuentes de datos también es de solo lectura. Puedes listar las fuentes configuradas y obtener una por identificador, que es como confirmas que un despliegue ve la fuente que espera una plantilla. No hay operación de creación, actualización ni eliminación, porque esa decisión pertenece al entorno.
Lee Conectar Reporter a Midaz para una configuración trabajada.
Informes
Una solicitud de informe nombra una plantilla y, opcionalmente, los filtros que reducen los datos detrás de ella. Los filtros anidan tres niveles — fuente de datos, después tabla, después campo — y cada campo lleva una condición:
eq, gt, gte, lt, lte, between, in y nin.
Un informe guarda su propia copia del formato de salida y de la descripción que llevaba la plantilla cuando el informe se creó. Ese snapshot es la razón por la que un artefacto sigue descargable en su forma original después de que la plantilla siga su camino.
Los informes se crean y se conservan. Existen cuatro operaciones: crear uno, obtenerlo por identificador, listarlos y descargar el artefacto de uno terminado. Un informe y su artefacto permanecen en su lugar una vez creados; la retención es una política de ciclo de vida sobre el bucket de almacenamiento de objetos, definida por quien opera el despliegue.
Los cuatro estados de un informe
La creación es síncrona solo hasta el punto en que el trabajo queda encolado.POST responde 201 Created con un informe ya en Processing, y un worker lo toma desde ahí.
Processing es el único estado de entrada, y nada vuelve a él una vez que el worker asienta el informe. Una cola puede entregar el mismo comando dos veces, así que el worker lee el informe antes de empezar una ejecución: uno que ya quedó en Finished o Error se deja como está, en lugar de generarse de nuevo.
La operación de descarga sirve el artefacto una vez que un informe está en Finished. Consulta GET /v1/reports/{id} de forma periódica hasta que el estado se asiente, o suscríbete a los eventos terminales que emite Reporter y sáltate 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 los que caen.
El estado es derivado, nunca almacenado. 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 en la primera lectura posterior a su fecha de vencimiento, y solo si quedó marcado como entregado. Ese avance limpia la marca de entrega, así que el registro vuelve a pending para la siguiente ocurrencia y un solo registro lleva toda la serie.
La notificación es por consulta. Una única operación devuelve los plazos que están dentro de su ventana de alerta, ordenados primero los vencidos, después los de aviso y después los informativos. Reporter no envía correo ni llama a ningún endpoint tuyo.
Lee Gestión de plazos para el ciclo de vida completo.
Tenants
El tenant es el límite de aislamiento en Reporter. Reporter lo resuelve desde 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 un tenant de una cabecera de solicitud, y ningún valor que envíe el cliente puede ampliar el alcance de una llamada.
El aislamiento recorre toda la profundidad del stack. Cada tenant recibe su propia base de datos de metadatos, su propio virtual host del broker de mensajes, sus propios pools de conexiones y su propio outbox de eventos. La resolución falla cerrada: una solicitud cuyo tenant no se puede resolver se rechaza, y nada recurre a un pool compartido.
La operación con un solo tenant es el valor por defecto y no necesita ninguna configuración de tenant. Consulta Multi-tenancy para el modelo 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, sigue y entrega una obligación de reporte.