# Especificação Funcional Oficial do Módulo de Relatórios da Ktalogu

Documento oficial do módulo de `Relatórios` da Ktalogu.

Esta especificação é a referência funcional para desenvolvimento, testes, auditoria, homologação e evolução futura.

Nenhuma implementação deve ser iniciada sem aderência a este documento.

## 1. Visão Geral

### Objetivo do módulo

O módulo de `Relatórios` existe para transformar dados operacionais da Ktalogu em informação confiável para decisão financeira, comercial, gerencial e analítica.

O módulo deve oferecer visão executiva e analítica sobre:

- vendas realizadas;
- recebimentos efetivos;
- carteira a receber;
- inadimplência;
- desempenho de clientes;
- desempenho de produtos;
- relatórios personalizados controlados.

O módulo não deve apenas "mostrar números"; ele deve preservar a integridade conceitual entre `pedido`, `recebimento`, `carteira` e `caixa`.

### Público-alvo

- Sócios e diretoria.
- Gestores financeiros.
- Gestores comerciais.
- Gestores de produtos, compras e produção.
- Vendedores com acesso analítico.
- Usuários administrativos autorizados.
- Auditores internos ou externos, quando aplicável.

### Decisões de negócio que o módulo suporta

- Avaliar evolução de vendas e faturamento.
- Avaliar recebimento real e liquidez.
- Medir carteira em aberto e inadimplência.
- Definir prioridades de cobrança.
- Acompanhar conversão comercial de orçamentos.
- Identificar clientes prioritários e clientes em risco de inatividade.
- Identificar produtos com maior e menor giro.
- Avaliar margem e rentabilidade por produto.
- Apoiar decisões de mix, preço, estoque e foco comercial.
- Apoiar fechamento gerencial com evidência exportável e auditável.

### Princípios de negócio obrigatórios

- `Faturamento` é indicador comercial.
- `Recebido` é indicador financeiro por caixa.
- `Contas a Receber` é indicador financeiro por competência.
- `Fluxo de Caixa` é indicador de movimentação financeira efetiva.
- `Pedidos`, `Recebimentos`, `Contas a Receber` e `Fluxo de Caixa` não podem ser misturados sem reconciliação explícita.
- Todo indicador deve ter uma fonte oficial, uma data oficial, uma fórmula oficial, regras formais de exclusão e comportamento padronizado para cancelamento, estorno, parcelamento e múltiplas formas de pagamento.

### Limitações conhecidas

- O módulo não substitui conciliação contábil completa.
- O módulo não substitui DRE contábil oficial.
- O módulo depende da integridade das rotinas que atualizam `orders`, `accounts_receivable`, `receivable_receipts` e `cash_flow`.
- Margem por produto só é auditável se o custo oficial do produto estiver corretamente modelado.
- Comparações entre comercial e financeiro devem ser tratadas como conciliação, não como igualdade automática no mesmo período.

## 2. Estrutura das Abas

### Financeiro

**Objetivo**

Exibir a visão oficial financeira do período com foco em liquidação, carteira, inadimplência e caixa.

**KPIs exibidos**

- `Valor Recebido`
- `Contas a Receber`
- `Contas em Atraso`
- `Fluxo de Caixa Líquido`

**Gráficos exibidos**

- `Recebimentos por período`
- `Fluxo de caixa por período`
- `Distribuição do recebido por forma de pagamento`
- `Carteira por status`

**Tabela exibida**

- Tabela analítica de movimentações financeiras.

**Filtros disponíveis**

- Período
- Cliente
- Forma de pagamento
- Status financeiro
- Conta bancária
- Categoria financeira
- Canal financeiro, quando aplicável

**Exportações permitidas**

- PDF
- Excel
- CSV
- Impressão

### Vendas

**Objetivo**

Exibir a visão comercial oficial do período com foco em pedidos válidos, faturamento, ticket e conversão.

**KPIs exibidos**

- `Faturamento Total`
- `Ticket Médio`
- `Conversão de Orçamentos`
- `Total de Pedidos Válidos`

**Gráficos exibidos**

- `Faturamento por período`
- `Conversão de orçamentos`
- `Ranking de clientes por faturamento`
- `Faturamento por vendedor` ou `por canal`, conforme configuração

**Tabela exibida**

- Tabela analítica de pedidos válidos.

**Filtros disponíveis**

- Período
- Cliente
- Vendedor
- Canal
- Status comercial válido
- Forma de pagamento apenas como atributo analítico, sem alterar faturamento

**Exportações permitidas**

- PDF
- Excel
- CSV
- Impressão

