# Plano de Execução Operacional do Módulo de Relatórios da Ktalogu

Documento executivo para implementação controlada do módulo de `Relatórios` da Ktalogu.

Base exclusiva: `Backlog Técnico Executivo`, `Especificação Funcional Oficial`, `Matriz de Verdade`, `Plano de Correção por Fases` e `Casos de Teste CT-001 a CT-015`.

## 1. Estrutura Organizacional

### Squads e Papéis

| Área | Responsabilidade principal |
|---|---|
| Backend | Regras analíticas, contratos, APIs de relatório, agregações, coerência entre fonte oficial e payload |
| Frontend | Cards, gráficos, filtros, tabelas, exportações acionadas pela UI, mensagens e consistência visual/funcional |
| Banco de Dados | Triggers, procedures, rastreabilidade transacional, integridade de títulos, recebimentos e fluxo de caixa |
| QA | Execução dos casos CT-001 a CT-015, evidências, regressão, validação cruzada entre tela e exportação |
| Homologação | Validação funcional com Financeiro, Comercial, Produtos, Clientes e usuários-chave |
| Produto | Guarda da especificação oficial, aprovação funcional, definição de aceite e arbitragem de aderência |

### Matriz de Responsabilidade por História

| História | Squad responsável | Áreas impactadas | Dependências técnicas | Ordem de execução |
|---|---|---|---|---|
| REL-001 | Backend | Frontend, QA, Produto, Homologação Financeira | Congelamento da especificação financeira; definição oficial de nomenclatura de KPIs financeiros | 1 |
| REL-002 | Frontend | Backend, QA, Produto | REL-001; payload financeiro estabilizado | 2 |
| REL-003 | Backend | Frontend, QA, Produto, Homologação Financeira | REL-001; catálogo de filtros financeiros oficial | 3 |
| REL-004 | Banco de Dados | Backend, QA, Produto, Homologação Financeira | Sprint 1 concluída; inventário de triggers e rotinas financeiras | 4 |
| REL-005 | Banco de Dados | Backend, QA, Produto, Homologação Financeira | REL-004; definição oficial da trilha de recebimento | 5 |
| REL-006 | Banco de Dados | Backend, QA, Produto, Homologação Financeira | REL-004 e REL-005 | 6 |
| REL-007 | Backend | QA, Produto, Frontend | Sprint 2 concluída; definição oficial de pedido válido | 7 |
| REL-008 | Backend | Frontend, QA, Produto, Homologação Comercial | REL-007 | 8 |
| REL-009 | Backend | Frontend, QA, Produto, Homologação Comercial | REL-007; vínculo oficial `quote -> order` validado | 9 |
| REL-010 | Backend | QA, Produto, Frontend | REL-007; base de pedidos válidos estabilizada | 10 |
| REL-011 | Backend | Frontend, QA, Produto, Homologação Produtos | REL-010 | 11 |
| REL-012 | Backend | Banco de Dados, QA, Produto, Homologação Produtos/Financeira | REL-010; validação de custo oficial | 12 |
| REL-013 | Backend | Frontend, QA, Produto, Homologação Clientes | REL-007 | 13 |
| REL-014 | Backend | Frontend, QA, Produto, Homologação Clientes | REL-007; janela oficial de inatividade | 14 |
| REL-015 | Backend | Frontend, QA, Produto, Homologação Clientes | REL-013 e REL-014 | 15 |
| REL-016 | Backend | Frontend, QA, Produto | REL-001 a REL-015 concluídas nos universos correspondentes | 16 |
| REL-017 | Backend | Frontend, QA, Produto | REL-016; catálogo oficial de campos certificados | 17 |
| REL-018 | Frontend | Backend, QA, Produto, Homologação | REL-016, REL-017, REL-019, REL-020 | 18 |
| REL-019 | Frontend | Backend, QA, Produto, Homologação | Regras de exportação congeladas; payload definitivo por aba | 19 |
| REL-020 | Backend | Frontend, QA, Produto, Homologação | REL-019; estabilização das consultas de tela | 20 |
| REL-021 | Backend | Frontend, QA, Produto, Homologação, Banco | REL-019 e REL-020; política de auditoria validada | 21 |

## 2. Plano de Implementação por Sprint

### Sprint 1

- **Histórias:** `REL-001`, `REL-002`, `REL-003`
- **Objetivo:** estabilizar a verdade financeira analítica em tela, filtros, tabela e gráficos.

| Item | Conteúdo |
|---|---|
| Entregáveis | KPIs financeiros aderentes à especificação; gráficos financeiros sem duplicidade semântica; ordenação cronológica correta; data de corte aplicada corretamente; tabela financeira coerente com KPIs |
| Riscos | Mudança perceptível de números; dependência de alinhamento com Financeiro; regressão em filtros e comparação com período anterior |
| Bloqueadores | Falta de definição final sobre `Recebido Bruto` x `Recebido Líquido`; falta de massa de teste financeira controlada |
| Critérios de saída | CT-001, CT-002, CT-005, CT-006, CT-008, CT-009, CT-010 e CT-015 executados; validação manual do Financeiro; tela e exportação preliminar coerentes |

