# Matriz de Verdade Oficial do Módulo de Relatórios da Ktalogu Este documento consolida a fonte única de verdade da Ktalogu para os indicadores e relatórios do módulo de `Relatórios`. Nenhuma regra deste documento pode ser reinterpretada sem nova aprovação formal. ## Princípios - A Ktalogu deve separar claramente três universos: `Comercial`, `Financeiro por Competência` e `Financeiro por Caixa`. - `Comercial` responde quanto foi vendido. A fonte principal é `pedidos` e seus `itens`. - `Financeiro por Competência` responde quanto a empresa tem a receber ou a pagar. A fonte principal é `accounts_receivable` e `accounts_payable`. - `Financeiro por Caixa` responde quanto efetivamente entrou ou saiu do caixa/banco. A fonte principal é `cash_flow`, desde que derivado de eventos financeiros válidos e auditáveis. - A mesma tela pode exibir indicadores dos três universos, mas cada indicador precisa declarar sua natureza. - `Pedido` representa a obrigação comercial. - `Conta a receber` representa o direito financeiro. - `Recebimento` representa a liquidação. - `Cash flow` representa a movimentação de caixa decorrente da liquidação. - Cancelamento nunca deve apenas sumir de forma implícita. - Estorno nunca deve ser tratado como simples exclusão histórica quando já houve efeito financeiro. - Pagamento parcial, parcelamento e múltiplas formas de pagamento devem ser tratados como eventos normais. ## Modelo Conceitual - `Pedidos` são a fonte oficial do que foi vendido. - `Itens do pedido` são a fonte oficial do mix vendido, quantidades, ticket por item, ranking de produtos e margem por produto. - `Contas a receber` são a fonte oficial da carteira a receber. - `Recebimentos` são a fonte oficial do que foi liquidado contra a carteira. - `Pagamentos do pedido` podem existir como evento operacional/comercial, mas precisam ter relação clara com liquidação financeira. - `Fluxo de caixa` é o livro caixa oficial, derivado de eventos financeiros confirmados, não uma base paralela de atalho. - `Orçamentos` são a fonte oficial da conversão comercial. - `Clientes` são a dimensão mestra para análises de base, ativação, inatividade e aquisição. ## Regras Corretas por Indicador ### Faturamento Total - Conceito empresarial: valor bruto vendido no período, em regime comercial, independentemente do recebimento. - Deve entrar: pedidos comercialmente válidos emitidos no período de venda, com seu valor total líquido comercial. - Não deve entrar: recebimentos avulsos, lançamentos manuais de caixa, contas a receber manuais que não nasceram de venda, juros, multas, ajustes financeiros, estornos negativos, pedidos em rascunho, pedidos cancelados. - Tabelas consideradas: `orders` como fonte oficial; `order_items` para reconciliação analítica. - Cancelamentos: pedido cancelado não entra no faturamento. - Estornos: não alteram faturamento comercial, salvo devolução/cancelamento formal de venda. - Pagamentos parciais, múltiplas parcelas e múltiplas formas de pagamento: não alteram faturamento. ### Valor Recebido - Conceito empresarial: total efetivamente liquidado e recebido no período, em regime de caixa. - Deve entrar: somente recebimentos financeiros confirmados com reflexo real no banco/caixa. - Não deve entrar: valor do pedido ainda não pago, promessa de pagamento, conta a receber em aberto, títulos futuros, lançamentos cancelados, duplicatas de sincronização. - Tabelas consideradas: `receivable_receipts` como fonte oficial da liquidação; `cash_flow` como base de auditoria/espelho. - Cancelamentos: cancelamento comercial não remove recebimento passado; só o estorno financeiro altera o recebido líquido. - Estornos: a visão recomendada para ERP gerencial é `Recebido Líquido`, com bruto opcional. - Pagamentos parciais e parcelas: cada recebimento entra pela data do recebimento. - Múltiplas formas de pagamento: rateio do valor recebido por forma conforme cada liquidação. ### Contas a Receber - Conceito empresarial: saldo em aberto da carteira de recebíveis na data de corte. - Deve entrar: todas as contas a receber ativas e não liquidadas integralmente. - Não deve entrar: contas canceladas, títulos quitados integralmente, duplicidades, títulos originados por erro operacional. - Tabelas consideradas: `accounts_receivable`, com apoio de `receivable_receipts`. - Cancelamentos: conta cancelada sai da carteira. - Estornos: se um recebimento foi estornado, o saldo em aberto deve voltar a aumentar. - Pagamentos parciais: saldo em aberto = `total_amount - paid_amount`. - Múltiplas parcelas: cada parcela deve existir como título individual, se o modelo suportar; caso contrário, o saldo remanescente do título representa a carteira. - Múltiplas formas de pagamento: irrelevante para o saldo em aberto. ### Contas em Atraso - Conceito empresarial: parcela da carteira a receber cujo vencimento já passou e que ainda possui saldo aberto. - Deve entrar: contas com `due_date < data_corte` e saldo em aberto. - Não deve entrar: contas pagas, canceladas e títulos ainda a vencer. - Tabelas consideradas: `accounts_receivable`. - Cancelamentos: conta cancelada não entra. - Estornos: se o estorno reabre saldo vencido, volta a entrar. - Pagamentos parciais: entra apenas o saldo vencido remanescente. - Múltiplas parcelas: cada parcela vencida entra individualmente. - Múltiplas formas de pagamento: não altera a lógica do atraso. ### Fluxo de Caixa - Conceito empresarial: movimentação efetiva de entradas e saídas no caixa/banco no período. - Deve entrar: lançamentos financeiros efetivos, conciliados ou ao menos validados, por data financeira. - Não deve entrar: vendas não recebidas, promessas, competência sem liquidação, duplicidades, lançamentos de teste. - Tabelas consideradas: `cash_flow` como razão oficial; `receivable_receipts`, `payments`, `accounts_payable` e demais módulos como origem de geração/auditoria. - Cancelamentos: cancelamento comercial sem devolução financeira não altera caixa passado. - Estornos: entram como saída reversa claramente vinculada ao evento original. - Pagamentos parciais e parcelas: cada liquidação compõe o caixa de forma individual. - Múltiplas formas de pagamento: o fluxo reflete a forma real de cada movimento. ### Ticket Médio - Conceito empresarial: valor médio por pedido vendido. - Deve entrar: pedidos válidos do período. - Não deve entrar: orçamentos, pedidos cancelados, pedidos em rascunho, recebimentos avulsos. - Tabelas consideradas: `orders`. - Cancelamentos: pedido cancelado sai da base. - Estornos, parcelas e múltiplas formas: não afetam ticket comercial. ### Conversão de Orçamentos - Conceito empresarial: percentual de orçamentos elegíveis que se converteram em venda. - Deve entrar: orçamentos emitidos e efetivamente enviados/apresentados ao cliente, dentro do funil comercial. - Não deve entrar: rascunhos, cotações internas, duplicações de teste, orçamentos cancelados internamente antes de envio. - Tabelas consideradas: `quotes` como base oficial; `orders` para identificar conversão real; vínculo `orders.quote_id` ou equivalente. - Cancelamentos: orçamento cancelado ou rejeitado pode entrar no denominador se a régua quiser medir eficiência do funil; rascunho não entra. - Estornos, parcelas e múltiplas formas: não afetam conversão. ### Ranking de Clientes - Conceito empresarial: ordenação dos clientes pelo valor comprado no período. - Deve entrar: valor vendido por cliente em pedidos válidos. - Não deve entrar: orçamentos, caixa recebido sem venda identificada, pedidos cancelados. - Tabelas consideradas: `orders` e `clients`. - Cancelamentos: excluir pedidos cancelados. - Estornos, parcelas e múltiplas formas: não alteram ranking comercial. ### Produtos Mais Vendidos - Conceito empresarial: produtos com maior saída no período. - Deve entrar: itens efetivamente vendidos em pedidos válidos. - Não deve entrar: itens de orçamento, itens cancelados, itens de pedido cancelado, itens de teste. - Tabelas consideradas: `order_items`, `orders`, `products`. - Cancelamentos: itens de pedidos cancelados saem da base. - Estornos: não alteram quantidade vendida, salvo devolução física formal. - Parcelas e formas de pagamento: irrelevantes. ### Produtos Menos Vendidos - Conceito empresarial: produtos com venda positiva, porém com menor saída no período. - Deve entrar: produtos que tiveram ao menos uma venda no período. - Não deve entrar: produtos sem venda. - Tabelas consideradas: `order_items`, `orders`, `products`. - Cancelamentos: excluir itens de pedidos cancelados. ### Produtos Sem Venda - Conceito empresarial: produtos ativos cadastrados que não tiveram nenhuma venda no período. - Deve entrar: produtos ativos no catálogo elegível para venda. - Não deve entrar: produtos inativos, arquivados, excluídos, bloqueados ou fora do portfólio comercial vigente. - Tabelas consideradas: `products` e ausência de relacionamento em `order_items` ligados a `orders` válidos no período. - Cancelamentos: itens de pedidos cancelados não contam como venda. ### Margem por Produto - Conceito empresarial: lucratividade por produto no período. - Deve entrar: receita líquida do item menos custo do item vendido. - Não deve entrar: receitas financeiras, fretes não apropriados, despesas administrativas gerais, caixa recebido. - Tabelas consideradas: `order_items`, `orders`, `products`; se houver custo histórico por item/lote, usar custo histórico. Se não houver, usar custo padrão vigente com ressalva. - Cancelamentos: excluir itens de pedidos cancelados. - Estornos: não alteram margem comercial, salvo devolução de mercadoria formal. ### Clientes Ativos - Conceito empresarial: clientes com atividade comercial relevante dentro da janela de análise. - Deve entrar: clientes com pelo menos um pedido válido no período. - Não deve entrar: clientes apenas cadastrados, clientes com rascunhos, clientes sem movimento, clientes com pedido cancelado sem venda válida. - Tabelas consideradas: `clients`, `orders`. - Cancelamentos: pedido cancelado não torna cliente ativo. ### Clientes Inativos - Conceito empresarial: clientes da base que não compram há um intervalo definido. - Deve entrar: clientes cadastrados cuja última compra válida é anterior ao limiar de inatividade. - Não deve entrar: clientes recém-cadastrados ainda sem tempo hábil, clientes excluídos, clientes bloqueados, clientes somente com orçamento. - Tabelas consideradas: `clients`, `orders`. - Cancelamentos: pedido cancelado não conta como atividade. - Regra recomendada: cliente inativo = sem pedido válido há `X` dias, parametrizável. ### Novos Clientes - Conceito empresarial: clientes adquiridos no período. - Deve entrar: clientes cuja primeira compra válida ocorreu no período. - Não deve entrar: cliente apenas cadastrado sem compra, se o objetivo for aquisição comercial real. - Tabelas consideradas: `clients` e `orders`. - Cancelamentos: se a primeira compra foi cancelada e não houve compra válida, não deve contar como novo cliente adquirido. ## Matriz de Verdade | Indicador | Fonte Oficial | Fórmula | Tabelas | Status considerados | Observações | |---|---|---|---|---|---| | Faturamento Total | Comercial | `sum(total_amount dos pedidos válidos no período)` | `orders` | Incluir pedidos válidos; excluir `canceled`; excluir `draft` se existir em pedido | Regime comercial; não depende de pagamento | | Valor Recebido | Financeiro Caixa | `sum(recebimentos confirmados no período)` ou `entradas - estornos`, conforme visão líquida | `receivable_receipts` e reconciliação com `cash_flow` | Incluir recebimentos válidos; excluir recebimentos cancelados/estornados | Recomenda-se publicar `Recebido Bruto` e `Recebido Líquido` | | Contas a Receber | Financeiro Competência | `sum(max(0,total_amount-paid_amount)) na data de corte` | `accounts_receivable` | Incluir `PENDING`, `PARTIALLY_PAID`, `OVERDUE`; excluir `PAID`, `CANCELED` | Posição de carteira, não fluxo | | Contas em Atraso | Financeiro Competência | `sum(saldo em aberto de títulos com due_date0`, ordenado ascendente | `order_items`, `orders`, `products` | Pedidos válidos; excluir cancelados | Não misturar com sem venda | | Produtos Sem Venda | Comercial | `produtos ativos sem order_item em pedido válido no período` | `products`, `order_items`, `orders` | Produtos ativos; pedidos válidos | Indicador de portfólio, não de faturamento | | Margem por Produto | Comercial Gerencial | `(receita líquida do item - custo do item) / receita líquida do item` | `order_items`, `orders`, `products` | Pedidos válidos; excluir cancelados | Só é auditável se custo oficial estiver bem definido | | Clientes Ativos | Comercial CRM | `count(distinct clientes com ao menos um pedido válido no período)` | `clients`, `orders` | Pedidos válidos; excluir cancelados | Atividade por compra, não por cadastro | | Clientes Inativos | Comercial CRM | `clientes sem compra válida há X dias` | `clients`, `orders` | Base de clientes ativos cadastrais; última compra válida | Parametrizar janela, ex.: 90 dias | | Novos Clientes | Comercial CRM | `clientes cujo primeiro pedido válido ocorreu no período` | `clients`, `orders` | Primeiro pedido válido; excluir primeiras compras canceladas | Não confundir com novos cadastros | ## Decisões Estruturais Recomendadas - A Ktalogu deve adotar oficialmente duas famílias de indicadores: `Comerciais` e `Financeiros`. - `Faturamento`, `Ticket`, `Conversão`, `Ranking de Clientes`, `Produtos`, `Margem`, `Clientes Ativos/Inativos/Novos` pertencem ao universo comercial. - `Valor Recebido`, `Contas a Receber`, `Contas em Atraso` e `Fluxo de Caixa` pertencem ao universo financeiro. - Sempre que houver comparação entre comercial e financeiro, ela deve ser tratada como `conciliação`, não como identidade automática.