### Produtos

**Objetivo**

Exibir a performance do portfólio no período com foco em giro, receita, margem e lacunas de venda.

**KPIs exibidos**

- `Produtos Mais Vendidos`
- `Produtos Menos Vendidos`
- `Produtos Sem Venda`
- `Margem por Produto`

**Gráficos exibidos**

- `Top produtos por quantidade`
- `Top produtos por receita`
- `Participação por categoria`
- `Curva ABC`

**Tabela exibida**

- Tabela analítica de produtos com quantidade, receita, lucro, margem e status de venda.

**Filtros disponíveis**

- Período
- Categoria
- Produto
- Fornecedor
- Canal
- Vendedor, quando fizer sentido analítico

**Exportações permitidas**

- PDF
- Excel
- CSV
- Impressão

### Clientes

**Objetivo**

Exibir a dinâmica da base de clientes com foco em aquisição, atividade, inatividade e valor comprado.

**KPIs exibidos**

- `Clientes Ativos`
- `Clientes Inativos`
- `Novos Clientes`
- `Ticket Médio por Cliente`

**Gráficos exibidos**

- `Novos clientes por período`
- `Ativos vs Inativos`
- `Ranking de clientes por faturamento`
- `Distribuição por praça` quando aplicável

**Tabela exibida**

- Tabela analítica de clientes com atividade, valor comprado, quantidade de pedidos e última compra.

**Filtros disponíveis**

- Período
- Cidade
- Estado
- Cliente
- Vendedor
- Canal

**Exportações permitidas**

- PDF
- Excel
- CSV
- Impressão

### Personalizados

**Objetivo**

Permitir exploração controlada de dados certificados a partir das fontes oficiais aprovadas.

**KPIs exibidos**

- Derivados da configuração escolhida e limitados ao universo selecionado.

**Gráficos exibidos**

- Ranking
- Série temporal
- Colunas
- Donut
- Compare
- Apenas para combinações permitidas pela governança do módulo.

**Tabela exibida**

- Tabela analítica personalizada conforme campos aprovados.

**Filtros disponíveis**

- Dependem do universo escolhido:
  - `Comercial`
  - `Financeiro Caixa`
  - `Financeiro Carteira`
  - `Clientes`
  - `Produtos`

**Exportações permitidas**

- PDF
- Excel
- CSV
- Impressão

## 3. Dicionário de Indicadores

### Faturamento Total

- **Descrição:** soma do valor vendido em pedidos comercialmente válidos no período.
- **Fórmula:** `sum(order.total_amount)` para pedidos válidos no período.
- **Fonte oficial:** Comercial.
- **Tabelas utilizadas:** `orders`.
- **Campos utilizados:** `orders.id`, `orders.total_amount`, `orders.status`, `orders.created_at` ou `orders.closed_at`, se existir e for oficial.
- **Regras de exclusão:** excluir pedidos cancelados, rascunhos, testes e registros inválidos.
- **Regras de cancelamento:** pedido cancelado não entra.
- **Regras de estorno:** estorno financeiro não altera faturamento comercial.
- **Regras de parcelamento:** não altera faturamento.
- **Exemplo prático:** três pedidos válidos de R$ 1.000, R$ 500 e R$ 700 no período geram `Faturamento Total = R$ 2.200`, mesmo que apenas R$ 900 tenham sido recebidos.

### Valor Recebido

- **Descrição:** soma dos recebimentos efetivamente liquidados no período.
- **Fórmula:** `sum(receivable_receipts.amount)` no período, deduzindo estornos quando a visão oficial for líquida.
- **Fonte oficial:** Financeiro Caixa.
- **Tabelas utilizadas:** `receivable_receipts` e `cash_flow` para reconciliação.
- **Campos utilizados:** `receivable_receipts.id`, `receivable_receipts.receivable_id`, `receivable_receipts.amount`, `receivable_receipts.received_at`, `receivable_receipts.payment_method`, `cash_flow.origin`, `cash_flow.type`, `cash_flow.amount`, `cash_flow.date`.
- **Regras de exclusão:** excluir recebimentos estornados, anulados ou inválidos.
- **Regras de cancelamento:** cancelamento comercial não remove recebimento passado; só deixa de compor o líquido se houver estorno financeiro formal.
- **Regras de estorno:** se a visão oficial for líquida, o estorno reduz o recebido.
- **Regras de parcelamento:** cada liquidação parcial entra pela sua data.
- **Regras de múltiplas formas de pagamento:** o total deve ser rateado por forma de pagamento conforme cada liquidação.
- **Exemplo prático:** um título de R$ 1.200 recebeu R$ 400 em Pix em 05/06 e R$ 800 em cartão em 15/06. Em junho, `Valor Recebido = R$ 1.200`, sendo R$ 400 em Pix e R$ 800 em cartão.

