# Backlog Técnico Executivo do Módulo de Relatórios da Ktalogu

Documento executivo-operacional do módulo de `Relatórios` da Ktalogu.

Base exclusiva: `Especificação Funcional Oficial`, `Matriz de Verdade`, `Plano de Correção Fases 1 a 5` e `Auditoria Final`.

## Premissas

- Nenhuma história pode reinterpretar a regra oficial.
- Toda entrega deve preservar rastreabilidade entre fonte oficial, relatório, exportação e auditoria.
- Toda mudança deve ser testada com massa controlada e reconciliação manual.
- Toda história deve ser aprovada por aderência à especificação, não por percepção visual.

## EPICS

### EPIC-001 – Financeiro Analítico

- **Objetivo:** alinhar todos os indicadores e relatórios financeiros à fonte oficial da Ktalogu, separando claramente `faturamento`, `recebido`, `carteira` e `caixa`.
- **Problema Atual:** mistura de universos analíticos diferentes, duplicidade conceitual entre `Faturamento Total` e `Valor Recebido`, e regras incorretas de carteira/atraso.
- **Benefício Esperado:** decisão financeira confiável, fim da duplicidade semântica e relatórios financeiros reproduzíveis.
- **Dependências:** especificação funcional aprovada, definição oficial de data de corte, decisão sobre `Recebido Bruto` x `Recebido Líquido`.
- **Riscos:** mudança em números já vistos por clientes internos e dependência da qualidade das trilhas financeiras.
- **Critérios de Encerramento:** KPIs financeiros aderentes à especificação, gráficos cronologicamente corretos, tela e exportação com números idênticos e conciliação manual aprovada.

### EPIC-002 – Rastreabilidade Financeira

- **Objetivo:** garantir que eventos financeiros tenham trilha oficial, reversão auditável e consistência entre pedido, recebimento, título e caixa.
- **Problema Atual:** risco de divergência entre `payments`, `receivable_receipts`, `accounts_receivable` e `cash_flow`.
- **Benefício Esperado:** auditoria financeira confiável e base sólida para relatórios e exportações.
- **Dependências:** EPIC-001 concluído ou congelado funcionalmente; inventário dos cenários de pagamento, exclusão, cancelamento e estorno.
- **Riscos:** regressão transacional, impacto em rotinas operacionais e risco histórico em dados legados.
- **Critérios de Encerramento:** todo evento financeiro relevante com trilha verificável e estorno/reversão com impacto correto em carteira e caixa.

### EPIC-003 – Comercial e Vendas

- **Objetivo:** corrigir o universo comercial da aba de vendas para refletir apenas pedidos válidos, faturamento correto, ticket correto e conversão real.
- **Problema Atual:** cancelados contaminam análises e conversão não segue regra oficial.
- **Benefício Esperado:** métricas comerciais confiáveis e redução de leituras artificiais de performance.
- **Dependências:** EPIC-001 concluído, definição oficial de `pedido válido` e `orçamento elegível`.
- **Riscos:** mudança em metas históricas percebidas e impacto em painéis usados pelo Comercial.
- **Critérios de Encerramento:** KPIs de vendas aderentes à matriz, conversão por vínculo real e cancelados fora da base.

### EPIC-004 – Produtos e Margem

- **Objetivo:** transformar a aba de produtos em visão confiável de mix, giro, receita e margem.
- **Problema Atual:** a base de produtos herda problemas da camada comercial e a margem depende de custo que precisa ser validado.
- **Benefício Esperado:** visão confiável para mix, compra, produção e precificação.
- **Dependências:** EPIC-003 concluído, validação do custo oficial e definição do universo de produtos ativos comercializáveis.
- **Riscos:** alta sensibilidade em métricas de margem.
- **Critérios de Encerramento:** indicadores de produto aderentes à especificação, sem venda formalizado e margem aprovada por financeiro/controladoria e produto.

### EPIC-005 – Clientes e CRM

