# Registro de Decisões - Módulo de Relatórios

## Decisões Funcionais Aprovadas

| Data | Tipo | Decisão aprovada | Justificativa | Aprovador |
|---|---|---|---|---|
| 2026-06-04 | Funcional | `Faturamento` é indicador comercial e deve vir de `orders` | Separar venda de recebimento e impedir mistura conceitual | Aprovado em especificação funcional oficial |
| 2026-06-04 | Funcional | `Valor Recebido` é indicador financeiro por caixa e deve vir de `receivable_receipts`, com reconciliação em `cash_flow` | Garantir medição de liquidação efetiva e não de venda | Aprovado em especificação funcional oficial |
| 2026-06-04 | Funcional | `Contas a Receber` e `Contas em Atraso` são indicadores financeiros por competência | Garantir posição correta da carteira e do atraso por data de corte | Aprovado em especificação funcional oficial |
| 2026-06-04 | Funcional | `Conversão de Orçamentos` deve medir conversão real em pedido, e não mera aprovação | Alinhar o funil comercial à matriz de verdade | Aprovado em matriz de verdade e especificação funcional oficial |
| 2026-06-04 | Funcional | `Novos Clientes` devem ser calculados por primeira compra válida no período | Separar aquisição comercial de simples cadastro | Aprovado em matriz de verdade e especificação funcional oficial |
| 2026-06-04 | Funcional | `Clientes Ativos` e `Clientes Inativos` devem ser calculados por compra válida e janela oficial de inatividade | Garantir CRM analítico aderente à realidade comercial | Aprovado em matriz de verdade e especificação funcional oficial |
| 2026-06-04 | Funcional | Relatórios personalizados devem declarar universo analítico explícito | Impedir mistura indevida entre comercial, caixa, carteira, clientes e produtos | Aprovado em especificação funcional oficial |

## Decisões Técnicas Aprovadas