### Contas a Receber

- **Descrição:** saldo em aberto da carteira de recebíveis na data de corte.
- **Fórmula:** `sum(max(0, total_amount - paid_amount))` para títulos abertos na data de corte.
- **Fonte oficial:** Financeiro Competência.
- **Tabelas utilizadas:** `accounts_receivable`.
- **Campos utilizados:** `accounts_receivable.id`, `accounts_receivable.total_amount`, `accounts_receivable.paid_amount`, `accounts_receivable.status`, `accounts_receivable.due_date`.
- **Regras de exclusão:** excluir títulos cancelados e quitados integralmente.
- **Regras de cancelamento:** título cancelado sai da carteira.
- **Regras de estorno:** se um recebimento foi estornado e reabriu saldo, o saldo volta a entrar.
- **Regras de parcelamento:** cada parcela deve ter saldo próprio, se modelada como títulos separados.
- **Exemplo prático:** dois títulos em aberto: R$ 1.000 com R$ 300 pagos e R$ 500 sem pagamento. `Contas a Receber = R$ 1.200`.

### Contas em Atraso

- **Descrição:** parcela da carteira a receber cujo vencimento já passou e que ainda possui saldo aberto.
- **Fórmula:** `sum(max(0, total_amount - paid_amount))` para títulos com `due_date < data_corte`.
- **Fonte oficial:** Financeiro Competência.
- **Tabelas utilizadas:** `accounts_receivable`.
- **Campos utilizados:** `accounts_receivable.total_amount`, `accounts_receivable.paid_amount`, `accounts_receivable.status`, `accounts_receivable.due_date`.
- **Regras de exclusão:** excluir títulos não vencidos, pagos e cancelados.
- **Regras de cancelamento:** título cancelado não entra.
- **Regras de estorno:** se o estorno reabre saldo de título vencido, o saldo volta para atraso.
- **Regras de parcelamento:** cada parcela vencida é analisada individualmente.
- **Exemplo prático:** um título de R$ 900 vencido, com R$ 200 pagos, gera R$ 700 em atraso.

### Fluxo de Caixa Líquido

- **Descrição:** resultado líquido das entradas menos saídas no período.
- **Fórmula:** `sum(cash_flow.amount where type='IN') - sum(cash_flow.amount where type='OUT')`
- **Fonte oficial:** Financeiro Caixa.
- **Tabelas utilizadas:** `cash_flow`.
- **Campos utilizados:** `cash_flow.id`, `cash_flow.type`, `cash_flow.amount`, `cash_flow.date`, `cash_flow.origin`, `cash_flow.bank_account_id`.
- **Regras de exclusão:** excluir lançamentos de teste e inconsistentes.
- **Regras de cancelamento:** cancelamento comercial não altera fluxo passado sem estorno financeiro correspondente.
- **Regras de estorno:** estorno entra como saída reversa ou ajuste formal.
- **Exemplo prático:** entradas de R$ 5.000 e saídas de R$ 3.200 no período geram `Fluxo de Caixa Líquido = R$ 1.800`.

### Ticket Médio

- **Descrição:** valor médio por pedido comercialmente válido no período.
- **Fórmula:** `sum(order.total_amount) / count(distinct order.id)`
- **Fonte oficial:** Comercial.
- **Tabelas utilizadas:** `orders`.
- **Campos utilizados:** `orders.id`, `orders.total_amount`, `orders.status`, `orders.created_at` ou data comercial oficial.
- **Regras de exclusão:** excluir pedidos cancelados, pedidos em rascunho e pedidos técnicos sem valor comercial.
- **Exemplo prático:** quatro pedidos válidos somando R$ 8.000 geram `Ticket Médio = R$ 2.000`.

### Conversão de Orçamentos

- **Descrição:** percentual de orçamentos elegíveis que se transformaram em pedido.
- **Fórmula:** `count(quotes convertidos em pedido) / count(quotes elegíveis)`
- **Fonte oficial:** Comercial.
- **Tabelas utilizadas:** `quotes`, `orders`.
- **Campos utilizados:** `quotes.id`, `quotes.status`, `quotes.created_at`, `orders.quote_id`, `orders.id`, `orders.status`.
- **Regras de exclusão:** excluir `draft` e orçamentos de teste.
- **Exemplo prático:** 100 orçamentos elegíveis no período, 18 convertidos em pedido. `Conversão = 18%`.

