# Plano de Correção Oficial da Ktalogu

Plano oficial de correção do módulo de `Relatórios`, ordenado por impacto no negócio e com foco inicial na eliminação de decisões financeiras incorretas.

## Fases Oficiais

| Fase | Objetivo | Indicadores afetados | Arquivos afetados | Funções afetadas | Risco de regressão | Dependências | Estratégia de testes | Critérios de aprovação | Migração de banco |
|---|---|---|---|---|---|---|---|---|---|
| **Fase 1** | Corrigir a semântica e o cálculo dos indicadores financeiros principais conforme a Matriz de Verdade, sem ainda redesenhar o modelo transacional | `Faturamento Total`, `Valor Recebido`, `Contas a Receber`, `Contas em Atraso`, gráficos financeiros temporais, distribuição por forma de pagamento, tabela financeira | `service.ts`, `utils.ts`, `contracts.ts`, `report-page-client.tsx`, `report-charts.tsx`, `report-data-table.tsx` | `buildFinancialReport()`, `buildSeriesMap()`, `takeTopSeries()`, `monthLabel()`, `loadReport()` | Crítico | Matriz de Verdade aprovada; definição oficial de data de corte; decisão executiva se `Valor Recebido` será exibido em visão `bruta`, `líquida` ou ambas | Criar massa de teste controlada com pedido vendido não recebido, pedido parcialmente recebido, conta a receber futura, conta vencida, conta quitada, estorno, ajuste manual; validar tela, exportação, paginação e comparação com período anterior | `Faturamento` passa a bater com `orders`; `Recebido` deixa de replicar `Faturamento`; `Contas a Receber` vira posição real da carteira; `Contas em Atraso` respeita data de corte; gráficos financeiros deixam de duplicar conceito e ordenam cronologicamente | Não obrigatória |
| **Fase 2** | Fortalecer a rastreabilidade financeira oficial para garantir que recebimentos, estornos e reversões sejam auditáveis de ponta a ponta | `Valor Recebido`, `Fluxo de Caixa`, conciliação com estornos, rastreio de reversões, distribuição por forma de pagamento líquida | `68_add_accounts_receivable_manual.sql`, `69_update_cash_flow_origin_receber.sql`, `70_make_delete_payment_compatible_with_immutable_cash_flow.sql`, `create_financial_module.sql`, `update_schema.sql`, `financial.ts`, rotas de recebimento e cancelamento PDV | `handle_payment_change()`, `create_cash_flow_from_payment()`, `sync_accounts_receivable_status()`, `delete_payment_with_cleanup()`, `registerPayment()`, `POST /accounts-receivable/[id]/receive`, `POST /pdv/cancel-sale` | Crítico | Fase 1 concluída; decisão arquitetural da fonte oficial de `Recebido`; inventário completo dos cenários de estorno | Testes de integração financeira com pagamento inserido, pagamento excluído, estorno PDV, recebimento parcial, reversão de recebimento, ambiente com fluxo imutável | Todo recebimento passa a ter trilha auditável; todo estorno/reversão impacta corretamente carteira e caixa; números financeiros continuam corretos mesmo após exclusão, compensação ou cancelamento | Sim, recomendada |
| **Fase 3** | Sanear a camada comercial de vendas para alinhar KPIs de performance e funil à Matriz de Verdade | `Faturamento Total comercial`, `Ticket Médio`, `Conversão de Orçamentos`, `Ranking de Clientes` da aba vendas, `Evolução de Vendas`, tabela de vendas | `service.ts`, `contracts.ts`, `report-page-client.tsx`, `report-charts.tsx` | `loadSalesBase()`, `buildSalesReport()` | Alto | Fase 1 concluída; definição oficial de `pedido válido`; definição oficial de `orçamento elegível`; confirmação se conversão será `aprovado` ou `convertido em pedido` | Criar massa com orçamento draft, enviado, aprovado sem pedido, aprovado com pedido, pedido cancelado, pedido parcial, pedido normal | Cancelados deixam de contaminar vendas; ticket passa a usar apenas pedidos válidos; conversão mede o que foi definido na matriz; ranking de clientes da aba vendas passa a refletir compra real no período | Não obrigatória |
| **Fase 4** | Sanear a inteligência de produtos e lucratividade para transformar a aba de produtos em ferramenta confiável de mix e margem | `Produtos Mais Vendidos`, `Produtos Menos Vendidos`, `Produtos Sem Venda`, `Margem por Produto`, `Receita por Produto`, `Lucro`, `Curva ABC`, `Participação por categoria` | `service.ts`, `utils.ts`, `report-charts.tsx`, eventuais schemas de custo em `products` | `loadSalesBase()`, `buildProductsReport()` | Alto | Fase 3 concluída; validação do conceito oficial de custo; decisão se `sem venda` considera apenas produtos ativos comercializáveis | Testes com produtos vendidos, pouco vendidos, sem venda, cancelados, custo zerado, custo incorreto, múltiplos itens por pedido | Ranking por quantidade e por receita passa a refletir venda válida; `Sem Venda` considera portfólio ativo; margem só é aprovada se a base de custo for oficialmente validada | Condicional |
| **Fase 5** | Corrigir CRM analítico e consolidar governança da camada de relatórios personalizados e exportações | `Clientes Ativos`, `Clientes Inativos`, `Novos Clientes`, `Ranking de Clientes` da aba clientes, relatórios personalizados, exportações finais, comparação com período anterior | `service.ts`, `report-page-client.tsx`, `report-data-table.tsx`, `src/app/api/reports/export/route.ts` | `buildCustomersReport()`, `buildCustomReport()`, `aggregateCustomRows()`, `loadFullReportForExport()`, `exportReport()` | Médio/Alto | Fases 1, 3 e 4 concluídas; definição oficial de `cliente novo` e janela de `inatividade`; catálogo final de filtros permitidos por universo | Testes com clientes sem compra, primeira compra no período, cliente antigo reativado, cliente só com orçamento, cliente com pedido cancelado; validar exportações contra a tela | `Novos Clientes` passa a ser primeira compra válida; `Ativos/Inativos` passam a obedecer regra oficial; personalizados deixam de propagar base contaminada; exportações reproduzem os números aprovados em tela | Não obrigatória |

