# Auditoria do Diagnóstico Técnico - REL-004 ## Objetivo Auditar exclusivamente o conteúdo de `DIAGNOSTICO_REL_004.md`, validando: - a delimitação correta entre `REL-004`, `REL-005` e `REL-006`; - os problemas que realmente pertencem à `REL-004`; - os arquivos realmente necessários; - os impactos efetivos sobre `payments`, `cash_flow`, `orders`, `cancel-sale`, `receive`, comissão e relatórios financeiros; - se a implementação da `REL-004` pode ocorrer sem alterar banco, migrations, triggers e procedures; - os casos de teste realmente afetados; - a recomendação formal de autorização ou não para implementação. ## Veredito Sobre o Diagnóstico ### Veredito geral O `DIAGNOSTICO_REL_004.md` está **majoritariamente correto** ao identificar: - que existe um problema real na trilha `orders -> payments -> cash_flow`; - que há inconsistência ou opacidade na criação do `cash_flow` com `origin = PEDIDO`; - que o cancelamento PDV depende de reversão financeira sensível; - que a Sprint 2 é o lugar correto para tratar rastreabilidade transacional. ### Correção obrigatória do diagnóstico Apesar de correto no núcleo, o diagnóstico ficou **amplo demais** em dois pontos: 1. puxou itens do universo `accounts_receivable` / `receivable_receipts` para dentro da análise central da `REL-004` com peso maior do que o necessário; 2. concluiu `REL-004 AUTORIZADA`, mas os próprios documentos oficiais indicam que a implementação **não é segura nem aderente** sem alterações de banco, migrations, triggers e procedures. Conclusão da auditoria: - o diagnóstico acerta o problema estrutural; - erra ao ser permissivo demais na autorização final; - a recomendação formal precisa ser reclassificada. ## Delimitação Correta Entre REL-004, REL-005 e REL-006 ### REL-004 Pertence corretamente à `REL-004`: - trilha oficial entre `orders`, `payments` e `cash_flow`; - criação oficial do reflexo financeiro de um pagamento de pedido; - sincronização consistente entre pagamento do pedido e resumo financeiro de `orders`; - cancelamento e reversão de pagamento de pedido, especialmente no PDV; - regra de consistência entre evento operacional de pagamento e efeito em caixa. ### REL-005 Pertence corretamente à `REL-005`: - trilha entre `accounts_receivable`, `receivable_receipts` e `cash_flow`; - baixa formal de títulos; - reabertura de saldo da carteira por estorno de recebimento; - consistência entre título, recibo e saldo em aberto; - manutenção da trigger `sync_accounts_receivable_status()`. ### REL-006 Pertence corretamente à `REL-006`: - política transversal de estorno e reversão auditável; - padronização definitiva do modelo imutável ou híbrido; - vínculo formal entre evento original e evento reverso; - governança universal de exclusão versus compensação; - fechamento completo do `CT-015`. ### Sprint 2 posterior / fora do escopo imediato da REL-004 Devem permanecer fora da `REL-004`: - correções em relatórios financeiros analíticos; - ajuste de KPI de recebido líquido em `service.ts`; - reclassificação de carteira no frontend; - qualquer mudança para exportações ou tabela analítica; - fechamento completo de rastreabilidade entre pedido, título, recebimento e caixa no mesmo pacote. ## Escopo Correto da REL-004 O escopo correto da `REL-004` é: - garantir que todo pagamento de pedido tenha reflexo rastreável em `cash_flow`; - garantir que cancelamento de pedido pago, especialmente no PDV, trate reversão de caixa de forma consistente; - garantir que `orders.paid_amount` e `orders.financial_status` fechem com a política oficial do pagamento; - consolidar a trilha do domínio `pedido/pagamento/caixa`, sem assumir o domínio `título/recebimento/carteira`. ## Escopo Incorreto Identificado no Diagnóstico ### Classificação incorreta 1 - **Tema:** `receive route.ts` - **Diagnóstico:** tratado como parte relevante do núcleo da `REL-004` - **Auditoria:** pertence principalmente à `REL-005` - **Justificativa:** o endpoint opera sobre `accounts_receivable` e `receivable_receipts`, não sobre o trilho principal `orders -> payments -> cash_flow` ### Classificação incorreta 2 - **Tema:** `accounts-receivable/route.ts` - **Diagnóstico:** trazido para a análise estrutural da `REL-004` - **Auditoria:** é secundário e fora do núcleo da história - **Justificativa:** a criação e manutenção de títulos manuais é tema da trilha de carteira, não da trilha de pagamento do pedido ### Classificação incorreta 3 - **Tema:** `68_add_accounts_receivable_manual.sql` - **Diagnóstico:** apontado como peça relevante da história - **Auditoria:** pertence à `REL-005` - **Justificativa:** a trigger `sync_accounts_receivable_status()` é importante para recebimentos de títulos, não para a trilha principal de pagamentos de pedidos ### Classificação incorreta 4 - **Tema:** `service.ts` e relatórios financeiros - **Diagnóstico:** corretamente tratou como "não devem ser alterados", mas ainda os citou como área contaminável - **Auditoria:** devem permanecer expressamente fora da implementação da `REL-004` - **Justificativa:** a Sprint 1 já congelou a camada analítica; reabrir isso aqui misturaria histórias ## Problemas que Realmente Pertencem à REL-004 ### Problema 1 - ausência de evidência clara e única para a criação do `cash_flow` vinculado ao `payments.insert` ### Problema 2 - dependência de exclusão física de `payments` e `cash_flow` como caminho primário em alguns cenários ### Problema 3 - cancelamento PDV com múltiplos efeitos paralelos em `payments`, `pdv_cash_movements`, `cash_flow` e `orders` ### Problema 4 - sincronização insuficientemente explícita entre pagamento do pedido e resumo financeiro do próprio pedido ### Problema 5 - risco de divergência entre evento operacional (`payments`) e livro caixa (`cash_flow`) ## Problemas que Não Pertencem Primariamente à REL-004 ### REL-005 - reversão formal de `receivable_receipts` - reabertura de carteira em `accounts_receivable` - coerência entre título manual, recibo e caixa - governança do endpoint `receive` ### REL-006 - política única e definitiva de fluxo imutável - estratégia universal de compensação versus exclusão - vínculo auditável genérico entre evento original e reverso - encerramento completo do `CT-015` ### Sprint 2 posterior - ajustes analíticos de `Recebido Líquido` no relatório - ajustes de exportação - adequação de dashboards que consomem estado financeiro derivado ## Revisão dos Arquivos Apontados ## Arquivos Obrigatórios - `apps/admin/src/app/actions/financial.ts` - contém `registerPayment()` e `deletePayment()` - é o ponto mais direto do domínio `orders -> payments` - `apps/admin/src/app/api/pdv/cancel-sale/route.ts` - é o fluxo explícito de cancelamento com reversão financeira de pedido pago - `apps/admin/src/app/api/pdv/checkout/route.ts` - é o fluxo explícito de criação do pagamento no PDV e precisa fechar com o caixa oficial - `apps/admin/src/db/migrations/70_make_delete_payment_compatible_with_immutable_cash_flow.sql` - já é a procedure central de exclusão/reversão de pagamentos ## Arquivos Prováveis - nova migration para formalizar a rotina oficial `payments -> cash_flow -> orders` - o próprio backlog e plano de correção classificam `REL-004` como história de banco - procedure ou trigger oficial de sincronização de resumo financeiro do pedido - necessária se o comportamento atual continuar implícito - eventual ajuste em migration/procedure predecessora `60_add_safe_payment_cleanup.sql` - apenas se o histórico de versões da procedure ainda estiver ativo em ambiente legado ## Arquivos Condicionais - `apps/admin/src/db/migrations/63_add_commission_payment_engine.sql` - não é alvo da história - pode exigir revalidação ou pequeno ajuste apenas se a nova estratégia de pagamentos alterar o ciclo de insert/delete - `apps/admin/src/app/api/cash-flow/route.ts` - pode exigir adaptação apenas se a semântica dos eventos de caixa mudar visivelmente para leitura operacional ## Arquivos que Não Devem Ser Alterados - `apps/admin/src/app/api/accounts-receivable/[id]/receive/route.ts` - `apps/admin/src/app/api/accounts-receivable/route.ts` - `apps/admin/src/db/migrations/68_add_accounts_receivable_manual.sql` - `apps/admin/src/lib/reports/service.ts` - `apps/admin/src/components/reports/report-page-client.tsx` - `apps/admin/src/lib/reports/contracts.ts` - `apps/admin/src/app/api/reports/route.ts` - `apps/admin/src/app/api/reports/export/route.ts` - `apps/admin/src/app/dashboard/financial/receivables/page.tsx` Justificativa: - esses arquivos pertencem ao domínio de carteira/recebimento (`REL-005`) ou à camada analítica já fechada na Sprint 1. ## Impactos por Domínio ### payments - impacto direto e central - é o ponto de entrada do pagamento do pedido - a história depende de tornar esse evento rastreável até o caixa ### cash_flow - impacto direto e central - precisa refletir oficialmente o pagamento do pedido - precisa suportar reversão coerente no cancelamento ### orders - impacto direto e central - `paid_amount` e `financial_status` precisam fechar com a política oficial do pagamento ### cancel-sale - impacto direto e central - já contém reversão parcial e fallback compensatório - é um dos fluxos mais críticos da `REL-004` ### receive - impacto apenas indireto - deve ser observado por coerência arquitetural - não deve ser alvo principal da `REL-004` ### comissão - impacto indireto de alto risco - não é escopo funcional da história - qualquer mudança no ciclo de `payments` pode disparar efeitos colaterais nas triggers de comissão ### relatórios financeiros - impacto indireto - relatórios são consumidores da trilha transacional - não devem ser alterados nesta história ## Pode Implementar a REL-004 Sem Banco, Migrations, Triggers e Procedures? - **Não** ### Fundamentação documental Conforme os documentos oficiais: - `BACKLOG_EXECUTIVO.md` classifica `REL-004` como `Banco de dados`, `Auditoria`, `Regra analítica`, `API` - `PLANO_DE_EXECUCAO.md` atribui `REL-004` à squad de `Banco de Dados` - `PLANO_DE_CORRECAO.md` Fase 2 lista explicitamente migrations, procedures, triggers e revisão de banco como parte da correção ### Fundamentação técnica O problema central da `REL-004` não é apenas de API: - a exclusão/reversão já passa por procedure; - o modelo atual depende de comportamento persistido em `cash_flow`; - o sincronismo de resumo do pedido não está formalizado de forma visível no código de aplicação; - qualquer solução segura precisará endurecer a camada persistida. Conclusão: - uma implementação "sem banco" descaracteriza a `REL-004`; - se houver restrição para não alterar migrations, triggers e procedures, a história não deve ser iniciada. ## CTs Realmente Afetados ### CTs diretamente afetados - `CT-002` - coerência entre pedido pago e entrada em caixa - `CT-004` - cancelamento após recebimento com estorno formal - `CT-010` - fluxo líquido com entrada, saída e ajuste reverso no universo de pagamentos/cancelamentos ### CT afetado de forma parcial e dependente - `CT-015` - a `REL-004` participa do cenário, mas não o encerra sozinha - o fechamento completo continua dependente de `REL-005` e `REL-006` ### CTs que não pertencem ao núcleo da REL-004 - `CT-005`, `CT-006`, `CT-008`, `CT-009` - pertencem ao universo de títulos e recebimentos - devem permanecer em `REL-005` ## Dependências com REL-005 e REL-006 ### Dependência com REL-005 - a `REL-004` deve fechar o lado `pedido/pagamento/caixa` - a `REL-005` deve fechar o lado `título/recebimento/caixa` - ambas precisam convergir, mas não devem ser implementadas como uma única história ### Dependência com REL-006 - a `REL-006` depende da consolidação prévia das duas trilhas - a política transversal de estorno não deve ser embutida prematuramente na `REL-004` ## Riscos de Regressão ### 1. Regressão em PDV - o cancelamento PDV já opera com múltiplos artefatos paralelos - qualquer alteração mal delimitada pode quebrar reversão de venda já realizada ### 2. Regressão em comissão - mudanças no ciclo de vida de `payments` podem acionar ou impedir reversões de comissão ### 3. Regressão em legado financeiro - pagamentos antigos podem não possuir trilha consistente em `cash_flow` ### 4. Mistura indevida com carteira - se a `REL-004` tocar `receive` e `accounts_receivable`, invadirá a `REL-005` ### 5. Reabertura indevida da camada analítica - mexer em relatórios ou dashboards nesta etapa causará regressão de escopo ## Estratégia Recomendada 1. Reclassificar formalmente o escopo da `REL-004` para o núcleo `orders`, `payments`, `cash_flow`, `pdv checkout`, `cancel-sale` e procedures correlatas. 2. Excluir do pacote principal da história qualquer alteração em `receive`, `accounts_receivable` e `sync_accounts_receivable_status()`. 3. Exigir autorização explícita para banco, migrations, triggers e procedures antes da implementação. 4. Preservar `service.ts` e demais arquivos da camada de relatórios fora da execução da história. 5. Tratar `CT-015` apenas como dependência parcial da `REL-004`, e não como critério encerrável isoladamente. ## Conclusão Executiva O diagnóstico auditado: - **acerta** ao afirmar que existe um problema real e crítico na trilha `orders -> payments -> cash_flow`; - **acerta** ao situar a matéria na Sprint 2; - **erra** ao manter peso excessivo em arquivos e problemas do domínio `accounts_receivable` / `receivable_receipts`; - **erra** ao concluir `REL-004 AUTORIZADA` sem impor como condição obrigatória a liberação para alterações de banco, migrations, triggers e procedures. ## Classificação Final - **REL-004 NÃO AUTORIZADA** ### Fundamentação final 1. O escopo correto da história é válido e necessário. 2. Porém, a implementação não pode ocorrer de forma aderente sem banco, migrations, triggers e procedures. 3. Os próprios documentos oficiais do projeto classificam a história como dependente da camada de banco. 4. Logo, a história não deve ser autorizada para implementação enquanto essas frentes continuarem fora de autorização. ### Condição para futura autorização A `REL-004` só poderá ser reclassificada como autorizável quando houver autorização explícita para: - alterar banco; - criar/ajustar migrations financeiras; - revisar triggers e procedures relacionadas ao ciclo de `payments` e `cash_flow`; - validar impactos colaterais em `orders`, `PDV` e comissão.