### Ranking de Clientes

- **Descrição:** ordenação dos clientes pelo valor comprado no período.
- **Fórmula:** `sum(order.total_amount)` por `client_id`
- **Fonte oficial:** Comercial.
- **Tabelas utilizadas:** `orders`, `clients`.
- **Campos utilizados:** `orders.client_id`, `orders.total_amount`, `orders.status`, `clients.id`, `clients.name`, `clients.company_name`.
- **Regras de exclusão:** excluir pedidos cancelados e clientes sem compra no período.
- **Exemplo prático:** Cliente A comprou R$ 12.000 e Cliente B comprou R$ 8.500. O ranking coloca A acima de B.

### Produtos Mais Vendidos

- **Descrição:** produtos com maior saída no período.
- **Fórmula:** `sum(order_items.quantity)` por produto.
- **Fonte oficial:** Comercial.
- **Tabelas utilizadas:** `order_items`, `orders`, `products`.
- **Campos utilizados:** `order_items.product_id`, `order_items.quantity`, `order_items.line_total`, `orders.id`, `orders.status`, `products.id`, `products.name`.
- **Regras de exclusão:** excluir itens de pedidos cancelados.
- **Exemplo prático:** Produto X vendeu 120 unidades e Produto Y vendeu 80. Produto X lidera o ranking.

### Produtos Menos Vendidos

- **Descrição:** produtos com venda positiva, porém com menor saída no período.
- **Fórmula:** `sum(order_items.quantity) > 0`, ordenado de forma ascendente.
- **Fonte oficial:** Comercial.
- **Tabelas utilizadas:** `order_items`, `orders`, `products`.
- **Exemplo prático:** Produto Z vendeu 1 unidade no período e é o menos vendido entre os que venderam.

### Produtos Sem Venda

- **Descrição:** produtos ativos que não tiveram nenhuma venda válida no período.
- **Fórmula:** `produtos ativos - produtos com ao menos um item em pedido válido`
- **Fonte oficial:** Comercial.
- **Tabelas utilizadas:** `products`, `order_items`, `orders`.
- **Exemplo prático:** 300 produtos ativos, 180 com venda no período. `Produtos Sem Venda = 120`.

### Margem por Produto

- **Descrição:** lucro relativo gerado por produto no período.
- **Fórmula:** `((receita do produto - custo do produto) / receita do produto) * 100`
- **Fonte oficial:** Comercial Gerencial.
- **Tabelas utilizadas:** `order_items`, `orders`, `products`, tabela de custo oficial, se existir.
- **Regras de exclusão:** excluir itens de pedidos cancelados e itens sem custo oficial.
- **Exemplo prático:** produto com receita de R$ 10.000 e custo de R$ 6.000 gera `Margem = 40%`.

### Clientes Ativos

- **Descrição:** clientes com pelo menos uma compra válida no período.
- **Fórmula:** `count(distinct client_id)` com ao menos um pedido válido no período.
- **Fonte oficial:** Comercial CRM.
- **Tabelas utilizadas:** `orders`, `clients`.
- **Exemplo prático:** 86 clientes compraram no mês. `Clientes Ativos = 86`.

### Clientes Inativos

- **Descrição:** clientes da base cuja última compra válida ocorreu antes da janela oficial de inatividade.
- **Fórmula:** `count(clientes cuja última compra válida < data_corte - janela_inatividade)`
- **Fonte oficial:** Comercial CRM.
- **Tabelas utilizadas:** `clients`, `orders`.
- **Exemplo prático:** com janela de 90 dias, clientes sem compra válida há mais de 90 dias entram como inativos.

### Novos Clientes

- **Descrição:** clientes cuja primeira compra válida ocorreu no período.
- **Fórmula:** `count(clientes cujo primeiro pedido válido está dentro do período)`
- **Fonte oficial:** Comercial CRM.
- **Tabelas utilizadas:** `clients`, `orders`.
- **Exemplo prático:** cliente cadastrado há 2 anos, mas cuja primeira compra válida ocorreu em junho, conta como novo cliente de junho.

## 4. Dicionário de Gráficos