- **Objetivo:** corrigir os indicadores de clientes para refletir aquisição real, atividade e inatividade conforme regra oficial.
- **Problema Atual:** `Novos Clientes`, `Ativos` e `Inativos` não seguem a definição oficial.
- **Benefício Esperado:** CRM analítico confiável e melhor priorização de relacionamento.
- **Dependências:** EPIC-003 concluído, janela de inatividade definida e regra de primeira compra válida aprovada.
- **Riscos:** mudança na leitura do tamanho e qualidade da base.
- **Critérios de Encerramento:** novos clientes por primeira compra válida, ativos/inativos por regra oficial e ranking alinhado ao universo comercial correto.

### EPIC-006 – Relatórios Personalizados

- **Objetivo:** garantir que relatórios personalizados respeitem universos analíticos, campos certificados e agregações permitidas.
- **Problema Atual:** o motor customizado pode reproduzir números contaminados e misturas indevidas.
- **Benefício Esperado:** flexibilidade com controle e relatórios customizados auditáveis.
- **Dependências:** EPIC-001 a EPIC-005 concluídos em seus universos e catálogo oficial de campos permitidos/proibidos.
- **Riscos:** alto risco de interpretação errada se a governança ficar incompleta.
- **Critérios de Encerramento:** universo analítico explícito, campos governados e exportação customizada aderente à mesma verdade da tela.

### EPIC-007 – Exportações e Auditoria

- **Objetivo:** garantir que PDF, Excel, CSV e Impressão sejam extensões auditáveis da mesma verdade apresentada em tela.
- **Problema Atual:** exportações podem divergir da tela e metadados de auditoria ainda precisam padronização.
- **Benefício Esperado:** segurança para uso interno e externo e reprodutibilidade das informações.
- **Dependências:** estabilização das regras dos demais epics.
- **Riscos:** divergência entre tela e arquivo e baixa confiabilidade em auditoria se faltar metadado.
- **Critérios de Encerramento:** paridade total entre tela e exportação, metadados obrigatórios presentes e log de geração/exportação disponível para auditoria.

## Histórias