### Sprint 2

- **Histórias:** `REL-004`, `REL-005`, `REL-006`
- **Objetivo:** garantir rastreabilidade financeira transacional e blindar a base que sustenta os relatórios.

| Item | Conteúdo |
|---|---|
| Entregáveis | Mapeamento consistente entre pedidos, pagamentos, títulos, recebimentos e caixa; comportamento oficial de estorno e reversão; trilha auditável formalizada |
| Riscos | Regressão em rotinas operacionais; impacto em histórico financeiro; dependência de revisão de banco |
| Bloqueadores | Falta de inventário completo das triggers/funções; dados legados inconsistentes |
| Critérios de saída | CT-004, CT-005, CT-006, CT-010 e CT-015 aprovados; conciliação transacional validada; homologação financeira concluída |

### Sprint 3

- **Histórias:** `REL-007`, `REL-008`, `REL-009`
- **Objetivo:** sanear o universo comercial oficial de vendas e funil.

| Item | Conteúdo |
|---|---|
| Entregáveis | Base de pedidos válidos oficial; faturamento comercial correto; ticket médio correto; conversão real de orçamento em pedido; rankings comerciais limpos |
| Riscos | Mudança nos números históricos percebidos pelo Comercial; divergência entre hábito operacional e regra oficial |
| Bloqueadores | Falta de definição fechada de `pedido válido` e `orçamento elegível`; inconsistência no vínculo `quote_id` |
| Critérios de saída | CT-001, CT-002, CT-003, CT-011 e CT-014 aprovados; homologação comercial concluída; aceite de Produto |

### Sprint 4

- **Histórias:** `REL-010`, `REL-011`, `REL-012`
- **Objetivo:** consolidar a camada de produtos e margem com base comercial já saneada.

| Item | Conteúdo |
|---|---|
| Entregáveis | Base oficial de produtos vendidos; indicadores de mais vendidos, menos vendidos e sem venda; margem por produto aderente ao custo oficial |
| Riscos | Dependência de definição do custo oficial; sensibilidade alta de indicadores de margem |
| Bloqueadores | Custo não certificado; ausência de regra consolidada para produto ativo comercializável |
| Critérios de saída | CT-012 e CT-014 aprovados; ranking e tabela de produtos conciliados manualmente; homologação de Produtos concluída |

### Sprint 5

- **Histórias:** `REL-013`, `REL-014`, `REL-015`, `REL-016`, `REL-017`, `REL-018`, `REL-019`, `REL-020`, `REL-021`
- **Objetivo:** concluir CRM analítico, governança do customizado, exportações e auditoria.

| Item | Conteúdo |
|---|---|
| Entregáveis | Clientes novos/ativos/inativos oficiais; ranking de clientes oficial; universos segregados no customizado; exportações padronizadas; paridade tela-exportação; trilha de auditoria |
| Riscos | Elevada combinatória de filtros e relatórios customizados; divergência entre tela e arquivos; atraso na homologação final |
| Bloqueadores | Falta de catálogo final de campos permitidos; ausência de política final de auditoria; pendência de aprovação dos sprints anteriores |
| Critérios de saída | CT-013 e CT-014 aprovados; exportações validadas; homologações de Clientes, Personalizados e Exportações concluídas; aceite final de Produto |

## 3. Plano de QA