| Gráfico | Objetivo | Tipo | Fonte dos dados | Método de agregação | Ordenação | Período | Comportamento sem dados |
|---|---|---|---|---|---|---|---|
| Recebimentos por período | Mostrar a evolução do valor recebido ao longo do período selecionado | Colunas | `receivable_receipts` | Soma do valor recebido por período | Cronológica ascendente pela chave de período | Diário, semanal ou mensal conforme janela | `Sem recebimentos no período` |
| Fluxo de caixa por período | Mostrar entradas, saídas e saldo líquido por período | Linha, área ou compare | `cash_flow` | Soma de `IN`, soma de `OUT` e saldo líquido por período | Cronológica ascendente | Diário, semanal ou mensal | Estado vazio sem forçar zero fictício |
| Distribuição do recebido por forma de pagamento | Mostrar o peso de cada forma de pagamento no valor recebido | Donut | `receivable_receipts` | Soma do recebido por `payment_method` | Decrescente por valor | Período selecionado | `Sem recebimentos para distribuição` |
| Carteira por status | Mostrar a composição da carteira em aberto por situação financeira | Donut ou barras empilhadas | `accounts_receivable` | Soma do saldo em aberto por status oficial | Ordem fixa: `Pendente`, `Parcial`, `Em atraso` | Data de corte do relatório | `Sem títulos em aberto na data de corte` |
| Faturamento por período | Mostrar a evolução do faturamento comercial no período | Linha ou área | `orders` | Soma do `total_amount` por período para pedidos válidos | Cronológica ascendente | Diário, semanal ou mensal | `Sem pedidos válidos no período` |
| Conversão de orçamentos | Mostrar a proporção entre orçamentos elegíveis e convertidos | Compare | `quotes` e `orders` | Contagem de orçamentos elegíveis versus convertidos em pedido | Ordem fixa dos grupos | Data do orçamento | `Sem orçamentos elegíveis no período` |
| Ranking de clientes por faturamento | Mostrar os clientes que mais compraram no período | Ranking horizontal | `orders` e `clients` | Soma do faturamento por cliente | Decrescente por valor | Período selecionado | `Sem compras de clientes no período` |
| Top produtos por quantidade | Mostrar os produtos com maior saída em unidades | Ranking horizontal | `order_items`, `orders`, `products` | Soma de quantidade por produto | Decrescente por quantidade | Período selecionado | `Sem venda de produtos no período` |
| Top produtos por receita | Mostrar os produtos com maior geração de receita | Ranking horizontal | `order_items`, `orders`, `products` | Soma de receita por produto | Decrescente por valor | Período selecionado | `Sem receita de produtos no período` |
| Participação por categoria | Mostrar a participação de cada categoria na receita do período | Donut | `order_items`, `orders`, `products`, `categories` | Soma da receita por categoria | Decrescente por receita | Período selecionado | `Sem participação por categoria no período` |
| Curva ABC | Mostrar concentração acumulada de receita por produto | Linha | `order_items`, `orders`, `products` | Ordenação por receita e cálculo da participação acumulada | Descendente por receita, com curva acumulada | Período selecionado | `Sem base suficiente para curva ABC` |
| Novos clientes por período | Mostrar aquisição comercial real de clientes | Colunas | `orders`, `clients` | Contagem de clientes cuja primeira compra válida ocorreu em cada período | Cronológica ascendente | Período selecionado | `Sem novos clientes no período` |
| Ativos vs Inativos | Mostrar a distribuição da base entre clientes ativos e inativos | Compare ou donut | `clients`, `orders` | Contagem de clientes por regra oficial de atividade | Ordem fixa | Data de corte + janela de inatividade | `Sem clientes classificados para o período` |

## 5. Dicionário de Filtros

