Pular para o conteúdo principal

Documentation Index

Fetch the complete documentation index at: https://docs.lerian.studio/llms.txt

Use this file to discover all available pages before exploring further.

Instituições financeiras precisam gerar relatórios regulatórios, demonstrativos de auditoria e analytics de negócio — muitas vezes com prazos apertados e dados espalhados em múltiplos sistemas. O Reporter automatiza esse processo. Você define templates em texto puro (arquivos .tpl), e o Reporter busca os dados, aplica a lógica e gera o relatório no formato que você precisa. O Reporter é o mecanismo de geração de relatórios source-available da Lerian. O código-fonte está disponível publicamente no GitHub.
Formato do templateFormato de saída
.tpl estruturado como CSVArquivo CSV
.tpl estruturado como XMLArquivo XML
.tpl estruturado como HTMLArquivo HTML ou PDF
.tpl estruturado como TXTArquivo TXT

​
Por que usar o Reporter?

Instituições financeiras dedicam tempo significativo à produção de relatórios recorrentes — para reguladores, auditores e stakeholders internos. O Reporter elimina esse trabalho manual ao permitir que você defina um template uma vez e gere relatórios atualizados automaticamente a partir de dados em tempo real. Para equipes técnicas: em vez de escrever consultas SQL complexas, você referencia domínios, tabelas e campos por meio de placeholders intuitivos. Isso torna a criação de relatórios mais rápida, flexível e fácil de manter.

​
Como funciona

​
Fluxo de trabalho

O Reporter segue um fluxo de trabalho simples e eficiente que transforma seus templates em relatórios prontos para produção:
  1. Envie templates com filtros e parâmetros opcionais
  2. O Reporter recupera os dados dos bancos de dados configurados (PostgreSQL, MongoDB)
  3. A lógica do template é aplicada (loops, condições, cálculos)
  4. A saída final é gerada no formato solicitado
Fluxo de trabalho do Reporter mostrando o processo do template ao relatório renderizado

​
Arquitetura

O Reporter é construído sobre uma arquitetura em camadas que mantém as responsabilidades bem definidas e permite crescimento:
  • Camada de dados: Conecta-se aos bancos de dados por meio de fontes de dados configuradas. Suporta PostgreSQL e MongoDB, com consultas multi-schema para PostgreSQL.
  • Camada de lógica de negócio: Gerencia a análise de templates, resolução de placeholders e renderização.
  • Camada de armazenamento: Armazena templates e relatórios gerados usando armazenamento de objetos compatível com S3 (AWS S3, MinIO ou SeaweedFS).
  • Camada de apresentação: Retorna a saída formatada por meio de APIs RESTful.
Camadas da arquitetura do Reporter mostrando a estrutura dos componentes

​
O que ele pode fazer

  • Consultas dinâmicas com placeholders: Referencie qualquer ponto de dados por caminhos diretos — sem necessidade de SQL.
  • Suporte a multi-schema: Consulte tabelas em múltiplos schemas do PostgreSQL a partir de um único template usando sintaxe explícita de schema.
  • Lógica de loops e condições: Construa conteúdo dinâmico com loops for, condicionais if/elif/else e blocos com escopo definido.
  • Operações matemáticas e agregação: Realize cálculos com sum_by, avg_by, count_by, min_by, max_by, calc e aggregate_balance.
  • Rastreamento de contadores: Rastreie e exiba contadores nomeados ao longo das iterações do template com counter e counter_show.
  • Filtros de transformação de dados: Transforme valores inline com where, sum, count, replace, slice, strip_zeros e percent_of.
  • Processamento assíncrono: Relatórios pesados são processados de forma assíncrona via fila de mensagens.
  • Armazenamento compatível com S3: Templates e relatórios são armazenados em qualquer serviço compatível com S3 (AWS S3, MinIO, SeaweedFS).
  • Múltiplos formatos de saída: Gere saídas em CSV, XML, HTML, TXT ou PDF a partir de um único mecanismo de templates.

​
Modelo de template

O Reporter utiliza templates que espelham a estrutura final do documento. Os arquivos devem ter a extensão .tpl independentemente do formato do conteúdo interno.
Embora o conteúdo do arquivo deva seguir o formato de saída, certifique-se de salvá-lo com a extensão .tpl. Isso é necessário para que o template funcione corretamente.