| ID | Título | Objetivo | Fonte Oficial | Impacto | Dependências | Tipo de Alteração |
|---|---|---|---|---|---|---|
| REL-001 | Redefinir KPIs financeiros conforme a Matriz de Verdade | Corrigir `Valor Recebido`, `Contas a Receber`, `Contas em Atraso` e remover a ambiguidade de `Faturamento` dentro da aba financeira | `receivable_receipts`, `accounts_receivable`, `cash_flow` | Crítico | Especificação aprovada; decisão oficial de nomenclatura e visão líquida/bruta | `Regra analítica`, `KPI`, `API`, `UI` |
| REL-002 | Corrigir gráficos financeiros e ordenação temporal | Garantir que gráficos financeiros reflitam a semântica oficial e ordenem períodos cronologicamente | `receivable_receipts`, `cash_flow`, `accounts_receivable` | Alto | REL-001 | `Gráfico`, `Agregação`, `Regra analítica`, `UI` |
| REL-003 | Corrigir filtros, data de corte e tabela analítica financeira | Alinhar filtros financeiros ao universo correto e fazer a tabela reproduzir a verdade oficial | `accounts_receivable`, `receivable_receipts`, `cash_flow` | Alto | REL-001 | `Regra analítica`, `Tabela`, `Filtro`, `UI` |
| REL-004 | Validar trilha oficial entre pedidos, pagamentos e fluxo de caixa | Mapear e padronizar a consistência entre `orders`, `payments` e `cash_flow` | `orders`, `payments`, `cash_flow` | Crítico | REL-001 concluído funcionalmente | `Banco de dados`, `Auditoria`, `Regra analítica`, `API` |
| REL-005 | Validar trilha oficial entre títulos, recebimentos e caixa | Garantir consistência entre `accounts_receivable`, `receivable_receipts` e `cash_flow` | `accounts_receivable`, `receivable_receipts`, `cash_flow` | Crítico | REL-001 | `Banco de dados`, `API`, `Auditoria`, `Regra analítica` |
| REL-006 | Padronizar estorno e reversão financeira auditável | Formalizar comportamento de exclusão, reversão e estorno | `payments`, `receivable_receipts`, `cash_flow`, `accounts_receivable` | Crítico | REL-004, REL-005 | `Banco de dados`, `Auditoria`, `API`, `Regra analítica` |
| REL-007 | Formalizar base oficial de pedidos válidos para relatórios comerciais | Remover cancelados e status não elegíveis da base comercial | `orders` | Alto | Sprint 2 concluída | `Regra analítica`, `Agregação`, `API` |
| REL-008 | Corrigir faturamento, ticket e ranking da aba de vendas | Alinhar KPIs e gráficos comerciais à Matriz de Verdade | `orders`, `clients` | Alto | REL-007 | `KPI`, `Gráfico`, `Tabela`, `Regra analítica`, `UI` |
| REL-009 | Corrigir conversão de orçamentos para conversão real em pedido | Medir conversão real via vínculo oficial com pedido | `quotes`, `orders` | Crítico | REL-007 | `Regra analítica`, `KPI`, `Gráfico`, `API` |
| REL-010 | Sanear a base oficial de produtos vendidos | Garantir que a aba de produtos use apenas itens de pedidos válidos | `order_items`, `orders`, `products` | Alto | REL-007 | `Regra analítica`, `Agregação`, `API` |
| REL-011 | Implementar indicadores oficiais de produtos mais vendidos, menos vendidos e sem venda | Formalizar os três indicadores exigidos pela especificação | `products`, `order_items`, `orders` | Alto | REL-010 | `KPI`, `Gráfico`, `Tabela`, `Regra analítica` |
| REL-012 | Formalizar margem por produto sobre custo oficial | Tornar margem auditável e alinhada ao custo oficial aprovado | `order_items`, `orders`, `products`, modelo oficial de custo | Alto | REL-010 | `Regra analítica`, `KPI`, `Banco de dados` opcional, `API` |
| REL-013 | Corrigir novos clientes para primeira compra válida | Alinhar aquisição de clientes à definição oficial | `orders`, `clients` | Alto | REL-007 | `Regra analítica`, `KPI`, `Gráfico` |
| REL-014 | Corrigir classificação de clientes ativos e inativos | Aplicar regra oficial de atividade e janela de inatividade | `orders`, `clients` | Alto | REL-007 | `Regra analítica`, `KPI`, `Gráfico`, `Tabela` |
| REL-015 | Corrigir ranking e tabela analítica de clientes | Refletir valor comprado, última compra e status de atividade corretos | `orders`, `clients` | Alto | REL-013, REL-014 | `Tabela`, `Gráfico`, `KPI`, `Regra analítica` |
| REL-016 | Segregar universos analíticos em relatórios personalizados | Impedir mistura indevida entre comercial, financeiro, clientes e produtos | Catálogo oficial da especificação | Alto | REL-001 a REL-015 aplicáveis | `Regra analítica`, `UI`, `API`, `Auditoria` |
| REL-017 | Governar campos permitidos, proibidos e agregações em relatórios personalizados | Restringir a engine customizada a campos certificados | Dicionário oficial de campos e regras de agregação | Médio | REL-016 | `Regra analítica`, `Agregação`, `UI`, `API` |
| REL-018 | Validar consistência, salvamento e exportação de relatórios personalizados | Garantir que modelos salvos e exportados mantenham a mesma verdade da tela | Configuração oficial do relatório personalizado | Médio | REL-016, REL-017, REL-019, REL-020 | `Auditoria`, `Exportação`, `UI`, `API` |
| REL-019 | Padronizar layout e metadados obrigatórios de exportação | Garantir que toda exportação contenha cabeçalho, rodapé e trilha mínima de auditoria | Especificação de exportação aprovada | Médio | KPIs e tabelas estabilizados | `Exportação`, `Auditoria`, `UI`, `API` |
| REL-020 | Garantir paridade entre tela e exportação | Impedir qualquer divergência entre o que o usuário vê e o que exporta | Serviço oficial de relatórios | Alto | REL-019 | `Exportação`, `API`, `Auditoria`, `Tabela` |
| REL-021 | Implantar governança de auditoria e rastreio de geração/exportação | Garantir rastreabilidade de quem gerou, quando gerou e com quais filtros | Política de auditoria da Ktalogu | Médio | REL-019, REL-020 | `Auditoria`, `API`, `Exportação` |