| Filtro | Tipo | Fonte | Comportamento | Impacto nos KPIs | Impacto nos gráficos | Impacto nas tabelas |
|---|---|---|---|---|---|---|
| Período | Intervalo de datas | Campo oficial de data do universo selecionado | Define janela temporal da consulta | Afeta todos os KPIs sensíveis a tempo | Afeta toda série temporal e gráficos agregados | Filtra o conjunto de linhas |
| Cliente | Seleção única ou múltipla | `clients` | Restringe análise ao(s) cliente(s) selecionado(s) | Afeta indicadores por cliente e, quando aplicável, KPIs financeiros/comerciais vinculados | Afeta rankings, distribuições e séries do cliente | Filtra linhas vinculadas ao cliente |
| Forma de pagamento | Seleção única ou múltipla | `receivable_receipts.payment_method` ou origem financeira oficial | Filtra recebimento/caixa pela forma utilizada | Afeta `Valor Recebido` e gráficos financeiros por forma | Afeta distribuição por forma e fluxo, quando aplicável | Filtra movimentações financeiras |
| Status financeiro | Seleção múltipla | `accounts_receivable.status` | Filtra carteira por situação oficial | Afeta `Contas a Receber` e `Contas em Atraso` | Afeta carteira por status | Filtra títulos e movimentações relacionadas |
| Conta bancária | Seleção múltipla | `bank_accounts` | Restringe movimentos de caixa e recebimentos por conta | Afeta `Fluxo de Caixa` e `Valor Recebido` quando aplicável | Afeta gráficos financeiros | Filtra lançamentos financeiros |
| Categoria financeira | Seleção múltipla | `financial_categories` | Restringe títulos e fluxo por categoria | Afeta carteira e caixa quando a categoria fizer parte da consulta | Afeta distribuições financeiras | Filtra movimentos financeiros |
| Vendedor | Seleção única ou múltipla | dimensão comercial oficial | Restringe análise comercial ao vendedor | Afeta faturamento, ticket, conversão, ranking e clientes do vendedor | Afeta gráficos comerciais | Filtra pedidos e itens |
| Canal | Seleção única ou múltipla | origem/canal comercial oficial | Restringe análise por canal de venda | Afeta KPIs comerciais | Afeta gráficos de vendas | Filtra pedidos |
| Categoria de produto | Seleção múltipla | `categories` | Restringe análise de produtos à categoria | Afeta indicadores de produtos | Afeta top produtos, participação e curva ABC | Filtra tabela de produtos |
| Produto | Seleção única ou múltipla | `products` | Restringe análise ao produto selecionado | Afeta produtos, margem, receita | Afeta gráficos de produto | Filtra tabela de produtos |
| Fornecedor | Seleção única ou múltipla | catálogo de fornecedor associado a produto | Restringe análise de produtos do fornecedor | Afeta produtos e margem | Afeta gráficos de produto | Filtra tabela de produtos |
| Cidade | Seleção múltipla | `clients.address_city` | Restringe clientes e compras por localidade | Afeta KPIs de clientes | Afeta gráficos de clientes | Filtra tabela de clientes |
| Estado | Seleção múltipla | `clients.address_state` | Restringe clientes e compras por UF | Afeta KPIs de clientes | Afeta gráficos de clientes | Filtra tabela de clientes |
| Agrupar por | Campo de configuração | dicionário de campos permitidos | Só disponível em `Personalizados` | Afeta KPIs derivados do relatório personalizado | Afeta gráfico customizado | Reorganiza a tabela personalizada |
| Ordenação | Campo + direção | metadado da tela | Define ordenação de exibição | Não altera valor do KPI | Afeta somente ordem visual de ranking/tabela | Altera ordenação da tabela e ranking |

### Regras gerais dos filtros

- Cada aba deve aplicar apenas filtros coerentes com seu universo.
- Filtros de um universo não podem alterar indicadores de outro universo sem reconciliação explícita.
- Filtros devem afetar tela e exportação de forma idêntica.
- KPIs de posição, como `Contas a Receber`, usam data de corte, não soma acumulada de movimentações do período.
- `Contas em Atraso` deve usar a data final selecionada como data de corte.
- Filtros de forma de pagamento não podem alterar `Faturamento Total`.
- Filtros de vendedor não podem alterar `Fluxo de Caixa`, salvo quando existir vínculo oficial e a análise for explicitamente comercial-financeira.

## 6. Exportações

### Formatos oficiais

- PDF
- Excel
- CSV
- Impressão

### Layout padrão

- Cabeçalho institucional com nome da empresa.
- Nome da aba ou relatório exportado.
- Período aplicado.
- Data e hora de geração.
- Usuário gerador.
- Identificador da empresa.
- Resumo dos filtros aplicados.
- Bloco de KPIs oficiais da visão.
- Bloco de gráficos, quando aplicável.
- Tabela analítica detalhada.
- Rodapé com paginação e metadados de auditoria.

### Campos obrigatórios em toda exportação

- Nome do relatório.
- Empresa.
- Período.
- Data e hora de geração.
- Usuário gerador.
- Timezone de geração.
- Filtros aplicados.
- Critério de ordenação.
- Versão da especificação funcional ou versão da regra analítica.
- Total de registros exportados.

### Critérios de auditoria

- Toda exportação deve ser reproduzível com os mesmos filtros.
- Tela e exportação devem apresentar os mesmos números.
- Exportações não devem depender da paginação visual; devem exportar o conjunto completo filtrado.
- Em caso de divergência entre exportação e tela, a exportação é considerada inválida.

## 7. Relatórios Personalizados

### Princípio geral

- Relatórios personalizados são permitidos, mas não podem violar a governança da fonte oficial.
- Todo relatório personalizado deve obrigatoriamente declarar seu `universo analítico`.