| Caso | Histórias impactadas | Massa de teste necessária | Resultado esperado | Evidências obrigatórias |
|---|---|---|---|---|
| CT-001 | REL-001, REL-007, REL-008 | 1 pedido válido sem recebimento; 1 título aberto futuro | Faturamento presente; recebido zero; carteira aberta; atraso zero | print dos KPIs; print da tabela financeira; exportação CSV da aba envolvida |
| CT-002 | REL-001, REL-002, REL-004, REL-008, REL-010 | 1 pedido válido com recebimento total e entrada em caixa | Faturamento, recebido e caixa coerentes; carteira zerada | prints da tela financeira e vendas; extrato/exportação comparativa |
| CT-003 | REL-007, REL-008, REL-010 | 1 pedido cancelado sem recebimento; itens de produto vinculados | Pedido não entra em faturamento, ticket, ranking, produtos vendidos | print dos KPIs de vendas; print tabela de vendas; print aba produtos |
| CT-004 | REL-004, REL-006 | 1 pedido com recebimento total seguido de cancelamento + estorno | Trilha reversa auditável; refletir caixa líquido conforme política oficial | prints antes/depois; exportação financeira; evidência de trilha transacional |
| CT-005 | REL-001, REL-003, REL-005 | 1 título de R$ 1.000 com recebimento parcial de R$ 400 | Recebido 400; carteira 600; atraso conforme vencimento | print dos KPIs; print da tabela de títulos/movimentos; exportação CSV |
| CT-006 | REL-001, REL-002, REL-005 | 1 título com recebimento parcelado em duas datas | Recebido distribuído corretamente no período; gráfico temporal coerente | print do gráfico; print do detalhamento; exportação Excel |
| CT-007 | REL-002 | 1 recebimento dividido entre Pix e Cartão | Distribuição por forma rateada corretamente | print do donut/legenda; memória de cálculo manual |
| CT-008 | REL-001, REL-003, REL-005 | 1 título vencido parcialmente pago | Carteira aberta e atraso iguais ao saldo vencido | print de KPI; print de tabela; cálculo manual anexo |
| CT-009 | REL-001, REL-003, REL-005 | 1 título futuro em aberto | Entra na carteira e não entra no atraso | print de KPI; print de filtro/data de corte; exportação CSV |
| CT-010 | REL-002, REL-004, REL-005, REL-006 | conjunto com entrada, saída e ajuste reverso | Fluxo líquido correto; tabela financeira coerente | print do gráfico de caixa; print da tabela; cálculo de reconciliação |
| CT-011 | REL-009 | 10 orçamentos com draft, aprovados, rejeitados e convertidos | Conversão real em pedido conforme especificação | print do KPI; print do gráfico; planilha de verdade |
| CT-012 | REL-010, REL-011, REL-012 | 5 produtos ativos com diferentes níveis de venda e custos | Mais vendidos, menos vendidos, sem venda e margem corretos | print da aba produtos; exportação Excel; memória de cálculo |
| CT-013 | REL-013, REL-014, REL-015 | clientes com primeira compra, compra recente, compra antiga e só cadastro | Novos, ativos, inativos e ranking corretos | print dos KPIs; print do gráfico; print da tabela clientes |
| CT-014 | REL-003, REL-008, REL-009, REL-011, REL-012, REL-013, REL-014, REL-015, REL-016, REL-017, REL-018, REL-019, REL-020, REL-021 | cenário consolidado por aba com filtros e exportações | Tela e exportações coerentes; customizado respeita governança | PDF, Excel, CSV, print; prints da tela; checklist de metadados |
| CT-015 | REL-001, REL-004, REL-005, REL-006 | cenário de fluxo imutável com estorno e reabertura de saldo | Reversão auditável; caixa líquido e carteira consistentes | evidência transacional; print da tela financeira; exportação comparativa |

## 4. Plano de Homologação

| Etapa | Responsável | Pré-requisitos | Evidências | Critério de aprovação |
|---|---|---|---|---|
| Homologação Financeira | Gestor Financeiro + Produto + QA líder | Sprint 1 e Sprint 2 concluídas em QA | prints dos KPIs; exportações PDF/Excel/CSV; memória de cálculo; trilha de estorno/reversão | KPIs financeiros aderentes à especificação; carteira e atraso coerentes; fluxo de caixa reconciliado |
| Homologação Comercial | Gestor Comercial + Produto + QA | Sprint 3 concluída | prints da aba Vendas; exportações; planilha de verdade da conversão; validação de ranking | Faturamento, ticket, pedidos válidos e conversão batendo com a regra oficial |
| Homologação Produtos | Gestor de Produtos/Operações + Financeiro/Controladoria + QA | Sprint 4 concluída | prints da aba Produtos; memória de cálculo de margem; exportação Excel | Mais vendidos, menos vendidos, sem venda e margem aderentes à especificação e ao custo oficial |
| Homologação Clientes | Gestor Comercial/CRM + Produto + QA | REL-013, REL-014 e REL-015 aprovadas em QA | prints da aba Clientes; memória de classificação; exportação CSV/Excel | Novos, ativos, inativos e ranking corretos pela compra válida |
| Homologação Relatórios Personalizados | Produto + usuários-chave + QA | REL-016, REL-017 e REL-018 aprovadas em QA | prints dos presets; exportações de relatórios customizados; validação de bloqueios | Universos segregados, campos governados e exportações coerentes com a tela |
| Homologação Exportações | Produto + QA + representantes dos domínios funcionais | REL-019, REL-020 e REL-021 aprovadas em QA | PDF, Excel, CSV e Impressão por aba; checklists de metadados; logs/auditoria | Paridade completa entre tela e arquivo; metadados obrigatórios presentes; rastreabilidade validada |

## 5. Plano de Evidências