## Leitura Executiva por Fase

### Fase 1

- Elimina imediatamente os números financeiros semanticamente errados na camada de relatórios.
- Corrige a fonte oficial de `Faturamento`, separa `Recebido`, corrige carteira em aberto, corrige atraso por data de corte e saneia os gráficos financeiros.

### Fase 2

- Blinda o modelo financeiro para que a correção analítica não fique dependente de comportamento frágil ou ambíguo do banco.
- Formaliza trilha oficial de liquidação, reversão e caixa.

### Fase 3

- Alinha o bloco comercial de vendas à regra oficial.
- Corrige exclusão de cancelados, definição de pedido válido, conversão, rankings e evolução temporal.

### Fase 4

- Torna a análise de produtos realmente útil para mix, margem e portfólio.
- Formaliza mais vendidos, menos vendidos, sem venda, margem, curva ABC e participação por categoria.

### Fase 5

- Fecha a governança analítica de clientes, CRM e relatórios personalizados.
- Corrige novos clientes, ativos, inativos, rankings, exportações e camada customizada.

## Correções que Exigem Migração de Banco

### Obrigatórias ou fortemente recomendadas

- Fortalecer rastreabilidade de estornos e reversões financeiras.
- Garantir vínculo auditável entre evento original e evento reverso em `cash_flow`.
- Endurecer o modelo oficial de liquidação/estorno para que `Recebido` e `Fluxo de Caixa` possam ser auditados sem interpretação ambígua.
- Revisar e, se necessário, complementar triggers e procedures ligadas a `payments`, `receivable_receipts`, `accounts_receivable` e `cash_flow`.

### Condicionais

- Modelagem de `custo oficial` para margem por produto, caso o campo atual em `products` não seja suficiente.
- Eventual definição de data comercial oficial (`closed_at`, `approved_at`, `issued_at`) se `created_at` não for suficiente.
- Eventual persistência de snapshots ou tabelas analíticas derivadas, caso a Ktalogu queira performance e auditoria forte em bases grandes.

## Correções que Podem Ser Feitas Só na Camada de Relatórios

- Reclassificação conceitual de KPIs e gráficos.
- Correção de fórmulas hoje erradas no serviço de relatórios.
- Correção da ordenação temporal dos gráficos.
- Exclusão de cancelados da base analítica comercial.
- Correção de `Conversão de Orçamentos` usando vínculos já existentes.
- Correção de `Clientes Ativos`, `Inativos` e `Novos Clientes`.
- Ajustes de exportação para reproduzir fielmente a nova verdade oficial.

## Critério Global de Encerramento

O plano só pode ser considerado concluído quando:

- cada KPI tiver uma única fonte oficial;
- cada indicador tiver uma data oficial de referência;
- os relatórios financeiros fecharem com carteira, recebimento e caixa conforme a matriz;
- os relatórios comerciais excluírem eventos inválidos;
- exportação, tela e comparação de período apresentarem o mesmo resultado;
- toda divergência residual estiver documentada como exceção de negócio, não como efeito colateral técnico.