> ## 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.

# Conceitos essenciais do Reporter

> O modelo do Reporter em um só lugar: templates, fontes de dados, relatórios, prazos, instituições, remessas regulatórias, os estados de relatório e o limite de tenant que os separa.

O Reporter tem um modelo pequeno. Você envia um **template** que descreve um documento. Um operador configura as **fontes de dados** que o Reporter pode ler. Você solicita um **relatório** com base em um template, e o Reporter renderiza um artefato que você baixa. Um **prazo** acompanha quando um relatório vence e se alguém o entregou.

Esta página define cada termo e as regras que os conectam.

## O modelo em resumo

***

| Conceito | Definição |
| - | - |
| Template | Uma definição de documento em texto simples, enviada como arquivo, que declara um formato de saída. |
| Fonte de dados | Uma conexão de banco de dados persistente e somente leitura que um operador gerencia pela API ou popula na inicialização. |
| Relatório | Uma renderização de um template, segundo os filtros solicitados. |
| Artefato | O arquivo que um relatório concluído produz, armazenado no armazenamento de objetos. |
| Filtro | Uma condição por campo que restringe as linhas que um relatório lê. |
| Prazo | Uma data de vencimento e uma regra de recorrência, opcionalmente vinculada a um template. |
| Instituição | Uma entidade regulada com um CNPJ, e as linhas de cada fonte de dados que pertencem a ela. |
| Remessa regulatória | Um relatório de um documento regulatório curado que uma pessoa corrige e aprova. |
| Tenant | O limite de isolamento. Cada operação resolve exatamente um. |

## 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](https://docs.lerian.studio/pt/products/reporter/template-reference.md) 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](https://docs.lerian.studio/pt/products/reporter/connecting-reporter-to-midaz.md) 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):

```json theme={null}
{
  "templateId": "0198c0f6-6d4d-7a34-a9ba-2c2b3ad2f1a0",
  "filters": {
    "midaz_onboarding": {
      "accounts": {
        "status": { "in": ["ACTIVE"] },
        "type": { "nin": ["internal"] }
      }
    }
  }
}
```

Existem doze operadores: `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ção `POST` responde `201 Created` com um relatório já em `Processing`, e um worker assume a partir daí.

| Estado | Significado |
| - | - |
| `Processing` | Aceito e enfileirado. O worker ainda não terminou. |
| `Finished` | Toda seção de dados teve sucesso e o artefato está armazenado. |
| `Partial` | Algumas seções de dados falharam. O relatório registra quais, por seção, para que você corrija essas fontes de dados e gere o relatório de novo. |
| `Error` | Toda seção tentada falhou, a requisição nunca chegou ao worker, ou o worker parou de enviar heartbeats. |
| `Draft` | Uma remessa regulatória foi gerada e aguarda revisão. |
| `Final` | Uma pessoa aprovou o rascunho regulatório. |

`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](https://docs.lerian.studio/pt/products/reporter/managing-deadlines.md) 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](https://docs.lerian.studio/pt/products/reporter/reporter-rest-api.md#regulatory-filing) 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

***

> [card] [Arquitetura](https://docs.lerian.studio/pt/products/reporter/reporter-architecture.md)
>
> Um binário, duas superfícies e a fila entre elas.

> [card] [Início rápido](https://docs.lerian.studio/pt/products/reporter/reporter-quick-start.md)
>
> Envie um template e gere seu primeiro relatório.

> [card] [Referência de template](https://docs.lerian.studio/pt/products/reporter/template-reference.md)
>
> As tags, filtros e expressões disponíveis para um template.

> [card] [Gerenciando prazos](https://docs.lerian.studio/pt/products/reporter/managing-deadlines.md)
>
> Crie, acompanhe e entregue uma obrigação de relatório.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.