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 e uma breve descrição. 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 ativo 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 deployment single-tenant 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, 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 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 é o motivo pelo qual um artefato continua 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.
Os quatro estados de um 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á se consolidou como Finished ou Error, e não o gera de novo.
A operação de download serve o artefato assim que um relatório está Finished. 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.
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.
A operação single-tenant é o padrão e não exige nenhuma configuração de tenant. Veja Multi-tenancy para o modelo da 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 template
As tags, filtros e expressões disponíveis para um template.
Gerenciando prazos
Crie, acompanhe e entregue uma obrigação de relatório.