## Casos de Teste Vinculados

| História | Casos de teste obrigatórios |
|---|---|
| REL-001 | `CT-001`, `CT-002`, `CT-005`, `CT-006`, `CT-008`, `CT-009`, `CT-015` |
| REL-002 | `CT-002`, `CT-006`, `CT-007`, `CT-010`, `CT-014` |
| REL-003 | `CT-005`, `CT-008`, `CT-009`, `CT-010`, `CT-014` |
| REL-004 | `CT-002`, `CT-004`, `CT-010`, `CT-015` |
| REL-005 | `CT-005`, `CT-006`, `CT-008`, `CT-009`, `CT-015` |
| REL-006 | `CT-004`, `CT-010`, `CT-015` |
| REL-007 | `CT-001`, `CT-002`, `CT-003`, `CT-004` |
| REL-008 | `CT-001`, `CT-002`, `CT-003`, `CT-011`, `CT-014` |
| REL-009 | `CT-011`, `CT-014` |
| REL-010 | `CT-002`, `CT-003`, `CT-012` |
| REL-011 | `CT-012`, `CT-014` |
| REL-012 | `CT-012`, `CT-014` |
| REL-013 | `CT-013`, `CT-014` |
| REL-014 | `CT-013`, `CT-014` |
| REL-015 | `CT-013`, `CT-014` |
| REL-016 | `CT-014` |
| REL-017 | `CT-014` |
| REL-018 | `CT-014` |
| REL-019 | `CT-014` |
| REL-020 | `CT-014` |
| REL-021 | `CT-014` |

## Matriz de Priorização

| ID | Item | Impacto no Negócio | Complexidade Técnica | Risco | Prioridade |
|---|---|---:|---:|---:|---|
| REL-001 | KPIs financeiros oficiais | Muito Alto | Média | Muito Alto | P0 |
| REL-002 | Gráficos financeiros e ordenação temporal | Alto | Média | Alto | P0 |
| REL-003 | Filtros, data de corte e tabela financeira | Alto | Média | Alto | P0 |
| REL-004 | Trilha pedidos-pagamentos-caixa | Muito Alto | Alta | Muito Alto | P0 |
| REL-005 | Trilha títulos-recebimentos-caixa | Muito Alto | Alta | Muito Alto | P0 |
| REL-006 | Estorno e reversão auditável | Muito Alto | Alta | Muito Alto | P0 |
| REL-007 | Base oficial de pedidos válidos | Alto | Média | Alto | P1 |
| REL-008 | Faturamento, ticket e ranking de vendas | Alto | Média | Alto | P1 |
| REL-009 | Conversão real de orçamentos | Muito Alto | Média | Alto | P1 |
| REL-010 | Base oficial de produtos vendidos | Alto | Média | Médio | P1 |
| REL-011 | Indicadores de produtos mais/menos/sem venda | Alto | Média | Médio | P1 |
| REL-012 | Margem por produto com custo oficial | Alto | Alta | Alto | P1 |
| REL-013 | Novos clientes por primeira compra válida | Alto | Média | Médio | P1 |
| REL-014 | Ativos e inativos por regra oficial | Alto | Média | Médio | P1 |
| REL-015 | Ranking e tabela de clientes | Alto | Média | Médio | P1 |
| REL-016 | Segregação de universos analíticos no customizado | Médio | Alta | Alto | P2 |
| REL-017 | Governança de campos e agregações no customizado | Médio | Média | Médio | P2 |
| REL-018 | Consistência, salvamento e exportação do customizado | Médio | Média | Médio | P2 |
| REL-019 | Layout e metadados obrigatórios de exportação | Médio | Média | Médio | P2 |
| REL-020 | Paridade entre tela e exportação | Alto | Média | Alto | P1 |
| REL-021 | Auditoria e rastreio de geração/exportação | Médio | Média | Médio | P2 |