| Data | Tipo | Decisão aprovada | Justificativa | Aprovador |
|---|---|---|---|---|
| 2026-06-04 | Técnica | Corrigir primeiro o núcleo financeiro analítico antes de qualquer outro universo | Reduzir risco de decisão financeira incorreta | Aprovado no plano de correção oficial |
| 2026-06-04 | Técnica | Executar o projeto em cinco sprints, na ordem oficial definida | Preservar dependências entre financeiro, rastreabilidade, comercial, produtos e clientes | Aprovado no plano de execução |
| 2026-06-04 | Técnica | Toda exportação deve reproduzir a mesma verdade exibida em tela | Garantir auditabilidade e paridade entre visualização e documento exportado | Aprovado na especificação funcional oficial |
| 2026-06-04 | Técnica | Toda mudança futura no módulo deve manter rastreabilidade por história `REL-001` a `REL-021` | Preservar continuidade do projeto entre sessões e facilitar auditoria | Aprovado no backlog executivo e plano de execução |
| 2026-06-04 | Técnica | A implementação da `REL-001` deve ficar restrita à camada analítica do relatório e ao ajuste mínimo de apresentação dos cards financeiros | Preservar o escopo da história e evitar invasão de `REL-002`, `REL-003` e histórias transacionais futuras | Execução da REL-001 autorizada pelo usuário |
| 2026-06-04 | Técnica | Os KPIs oficiais da aba `Financeiro` passam a ser `Valor Recebido`, `Contas a Receber`, `Contas em Atraso` e `Fluxo de Caixa Liquido` | Alinhar a aba à Especificação Funcional Oficial e à Matriz de Verdade | Execução da REL-001 autorizada pelo usuário |
| 2026-06-04 | Técnica | A `REL-001` não altera banco, migrations, triggers, procedures, filtros estruturais amplos nem redesign completo dos gráficos | Preservar o backlog aprovado e manter `REL-002` para gráficos e `REL-003` para filtros/data de corte estrutural | Execução da REL-001 autorizada pelo usuário |
| 2026-06-04 | Técnica | A `REL-001A` pode corrigir exclusivamente a regra de `Contas a Receber` removendo o corte por `due_date <= endDate` na composição da carteira aberta | Corrigir o erro de negócio remanescente da `REL-001` sem invadir o escopo da `REL-002` ou `REL-003` | Autorização explícita do usuário |
| 2026-06-04 | Técnica | A `REL-001` só pode ser considerada concluída se `CT-001`, `CT-002`, `CT-005`, `CT-008`, `CT-009` e `CT-015` estiverem todos aprovados | Preservar o critério formal de encerramento definido pelo usuário para a história | Autorização explícita do usuário |
| 2026-06-04 | Técnica | `REL-002` permanece não autorizada enquanto a `REL-001` estiver pendente ou bloqueada | Evitar avanço indevido para a história seguinte com caso obrigatório ainda reprovado | Autorização explícita do usuário |
| 2026-06-04 | Técnica | O `CT-015` foi formalmente reclassificado para a Sprint 2 e passa a depender das histórias `REL-004`, `REL-005` e `REL-006` | O caso exige rastreabilidade financeira transacional, reversão auditável e dependências de fluxo/banco fora do escopo da `REL-001` | Aprovação explícita do usuário com base em `DECISAO_CT_015.md` |
| 2026-06-04 | Técnica | A `REL-001` passa a ser considerada aprovada com os casos `CT-001`, `CT-002`, `CT-005`, `CT-008` e `CT-009` | Após a reclassificação do `CT-015`, os critérios restantes obrigatórios da história foram atendidos | Aprovação explícita do usuário |
| 2026-06-04 | Técnica | `REL-002` passa a ser a próxima história autorizada, mantendo-se em estado `Não iniciada` até nova ordem de execução | Encerrar formalmente a `REL-001` sem iniciar automaticamente a história seguinte | Aprovação explícita do usuário |
| 2026-06-05 | Técnica | A correção temporal da `REL-002` deve permanecer isolada na aba `Financeiro`, preservando a chave cronológica real em `buildFinancialReport()` e sem ajuste global em `buildSeriesMap()` | Corrigir a ordem cronológica dos gráficos financeiros sem alterar o comportamento de `Vendas`, `Clientes` e `Personalizados` | Autorização explícita do usuário |
| 2026-06-05 | Técnica | Os gráficos oficiais da `REL-002` passam a ser `Recebimentos por período` (`receivable_receipts`), `Fluxo de caixa por período` (`cash_flow`), `Distribuição do recebido por forma de pagamento` (`receivable_receipts`) e `Carteira por status` (`accounts_receivable`) | Fechar semanticamente cada gráfico com os KPIs oficiais da aba `Financeiro` e eliminar divergências entre card e visualização | Execução da REL-002 autorizada pelo usuário |
| 2026-06-05 | Técnica | O PDF da aba `Financeiro` deve suportar séries de linha com valores líquidos negativos sem alterar o comportamento de impressão textual nem das demais abas | Garantir que o gráfico `Fluxo de caixa por período` permaneça coerente em tela e exportação quando houver saldo líquido negativo em algum período | Necessidade técnica identificada e resolvida na REL-002 |
| 2026-06-05 | Técnica | O fechamento da `REL-002A` deve alinhar a comparação do `Financeiro` por chave temporal equivalente do período, sem usar `label` humanizado como chave de pareamento | Corrigir o bloqueio funcional apontado na auditoria mantendo a correção isolada no frontend autorizado da história | Execução da REL-002A autorizada pelo usuário |
| 2026-06-05 | Técnica | `PDF` e `Print` da aba `Relatórios` devem expor minimamente `usuário gerador`, `data/hora`, `timezone`, `critério de ordenação`, `total de registros`, `versão/regra utilizada` e `filtros aplicados` | Fechar o `CT-014` com aderência mínima à `ESPECIFICACAO_OFICIAL.md` sem ampliar o escopo para backend ou banco | Execução da REL-002A autorizada pelo usuário |
| 2026-06-05 | Técnica | A `REL-003` deve separar explicitamente o catálogo financeiro do catálogo genérico, mantendo `paymentMethods/statuses` das demais abas e adicionando `financialPaymentMethods`, `financialStatuses`, `bankAccounts`, `financialCategories` e `channels` apenas para a aba `Financeiro` | Corrigir o catálogo financeiro oficial sem regredir `Vendas`, `Produtos`, `Clientes` ou `Customizados` | Execução da REL-003 autorizada pelo usuário |
| 2026-06-05 | Técnica | A tabela da aba `Financeiro` passa a consolidar três bases analíticas explícitas: `Recebimento`, `Fluxo de caixa` e `Carteira` | Garantir paridade entre KPIs, gráficos, tabela e exportações sem depender de reconciliação transacional fora do escopo da Sprint 1 | Execução da REL-003 autorizada pelo usuário |
| 2026-06-05 | Técnica | Os filtros financeiros da `REL-003` devem atuar por universo oficial, sem remover linhas nem valores de subconjuntos onde o filtro não possui semântica confiável | Preservar a coerência analítica entre caixa e competência, evitando misturas indevidas e sem invadir `REL-004`, `REL-005` ou `REL-006` | Execução da REL-003 autorizada pelo usuário |
| 2026-06-05 | Técnica | A `REL-004` deve formalizar a trilha `payments -> cash_flow -> orders` no banco por functions e triggers dedicadas, sem depender de sincronismo implícito na aplicação | Garantir que todo pagamento de pedido produza reflexo oficial em caixa e recomposição determinística do resumo financeiro do pedido | Execução da REL-004 autorizada pelo usuário |
| 2026-06-05 | Técnica | A exclusão manual de pagamentos e o cancelamento PDV passam a usar reversão compensatória auditável em `cash_flow`, preservando o evento original como trilha principal | Eliminar a exclusão física de `cash_flow` como fluxo principal e manter o cancelamento PDV sob a mesma política oficial de estorno do domínio `pedido/pagamento/caixa` | Execução da REL-004 autorizada pelo usuário |
| 2026-06-05 | Técnica | O troco do PDV deixa de compor o `cash_flow` oficial da venda e permanece apenas como movimento operacional em `pdv_cash_movements` | Evitar dupla redução do caixa oficial quando a entrada principal da venda já passa a ser formalizada a partir de `payments` | Implementação técnica necessária dentro da REL-004 |
| 2026-06-05 | Técnica | A `REL-005` deve formalizar a baixa do título exclusivamente por routines persistidas (`register_receipt_with_cash_flow`, `sync_receivable_summary` e `create_cash_flow_from_receipt`), deixando a API apenas como consumidora da política oficial | Garantir consistência transacional entre `accounts_receivable`, `receivable_receipts` e `cash_flow` sem depender de sincronismo implícito nas rotas | Execução da REL-005 autorizada pelo usuário |
| 2026-06-05 | Técnica | O ciclo de vida de `accounts_receivable` passa a bloquear mutação manual dos status calculados (`PAID`, `PARTIALLY_PAID`, `OVERDUE`) e a preservar explicitamente `CANCELED` no resumo financeiro | Impedir que edição manual contradiga a soma oficial dos recibos e evitar reclassificação indevida de títulos cancelados | Execução da REL-005 autorizada pelo usuário |
| 2026-06-05 | Técnica | A reabertura mínima da `REL-005` fica restrita ao domínio `receivable_receipts -> accounts_receivable -> cash_flow`, sem encerrar a política universal de estorno auditável nem o `CT-015` | Preparar a infraestrutura mínima de reversão do título sem invadir a `REL-006` e sem quebrar a separação formal definida para a Sprint 2 | Execução da REL-005 autorizada pelo usuário |
| 2026-06-05 | Técnica | A página operacional `financial/receivables` deixa de usar `orders` como pseudo-carteira e passa a refletir somente `accounts_receivable` como fonte oficial da carteira de títulos | Eliminar a verdade híbrida entre pedido comercial e título financeiro, alinhando a superfície operacional à matriz de verdade aprovada | Execução da REL-005 autorizada pelo usuário |
| 2026-06-05 | Técnica | A `REL-006` substitui definitivamente a exclusão física de `payments` por reversão lógica auditável, preservando o evento original em `payments` e gerando compensação explícita em `cash_flow` | Fechar o `CT-015` sem reabrir a base da `REL-004`, mantendo rastreabilidade entre evento original, motivo, executor e timestamp | Execução da REL-006 autorizada pelo usuário |
| 2026-06-05 | Técnica | O contrato universal de reversão passa a exigir vínculo estrutural entre lançamento original e lançamento reverso em `cash_flow`, via `reversal_of_id`, `reversed_by` e `reversal_reason` | Eliminar dependência exclusiva de convenção textual e alinhar leitura operacional/analítica ao mesmo rastro oficial | Execução da REL-006 autorizada pelo usuário |
| 2026-06-05 | Técnica | O motor de comissão deixa de reagir à exclusão física de `payments` e passa a reverter `commission_events` por atualização lógica de `reversed_at` no pagamento | Incorporar a dependência de comissão identificada na auditoria e completar a rastreabilidade derivada do `payment_id` | Execução da REL-006 autorizada pelo usuário |
| 2026-06-05 | Técnica | O cancelamento `PDV` deixa de apagar `cash_flow` e `pdv_cash_movements`, passando a registrar compensação operacional explícita e a consumir a mesma rotina oficial de reversão financeira do pedido | Unificar a política de reversão auditável também na superfície operacional do `PDV` sem reabrir `checkout` | Execução da REL-006 autorizada pelo usuário |
| 2026-06-05 | Técnica | A exceção controlada em `service.ts` fica restrita a `buildFinancialReport()`, alterando apenas o KPI `Valor Recebido` para refletir o líquido oficial por `cash_flow` de recebíveis após reversões auditáveis | Fechar analiticamente o `CT-015` sem alterar layout, filtros, gráficos ou contratos públicos da API de relatórios | Autorização explícita de exceção controlada pelo usuário |