​
Configurando suas fontes de dados

Antes de gerar relatórios, você precisa configurar as conexões de banco de dados que o Reporter usará para obter dados. O Reporter se conecta aos seus bancos de dados por meio de fontes de dados gerenciadas, configuradas pela API de conexões de banco de dados. Cada fonte de dados representa uma conexão de banco de dados identificada por um nome único (configName), que é usado ao definir placeholders e filtros nos seus templates. Pela API de conexões, você pode:
  • Registrar um ou mais bancos de dados (PostgreSQL ou MongoDB)
  • Testar a conectividade antes de executar relatórios
  • Validar campos de templates contra o schema real do seu banco de dados

​
Nomenclatura recomendada

Para evitar conflitos — especialmente quando bancos de dados diferentes contêm tabelas com os mesmos nomes — use identificadores claros e descritivos. Por exemplo:
  • midaz_onboarding (PostgreSQL)
  • midaz_onboarding_metadata (MongoDB)

​
Validação de schema

Quando você cria ou atualiza um template, o Reporter valida que os campos referenciados nos seus placeholders existam nas fontes de dados configuradas. Se uma fonte de dados estiver temporariamente indisponível durante a validação, o Reporter retorna avisos (não erros), permitindo que você continue com a criação do template.
Campos válidos são confirmados contra o schema real do banco de dados. Fontes de dados indisponíveis geram um aviso com o código DATA_SOURCE_DOWN, não um erro bloqueante. Você pode corrigir problemas de conectividade depois sem perder seu trabalho no template.
Para opções de configuração detalhadas, incluindo variáveis de ambiente e configuração multi-schema, consulte Usando o Reporter — Configurando fontes de dados externas.

​
Usando placeholders

A estrutura dos placeholders segue uma sintaxe baseada em caminhos: 
{{ base.table_or_collection.field_or_document }}
Isso funciona tanto para bancos de dados SQL (tabelas e campos) quanto para MongoDB (coleções e documentos).

​
Placeholders com multi-schema

Quando sua fonte de dados PostgreSQL possui múltiplos schemas, use a sintaxe explícita de schema para evitar ambiguidade: 
{{ base:schema.table.field }}
Por exemplo: 
{{ external_db:sales.orders.total }}
{{ external_db:inventory.items.quantity }}
Se o nome de uma tabela existe em apenas um schema, a sintaxe legada {{ base.table.field }} ainda funciona — o Reporter descobre automaticamente o schema correto. Se uma tabela existe em múltiplos schemas, o Reporter usa por padrão o schema public. Se a tabela não está em public, o Reporter retorna um erro com sugestões:
ambiguous table reference: 'db.orders' exists in multiple schemas: [sales, shipping]
Please use explicit schema syntax:
  {{ db:sales.orders }}
  {{ db:shipping.orders }}

​
Referência de templates e placeholders

O Reporter inclui um amplo conjunto de tags de template para agregação (sum_by, avg_by, count_by, min_by, max_by), aritmética (calc), agrupamento financeiro (aggregate_balance), contadores e formatação de data/hora. Também fornece filtros para manipulação de strings, cálculo de porcentagens e operações com arrays. Para a referência completa, consulte Referência de templates. Para filtragem avançada de relatórios com operadores como eq, gt, between, in e mais, consulte a seção de Filtragem avançada.

​
Precisa de inspiração?

Confira a página de Exemplos de templates para explorar o que você pode fazer e começar a criar seu próprio template.

​
Autenticação e autorização

O Reporter não exige autenticação por padrão, mas é desenvolvido com integração nativa ao Access Manager. Quando habilitado, o Access Manager fornece controle de acesso baseado em papéis (RBAC) para templates, relatórios e fontes de dados — oferecendo controle granular sobre quem pode visualizar, criar ou gerenciar recursos de relatórios.
O Access Manager é uma funcionalidade opcional disponível no modelo Enterprise. Para detalhes sobre como habilitá-lo, consulte a documentação do Access Manager.

​
Próximos passos

Explorar a API do Reporter

Consulte endpoints para templates, relatórios e fontes de dados.

Usando o Reporter

Aprenda a criar e enviar seu primeiro template de relatório.