O modelo em resumo
Templates
Um template é um arquivo
.tpl de texto puro que você envia como multipart/form-data, junto com o formato de saída que ele produz e uma descrição curta. O Reporter guarda o arquivo em object storage e os metadados dele no MongoDB. A linguagem de template é a Pongo2, então um template mistura texto literal do documento com variáveis, laços, condicionais, filtros e tags de agregação.
Um template declara um único formato de saída: PDF, HTML, XML, TXT ou CSV. O PDF é renderizado primeiro como HTML e depois convertido por um pool de workers com navegador headless.
Um template endereça os dados por configName, o nome estável de uma fonte de dados, e por tabela: {{ midaz_onboarding.accounts }}. Quando há mais de um esquema em jogo, qualifique assim: {{ midaz_onboarding:public.accounts }}.
No envio, o Reporter lê o texto do template e deriva os campos que ele toca, por fonte de dados e por tabela. Em seguida confere cada tabela e cada campo referenciado contra o esquema ao vivo daquela fonte de dados. Uma fonte de dados inalcançável produz um aviso em vez de uma recusa, então um template ainda sobe enquanto um banco de dados está fora do ar.
Leia Referência de templates para as tags, os filtros e as expressões que a linguagem oferece.
Fontes de dados
Uma fonte de dados é um banco de dados que o Reporter lê, registrado inteiramente por configuração de ambiente. O Reporter se conecta a PostgreSQL e a MongoDB. O acesso é somente leitura por construção: o caminho de extração emite comandos
SELECT e buscas no MongoDB, e não existe caminho de escrita para uma fonte de dados.
DATASOURCE_<NAME>_CONFIG_NAME é a variável que faz uma fonte de dados existir. O valor dela é o configName que templates e filtros usam, e ele permanece estável enquanto hosts e credenciais mudam ao redor. O resto do bloco fornece a conexão em si.
A superfície de API sobre as fontes de dados também é somente leitura. Você pode listar as fontes configuradas e obter uma pelo identificador, que é como você confirma que uma implantação enxerga a fonte que um template espera. Não há operação de criação, atualização ou exclusão, porque essa decisão pertence ao ambiente.
Leia Conectar o Reporter ao Midaz para uma configuração trabalhada.
Relatórios
Uma requisição de relatório nomeia um template e, opcionalmente, os filtros que restringem os dados por trás dele. Os filtros aninham três níveis — fonte de dados, depois tabela, depois campo — e cada campo carrega uma condição:
eq, gt, gte, lt, lte, between, in e nin.
Um relatório guarda a própria cópia do formato de saída e da descrição que o template carregava quando o relatório foi criado. Esse snapshot é o motivo pelo qual um artefato continua disponível para download no formato original depois que o template segue adiante.
Relatórios são criados e retidos. Existem quatro operações: criar um, obtê-lo pelo identificador, listá-los e baixar o artefato de um concluído. Um relatório e o artefato dele permanecem no lugar depois de criados; a retenção é uma política de ciclo de vida no bucket de object storage, definida por quem opera a implantação.
Os quatro estados de um relatório
A criação é síncrona apenas até o ponto em que o trabalho entra na fila. OPOST responde 201 Created com um relatório já em Processing, e um worker assume dali em diante.
Processing é o único estado de entrada, e nada volta para ele depois que o worker acomoda o relatório. Uma fila pode entregar o mesmo comando duas vezes, então o worker lê o relatório antes de começar uma execução: um que já ficou em Finished ou Error é deixado como está, em vez de gerado de novo.
A operação de download serve o artefato quando um relatório está em Finished. Consulte GET /v1/reports/{id} periodicamente até o estado se acomodar, ou assine os eventos terminais que o Reporter emite e dispense a consulta repetida.
Prazos
Um prazo modela uma obrigação: uma data de vencimento, uma regra de recorrência e, opcionalmente, o template que a cumpre. O
type dele é regulatory ou custom. A frequency dele é once, daily, weekly, monthly, semiannual ou annual, e as regras semestral e anual também carregam os meses em que caem.
O status é derivado, nunca armazenado. Um prazo fica delivered assim que alguém o marca como tal, overdue assim que a data de vencimento passa sem entrega, e pending nos demais casos. Um prazo recorrente avança na primeira leitura depois de a data de vencimento passar, e só se ele tiver sido marcado como entregue. Esse avanço limpa a marca de entrega, então o registro volta para pending na próxima ocorrência e um único registro carrega a série inteira.
A notificação é por consulta. Uma única operação retorna os prazos que estão dentro da janela de alerta deles, ordenados primeiro os vencidos, depois os de aviso e depois os informativos. O Reporter não envia e-mail nem chama nenhum endpoint seu.
Leia Gerenciando prazos para o ciclo de vida completo.
Tenants
O tenant é a fronteira de isolamento no Reporter. O Reporter o resolve a partir da própria requisição autenticada — o token bearer que autoriza a chamada carrega o tenant na claim
tenantId dele. Nenhuma operação da API toma um tenant de um cabeçalho de requisição, e nenhum valor fornecido pelo cliente pode ampliar o escopo de uma chamada.
O isolamento percorre toda a profundidade da stack. Cada tenant recebe o próprio banco de metadados, o próprio virtual host no broker de mensagens, os próprios pools de conexão e o próprio outbox de eventos. A resolução é fail-closed: uma requisição cujo tenant não pode ser resolvido é recusada, e nada cai de volta para um pool compartilhado.
A operação com um único tenant é o padrão e não precisa de nenhuma configuração de tenant. Veja Multi-tenancy para o modelo de toda a plataforma.
Próximos passos
Arquitetura
Um binário, duas superfícies e a fila entre elas.
Início rápido
Envie um template e gere seu primeiro relatório.
Referência de templates
As tags, os filtros e as expressões disponíveis para um template.
Gerenciando prazos
Crie, acompanhe e entregue uma obrigação de reporte.