| História | Prints obrigatórios | Exportações obrigatórias | Comparações obrigatórias | Validações manuais obrigatórias |
|---|---|---|---|---|
| REL-001 | KPIs financeiros antes/depois; filtros aplicados | CSV financeiro | KPI vs memória de cálculo | conciliação com Financeiro |
| REL-002 | gráficos financeiros, legendas, tooltips | PDF financeiro | soma do gráfico vs KPI | validação visual + cálculo mensal |
| REL-003 | barra de filtros, tabela financeira, paginação | Excel financeiro | tela vs exportação parcial | validação da data de corte |
| REL-004 | tela de pedido pago, reflexo financeiro | CSV/Excel de apoio | pedido vs pagamento vs caixa | validação transacional com Financeiro |
| REL-005 | título, baixa, reflexo nos KPIs | CSV de recebimentos/carteira | título vs recibos vs caixa | conciliação manual de saldo |
| REL-006 | antes/depois de estorno, histórico da tela | PDF/CSV financeiro | evento original vs reverso | validação formal do fluxo de estorno |
| REL-007 | visão de vendas excluindo cancelados | CSV vendas | base antiga vs nova base saneada | validação de pedido válido |
| REL-008 | cards e gráficos de vendas; ranking | Excel vendas | KPI vs tabela vs gráfico | memória de cálculo comercial |
| REL-009 | card e gráfico de conversão | CSV/Excel de orçamentos | quotes elegíveis vs convertidos | validação com Comercial |
| REL-010 | aba produtos com base limpa | CSV produtos | produto vendido vs item em pedido válido | validação da base de itens |
| REL-011 | KPIs mais/menos/sem venda; gráfico correspondente | Excel produtos | KPI vs tabela de produtos | validação manual do portfólio ativo |
| REL-012 | margem por produto e sinalizações | Excel produtos | receita/custo/lucro/margem | validação Financeiro + Produtos |
| REL-013 | KPI e gráfico de novos clientes | CSV clientes | cadastro vs primeira compra válida | validação CRM |
| REL-014 | KPIs de ativos/inativos; gráfico comparativo | Excel clientes | última compra vs janela de inatividade | validação com Comercial |
| REL-015 | ranking e tabela de clientes | CSV clientes | ranking vs pedidos válidos | validação manual da última compra |
| REL-016 | tela do customizado com universo selecionado | exportação customizada | tentativa de misturas proibidas | validação de governança com Produto |
| REL-017 | seleção de campos, mensagens de bloqueio | exportação customizada | campos permitidos vs proibidos | revisão do catálogo oficial |
| REL-018 | salvar preset, reaplicar preset, exportar | PDF/CSV customizado | tela do preset vs exportação | validação funcional com usuário-chave |
| REL-019 | cabeçalho, rodapé e filtros no documento | PDF, Excel, CSV, impressão | formatos entre si | checklist de metadados |
| REL-020 | tela completa da aba e arquivos gerados | todos os formatos | total da tela vs total exportado | conferência por QA e Produto |
| REL-021 | evidência do log/auditoria associado à exportação | arquivo exportado correspondente | usuário/filtro/data vs registro de auditoria | validação de rastreabilidade |

## 6. Roadmap Final

### Sequência ideal de execução

| Etapa | Histórias | Objetivo do marco |
|---|---|---|
| Marco 1 | REL-001, REL-002, REL-003 | Congelar a verdade financeira analítica em tela |
| Marco 2 | REL-004, REL-005, REL-006 | Blindar a rastreabilidade financeira transacional |
| Marco 3 | REL-007, REL-008, REL-009 | Sanear o universo comercial e o funil |
| Marco 4 | REL-010, REL-011, REL-012 | Consolidar produtos e margem |
| Marco 5 | REL-013, REL-014, REL-015 | Corrigir CRM analítico |
| Marco 6 | REL-016, REL-017, REL-018 | Governar relatórios personalizados |
| Marco 7 | REL-019, REL-020, REL-021 | Fechar exportações, paridade e auditoria |

### Pontos de congelamento por sprint

| Sprint | Ponto de congelamento |
|---|---|
| Sprint 1 | após homologação financeira dos KPIs, filtros, tabela e gráficos |
| Sprint 2 | após aceite da trilha transacional e do comportamento de estorno |
| Sprint 3 | após aprovação comercial de faturamento, ticket e conversão |
| Sprint 4 | após validação de produtos e margem com custo oficial |
| Sprint 5 | após aceite de Clientes, Customizado, Exportações e Auditoria |

### Critérios para início da sprint seguinte

| Sprint seguinte | Critério obrigatório de entrada |
|---|---|
| Sprint 2 | Sprint 1 concluída com QA aprovado e homologação financeira formal |
| Sprint 3 | Sprint 2 concluída com rastreabilidade transacional validada |
| Sprint 4 | Sprint 3 concluída com base comercial saneada |
| Sprint 5 | Sprint 4 concluída com aba Produtos aprovada |
| Encerramento do projeto | Sprint 5 concluída com aceite final de Produto e evidências arquivadas |