### Universos permitidos

- `Comercial`
- `Financeiro Caixa`
- `Financeiro Carteira`
- `Clientes`
- `Produtos`

### Campos permitidos

- Apenas campos certificados do universo escolhido.
- Dimensões comerciais permitidas: data comercial, cliente, vendedor, canal, produto, categoria, quantidade, faturamento, ticket, status comercial certificado.
- Dimensões financeiras de caixa permitidas: data financeira, cliente, forma de pagamento, conta bancária, categoria financeira, origem do movimento, valor de entrada, valor de saída, valor líquido.
- Dimensões financeiras de carteira permitidas: vencimento, cliente, categoria financeira, status da carteira, valor total do título, valor pago, saldo em aberto, atraso.
- Dimensões de clientes permitidas: cliente, praça, primeira compra, última compra, valor comprado, quantidade de pedidos, status de atividade.
- Dimensões de produtos permitidas: produto, categoria, fornecedor, quantidade, receita, custo oficial, lucro, margem, status de venda.

### Campos proibidos

- Misturar no mesmo relatório agregado `Faturamento Total` e `Valor Recebido` como se fossem a mesma métrica.
- Misturar `Fluxo de Caixa` com `Carteira` sem eixo de reconciliação.
- Usar campos técnicos não auditáveis.
- Usar campos temporários, internos ou de debugging.
- Usar custo não certificado em relatórios de margem.
- Usar colunas cujo significado de negócio não esteja no dicionário oficial.

## 8. Regras de Consistência

### Fechamentos obrigatórios

- Para cada pedido: `orders.paid_amount` deve ser igual à soma oficial de pagamentos/recebimentos vinculados ao pedido conforme o modelo adotado.
- Para cada título: `accounts_receivable.paid_amount` deve ser igual à soma de `receivable_receipts.amount` do título.
- Para cada título: `saldo_aberto = total_amount - paid_amount`, limitado a zero.
- Para cada título em atraso: o saldo em atraso deve ser subconjunto da carteira em aberto.
- Para cada recebimento: deve existir evento financeiro correspondente no `cash_flow`, quando a política financeira exigir baixa em caixa.
- Para cada estorno: deve existir reversão rastreável do efeito financeiro anterior.
- Para cada distribuição por forma de pagamento: a soma por forma deve ser igual ao total recebido do mesmo recorte.
- Para cada ranking de produtos: a soma das receitas por item deve ser compatível com a receita comercial do universo filtrado.

### Matriz de validação obrigatória

| Validação | Regra | Fonte A | Fonte B | Tolerância | Frequência |
|---|---|---|---|---|---|
| Fechamento de pagamento do pedido | `orders.paid_amount = soma dos pagamentos/recebimentos vinculados` | `orders` | `payments` ou vínculo oficial equivalente | `0,01` | Contínua |
| Fechamento de título a receber | `accounts_receivable.paid_amount = soma de receivable_receipts.amount` | `accounts_receivable` | `receivable_receipts` | `0,01` | Contínua |
| Fechamento de saldo do título | `saldo_aberto = total_amount - paid_amount` | `accounts_receivable` | cálculo derivado | `0,01` | Contínua |
| Fechamento de atraso | `contas_em_atraso <= contas_a_receber` | `accounts_receivable` | `accounts_receivable` | exato | Contínua |
| Fechamento por forma de pagamento | `soma por forma = valor recebido total` | `receivable_receipts` | agregação do relatório | `0,01` | A cada relatório |
| Fechamento de caixa recebido | `recebimentos financeiros válidos = entradas correspondentes no cash_flow`, quando aplicável | `receivable_receipts` | `cash_flow` | `0,01` | Diária |
| Fechamento de faturamento comercial | `faturamento = soma dos pedidos válidos` | `orders` | agregação do relatório | `0,01` | A cada relatório |
| Fechamento de top produtos | `soma dos itens válidos por produto` consistente com total da análise de produtos | `order_items` | agregação do relatório | `0,01` | A cada relatório |
| Fechamento de clientes novos | `novos clientes = clientes cuja primeira compra válida ocorreu no período` | `orders` | agregação do relatório | exato | A cada relatório |

## 9. Critérios de Aceitação

