O modelo em resumo
Templates
Um template é um arquivo
.tpl em texto simples que você envia como multipart/form-data, junto com o formato de saída que ele produz, uma breve descrição e sua categoria. A categoria é a família de relatório pela qual um consumidor roteia. O Reporter guarda o arquivo no armazenamento de objetos e seus metadados no MongoDB. A linguagem do template é Pongo2, então um template mistura texto literal do documento com variáveis, loops, condicionais, filtros e tags de agregação.
Um template declara um formato de saída: PDF, HTML, XML, TXT ou CSV. O PDF é renderizado primeiro como HTML e depois convertido por um pool de navegadores headless.
Um template endereça dados pelo configName, o nome estável de uma fonte de dados, e pela tabela: {{ midaz_onboarding.accounts }}. Quando mais de um schema está em jogo, qualifique como {{ 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, verifica cada tabela e campo referenciados contra o schema dessa fonte de dados. Uma fonte de dados inacessível gera um aviso em vez de uma rejeição, então um template ainda é enviado enquanto um banco de dados está fora do ar.
Leia Referência de template para as tags, filtros e expressões que a linguagem oferece.
Fontes de dados
Uma fonte de dados é uma conexão PostgreSQL ou MongoDB armazenada no registro do Reporter. A API cria e gerencia as entradas do registro. Um deploy self-hosted também pode populá-las a partir de variáveis
DATASOURCE_* na inicialização. A extração de dados permanece somente leitura por construção: o Reporter emite instruções SELECT e finds do MongoDB, e não tem caminho de escrita para o banco de dados de origem.
Cada entrada tem dois identificadores. O dataSourceId é o UUID que as operações do registro usam. O configName é o nome estável que templates e filtros usam, então mantenha-o estável enquanto hosts e credenciais mudam. O Reporter criptografa senhas em repouso com DATASOURCE_CRED_ENC_KEY e nunca as retorna.
O registro expõe sete operações: listar, criar, obter, atualizar parcialmente, fazer exclusão reversível, inspecionar o schema ativo e testar a conexão. O Reporter recusa a exclusão enquanto um template ativo ainda referenciar a fonte.
Leia Conectando o Reporter ao Midaz para uma configuração completa.
Relatórios
Uma requisição de relatório nomeia um template e os filtros que restringem os dados por trás dele. Envie um objeto
filters vazio quando não precisar de nenhum. Os filtros aninham três níveis (fonte de dados, depois tabela, depois campo):
eq, gt, gte, lt, lte, between, in, nin, startsWith, notStartsWith, isNull e notNull.
Um relatório mantém sua própria cópia do formato de saída e da descrição que o template carregava no momento da criação. Esse snapshot mantém um artefato disponível para download no formato original depois que o template muda.
Relatórios seguem o modelo criar-e-reter. Existem quatro operações: criar um, obtê-lo pelo identificador, listá-los e baixar o artefato de um relatório concluído. Um relatório e seu artefato permanecem no lugar depois de criados. A retenção é uma política de ciclo de vida no bucket de armazenamento de objetos, definida por quem opera o deployment.
Estados de relatório
A criação é síncrona apenas até o trabalho chegar à fila. A operaçãoPOST responde 201 Created com um relatório já em Processing, e um worker assume a partir daí.
Processing é o único estado de entrada, e nada retorna a ele depois que o worker consolida o relatório. Uma fila pode entregar o mesmo comando duas vezes, então o worker lê o relatório antes de iniciar uma execução. O worker pula um relatório que já chegou a um status terminal, e não o gera de novo.
A operação de download serve o artefato de um relatório Finished ou Final, e de um Draft sem campo obrigatório em branco. Faça polling em GET /v1/reports/{id} até o estado se consolidar, ou inscreva-se nos eventos terminais que o Reporter emite e dispense o polling.
Prazos
Um prazo modela uma obrigação: uma data de vencimento, uma regra de recorrência e, opcionalmente, o template que a cumpre. Seu
type é regulatory ou custom. Sua frequency é once, daily, weekly, monthly, semiannual ou annual, e as regras semianual e anual também carregam os meses em que caem.
O Reporter deriva o status e nunca o armazena. Um prazo fica delivered assim que alguém o marca assim, overdue assim que a data de vencimento passa sem entrega, e pending nos demais casos. Um prazo recorrente avança na primeira leitura depois que sua data de vencimento passa. Ele avança apenas quando carrega a marca de entrega. Esse avanço limpa a marca de entrega, então o registro volta a pending para a próxima ocorrência, e um único registro carrega toda a série.
A notificação é por consulta. Uma única operação retorna os prazos dentro da janela de alerta deles, ordenados com os vencidos primeiro, depois os de aviso, depois os informativos. O Reporter não envia e-mail nem chama nenhum endpoint seu.
Leia Gerenciando prazos para o ciclo de vida completo.
Instituições e remessas regulatórias
Uma instituição é uma entidade regulada de um tenant, identificada pelo seu CNPJ. O escopo dela nomeia as linhas que pertencem a ela em cada fonte de dados. Um relatório lê para uma instituição, ou para
all.
Uma remessa regulatória começa a partir de um documento curado que o deployment carrega. O tenant se inscreve no documento e mapeia os campos dele para tabelas em um mapeamento YAML. O mapeamento começa pelo mapeamento de referência da Lerian quando o catálogo publica um, ou por um mapeamento em branco.
Uma consulta do mapeamento lê fontes de dados PostgreSQL ou MongoDB. Qualquer consulta pode fazer join com outras tabelas e calcular colunas. No MongoDB, uma consulta também pode ler campos aninhados e transformar cada item de uma lista em uma linha. Quando o contrato do documento permite, um conjunto lê de mais de uma fonte de dados, e as regras do contrato combinam as linhas delas. Você pode ver previamente as linhas de uma consulta antes de salvar o mapeamento.
Cada geração produz um Draft. Uma pessoa corrige o rascunho campo a campo, e uma pessoa com a permissão de aprovação o torna Final. A remessa mantém um registro de proveniência da versão do documento, do mapeamento, dos parâmetros e do SHA-256 do arquivo.
Cada remessa também registra o seu período e, quando o contrato do documento declara um, o seu tipo de remessa: original ou substituição. Uma remessa que não está Final nomeia, em supersededBy, a geração do seu período que prevalece no lugar dela. Quando o contrato exige, o Reporter recusa uma remessa de um período que não terminou no calendário de relatórios, ou de um dia que não é dia útil. Veja API REST do Reporter para as operações.
Tenants
O tenant é o limite de isolamento no Reporter. O Reporter o resolve a partir da própria requisição autenticada. O bearer token que autoriza a chamada carrega o tenant na claim
tenantId. Nenhuma operação da API obtém o tenant de um header 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 seu próprio banco de dados de metadados, seu próprio virtual host do message broker, seus próprios pools de conexão e seu próprio outbox de eventos. A resolução é fail-closed. O Reporter rejeita uma requisição quando não consegue resolver o tenant, e nada recorre a um pool compartilhado.
Um deploy self-hosted não exige nenhuma configuração de tenant.
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 template
As tags, filtros e expressões disponíveis para um template.
Gerenciando prazos
Crie, acompanhe e entregue uma obrigação de relatório.