- `Faturamento Total`: aprovado quando refletir apenas pedidos válidos e ignorar integralmente cancelados.
- `Valor Recebido`: aprovado quando não duplicar faturamento e refletir somente liquidação financeira oficial.
- `Contas a Receber`: aprovado quando o saldo aberto total refletir exatamente a carteira na data final do relatório.
- `Contas em Atraso`: aprovado quando usar a data de corte do relatório e não a data atual do sistema.
- `Fluxo de Caixa Líquido`: aprovado quando o saldo líquido fechar com a soma dos movimentos oficiais.
- `Ticket Médio`: aprovado quando cancelados não alterarem o ticket.
- `Conversão de Orçamentos`: aprovado quando medir conversão real em pedido, não apenas aprovação.
- `Ranking de Clientes`: aprovado quando a ordem do ranking bater com a receita oficial por cliente.
- `Produtos Mais Vendidos`: aprovado quando refletir corretamente a quantidade vendida em pedidos válidos.
- `Produtos Menos Vendidos`: aprovado quando excluir produtos sem venda e ordenar os vendidos de menor para maior.
- `Produtos Sem Venda`: aprovado quando apenas produtos ativos sem venda forem classificados assim.
- `Margem por Produto`: aprovado quando usar somente custo oficial e sinalizar itens não auditáveis.
- `Clientes Ativos`: aprovado quando apenas compra válida ativar o cliente.
- `Clientes Inativos`: aprovado quando usar a janela configurada e ignorar pedidos cancelados.
- `Novos Clientes`: aprovado quando refletir primeira compra válida e não mera data de cadastro.
- Exportações: aprovadas quando todos os formatos apresentarem os mesmos totais, filtros e metadados obrigatórios.

## Tabela Consolidada Final

| Indicador | Universo | Fonte Oficial | Tabelas | Fórmula Aprovada | Data Oficial | Exclusões Obrigatórias |
|---|---|---|---|---|---|---|
| Faturamento Total | Comercial | Pedidos válidos | `orders` | `sum(total_amount)` de pedidos válidos | Data comercial do pedido | Cancelados, rascunhos, testes |
| Valor Recebido | Financeiro Caixa | Recebimentos liquidados | `receivable_receipts` | `sum(amount)` dos recebimentos válidos no período | `received_at` | Estornados, inválidos, duplicados |
| Contas a Receber | Financeiro Competência | Carteira aberta | `accounts_receivable` | `sum(max(0,total_amount-paid_amount))` | Data de corte | `PAID`, `CANCELED` |
| Contas em Atraso | Financeiro Competência | Carteira vencida aberta | `accounts_receivable` | `sum(saldo aberto vencido)` | Data de corte | Pagos, cancelados, não vencidos |
| Fluxo de Caixa Líquido | Financeiro Caixa | Livro caixa | `cash_flow` | `sum(IN)-sum(OUT)` | `cash_flow.date` | Movimentos inválidos ou de teste |
| Ticket Médio | Comercial | Pedidos válidos | `orders` | `faturamento total / qtd pedidos válidos` | Data comercial do pedido | Cancelados, rascunhos |
| Conversão de Orçamentos | Comercial | Orçamentos convertidos | `quotes`, `orders` | `quotes convertidos / quotes elegíveis` | Data do orçamento | `draft`, testes |
| Ranking de Clientes | Comercial | Compras por cliente | `orders`, `clients` | `sum(total_amount)` por cliente | Data comercial do pedido | Cancelados |
| Produtos Mais Vendidos | Comercial | Itens vendidos | `order_items`, `orders`, `products` | `sum(quantity)` por produto | Data comercial do pedido | Itens de pedidos cancelados |
| Produtos Menos Vendidos | Comercial | Itens vendidos | `order_items`, `orders`, `products` | `sum(quantity)>0`, ordenado asc | Data comercial do pedido | Sem venda, cancelados |
| Produtos Sem Venda | Comercial | Portfólio ativo sem giro | `products`, `order_items`, `orders` | `produtos ativos sem item válido no período` | Período selecionado | Produtos inativos |
| Margem por Produto | Comercial Gerencial | Receita e custo oficial | `order_items`, `orders`, `products` | `(receita-custo)/receita` | Data comercial do pedido | Cancelados, custo não oficial |
| Clientes Ativos | Comercial CRM | Clientes com compra válida | `orders`, `clients` | `count(distinct client_id com compra válida)` | Período selecionado | Clientes sem compra válida |
| Clientes Inativos | Comercial CRM | Base sem compra recente | `clients`, `orders` | `clientes sem compra válida há X dias` | Data de corte + janela | Cancelados não reativam |
| Novos Clientes | Comercial CRM | Primeira compra válida | `orders`, `clients` | `clientes cuja primeira compra válida ocorreu no período` | Período selecionado | Apenas cadastro, primeira compra cancelada |