# Diagnóstico Técnico - REL-004 ## Objetivo Diagnosticar exclusivamente a `REL-004`, sem implementar correções, sem alterar código, banco, migrations, triggers, procedures ou documentação existente, definindo: - fluxo atual entre `orders`, `payments`, `accounts_receivable`, `receivable_receipts` e `cash_flow`; - origem oficial da verdade financeira; - comportamento atual de recebimento, cancelamento, estorno, reversão, reabertura de carteira e sincronização financeira; - divergências entre o estado atual e a especificação oficial; - dependências entre `REL-004`, `REL-005` e `REL-006`; - riscos, estratégia recomendada, critério de aceite e recomendação formal de autorização. ## Escopo Oficial da REL-004 Conforme o backlog executivo, a `REL-004` tem como objetivo: - validar a trilha oficial entre `orders`, `payments` e `cash_flow`; - padronizar a consistência entre pedido, pagamento e caixa; - preparar a rastreabilidade transacional da Sprint 2 sem reabrir a camada analítica já estabilizada na Sprint 1. Referências documentais principais: - `BACKLOG_EXECUTIVO.md`: `REL-004 = Validar trilha oficial entre pedidos, pagamentos e fluxo de caixa` - `PLANO_DE_CORRECAO.md`: Fase 2 fortalece rastreabilidade financeira oficial - `PLANO_DE_EXECUCAO.md`: `REL-004` é a primeira história do Marco 2 / Sprint 2 - `CASOS_DE_TESTE.md`: casos diretamente impactados `CT-002`, `CT-004`, `CT-010`, `CT-015` ## Documentos Obrigatórios Considerados - `ESPECIFICACAO_OFICIAL.md` - `MATRIZ_DE_VERDADE.md` - `BACKLOG_EXECUTIVO.md` - `PLANO_DE_CORRECAO.md` - `PLANO_DE_EXECUCAO.md` - `CASOS_DE_TESTE.md` - `STATUS.md` - `CHANGELOG.md` - `DECISOES.md` - `DECISAO_CT_015.md` ## Arquivos e Fluxos Inspecionados ### Arquivos primários de fluxo - `apps/admin/src/app/actions/financial.ts` - `apps/admin/src/app/api/pdv/checkout/route.ts` - `apps/admin/src/app/api/pdv/cancel-sale/route.ts` - `apps/admin/src/app/api/accounts-receivable/[id]/receive/route.ts` - `apps/admin/src/app/api/accounts-receivable/route.ts` - `apps/admin/src/app/api/cash-flow/route.ts` ### Migrations / procedures / triggers financeiras - `apps/admin/src/db/migrations/60_add_safe_payment_cleanup.sql` - `apps/admin/src/db/migrations/63_add_commission_payment_engine.sql` - `apps/admin/src/db/migrations/68_add_accounts_receivable_manual.sql` - `apps/admin/src/db/migrations/69_update_cash_flow_origin_receber.sql` - `apps/admin/src/db/migrations/70_make_delete_payment_compatible_with_immutable_cash_flow.sql` - `apps/admin/src/db/migrations/62_copy_sales_assignment_to_orders.sql` ### Arquivos auxiliares relevantes para evidência estrutural - `apps/admin/src/app/dashboard/financial/receivables/page.tsx` - `apps/admin/src/lib/reports/service.ts` ## Origem Oficial da Verdade Financeira Segundo `ESPECIFICACAO_OFICIAL.md` e `MATRIZ_DE_VERDADE.md`: - `orders` representam a obrigação comercial e a verdade do que foi vendido; - `payments` são eventos operacionais/comerciais de pagamento do pedido, mas não são a verdade oficial de caixa por si só; - `accounts_receivable` representam a carteira por competência; - `receivable_receipts` representam a liquidação oficial da carteira; - `cash_flow` representa o livro caixa oficial e deve refletir apenas eventos financeiros válidos e auditáveis; - cancelamento não pode apagar implicitamente o passado; - estorno não pode ser tratado como simples exclusão histórica quando já houve efeito financeiro. Conclusão conceitual para a `REL-004`: - a história não deve redefinir `Valor Recebido`, `Carteira` ou `Atraso`; - a história deve fechar a trilha transacional entre `pedido`, `pagamento` e `caixa`; - `payments` só é aceitável como elo operacional se houver reflexo oficial, auditável e reversível em `cash_flow`. ## Fluxo Atual Documentado ### 1. Fluxo atual de pedido para pagamento manual Em `financial.ts`: - `registerPayment()` valida saldo pendente usando `orders.total_amount - orders.paid_amount`; - em seguida insere um registro em `payments`; - o fluxo visível não cria `cash_flow` nesse mesmo ponto; - o fluxo visível também não mostra a rotina oficial que sincroniza `orders.paid_amount` e `orders.financial_status` após o insert do pagamento. Em `deletePayment()`: - a exclusão não remove o pagamento diretamente; - o caminho usa a procedure `delete_payment_with_cleanup()`. ### 2. Procedure atual de exclusão de pagamento Em `60_add_safe_payment_cleanup.sql` e `70_make_delete_payment_compatible_with_immutable_cash_flow.sql`: - a procedure procura o pagamento e o pedido correspondente; - bloqueia exclusão manual para vendas PDV; - tenta localizar e remover `cash_flow` com `origin = 'PEDIDO'` e `reference_id = payment.id`; - em versão mais recente, se a exclusão do `cash_flow` falhar em ambiente imutável, cria um lançamento compensatório `OUT / AJUSTE`; - depois exclui fisicamente o registro de `payments`. Ou seja: - a procedure pressupõe a existência de um lançamento anterior em `cash_flow` vinculado ao pagamento; - porém essa criação correspondente não foi localizada no código rastreável do repositório. ### 3. Fluxo atual de venda PDV Em `pdv/checkout/route.ts`: - a venda aprova orçamento e gera pedido via `approve_quote_and_generate_order`; - o pedido é marcado como `delivered`; - para valor maior que zero, o fluxo insere registros em `payments`; - para pagamento em dinheiro, também insere `pdv_cash_movements`; - para troco, insere `cash_flow` com `type = OUT` e `origin = AJUSTE`. Ponto crítico: - o fluxo visível insere `payments`, `pdv_cash_movements` e `cash_flow` apenas para troco; - não há, no código inspecionado, a criação explícita do `cash_flow` principal da entrada da venda com `origin = PEDIDO`; - ainda assim o cancelamento PDV tenta localizar e remover exatamente esse `cash_flow PEDIDO`. ### 4. Fluxo atual de cancelamento PDV Em `pdv/cancel-sale/route.ts`: - busca todos os `payments` da venda; - remove `pdv_cash_movements` vinculados ao pedido e/ou pagamento; - procura `cash_flow` com `origin = PEDIDO` e `reference_id in paymentIds`; - tenta excluir fisicamente esses lançamentos; - se a exclusão falhar, cria saídas compensatórias `OUT / AJUSTE`; - depois exclui fisicamente os `payments`; - por fim marca o pedido como `canceled`, zera `paid_amount` e define `financial_status = unpaid`. Esse fluxo evidencia: - existe preocupação com reversão de caixa; - mas a estratégia atual ainda privilegia exclusão física quando possível; - o fallback compensatório só entra em alguns cenários; - não existe vínculo formal universal entre evento original e evento reverso em `cash_flow`. ### 5. Fluxo atual de carteira manual e recebimento Em `accounts-receivable/route.ts` e `receive/route.ts`: - títulos manuais são criados diretamente em `accounts_receivable`; - um recebimento cria `receivable_receipts`; - o mesmo endpoint tenta criar `cash_flow` com `origin = RECEBER`; - em banco antigo, se `RECEBER` não for aceito, faz fallback para `origin = MANUAL` com tag `[RECEBER]`; - a trigger `sync_accounts_receivable_status()` recalcula `accounts_receivable.paid_amount` e `status`; - se a inserção em `cash_flow` falhar, o endpoint apaga o `receivable_receipts` recém-criado. Esse fluxo pertence mais diretamente a `REL-005`, mas mostra um padrão importante para a `REL-004`: - existe uma tentativa de consistência transacional local; - porém a reversão formal desse recebimento não está exposta na mesma maturidade do caminho de pagamentos de pedido. ### 6. Como a tela de recebíveis funciona hoje Em `dashboard/financial/receivables/page.tsx`: - a tela busca `orders` e trata `orders.paid_amount` e `orders.financial_status` como recebíveis de pedido; - em paralelo, busca `accounts_receivable` manuais pela API; - depois mescla ambas as bases na mesma listagem. Conclusão: - hoje coexistem duas verdades operacionais para "contas a receber": - pedidos com saldo em `orders`; - títulos manuais em `accounts_receivable`; - não foi localizado vínculo oficial que materialize pedidos em `accounts_receivable`. ## Modelo Atual de Fluxo Imutável O repositório mostra um modelo parcialmente híbrido: - parte dos fluxos ainda tenta apagar fisicamente `cash_flow`; - se o ambiente impedir a exclusão, alguns caminhos registram um evento compensatório; - a procedure `delete_payment_with_cleanup()` já fala explicitamente em modo imutável `append-only`; - o cancelamento PDV também possui fallback compensatório; - o fluxo de recebimento de `accounts_receivable` não possui reversão auditável equivalente exposta. Portanto, o modelo atual não é plenamente imutável nem plenamente mutável: - ele é híbrido; - depende do sucesso ou fracasso da exclusão física; - não entrega um padrão único, previsível e auditável para reversão. ## Fluxo Correto Segundo a Especificação ### 1. Trilho oficial `orders -> payments -> cash_flow` O comportamento correto para a `REL-004` deveria ser: - um pagamento confirmado do pedido gera um evento operacional em `payments`; - o mesmo evento gera, de forma oficial e rastreável, um lançamento correspondente em `cash_flow`; - o pedido passa a refletir `paid_amount` e `financial_status` coerentes com esse evento; - toda reversão posterior preserva o evento original e gera um evento reverso auditável; - o vínculo entre original e reverso deve ser explícito e reproduzível. ### 2. Cancelamento e estorno Segundo a especificação: - cancelamento comercial não deve apagar automaticamente o passado financeiro; - se houve efeito financeiro anterior, o cancelamento precisa gerar reversão formal; - a reversão deve ajustar caixa líquido sem destruir trilha histórica; - exclusão física só é aceitável antes de qualquer efeito financeiro oficial ou em política explicitamente aprovada. ### 3. Separação entre histórias - `REL-004` deve fechar o elo `orders`, `payments`, `cash_flow`; - `REL-005` deve fechar o elo `accounts_receivable`, `receivable_receipts`, `cash_flow`; - `REL-006` deve padronizar estorno, reversão e reabertura de saldo de forma transversal e auditável. ## Divergências Principais Encontradas ### Divergência 1 - **Tema:** criação do `cash_flow` de pagamento do pedido. - **Atual:** o repositório mostra leitura, exclusão e reversão de `cash_flow` com `origin = PEDIDO`, mas não mostra a criação correspondente no momento do `payments.insert`. - **Correto:** todo pagamento do pedido deve gerar sua contrapartida oficial em `cash_flow` por rotina única e rastreável. ### Divergência 2 - **Tema:** sincronização de `orders.paid_amount` e `orders.financial_status`. - **Atual:** `registerPayment()` usa esses campos para validar saldo, mas a rotina oficial que os sincroniza não aparece no fluxo inspecionado. - **Correto:** o resumo financeiro do pedido deve ser derivado por mecanismo explícito e confiável. ### Divergência 3 - **Tema:** modelo de reversão. - **Atual:** alguns caminhos apagam fisicamente eventos; apenas em fallback criam compensação. - **Correto:** a reversão deve ser auditável por padrão, não somente quando a exclusão falha. ### Divergência 4 - **Tema:** rastreabilidade universal. - **Atual:** o motor de comissão em `63_add_commission_payment_engine.sql` já possui geração e reversão formais por triggers em `payments`, mas não existe padrão equivalente claramente visível para `cash_flow` do pagamento do pedido. - **Correto:** caixa deveria ter o mesmo grau de rastreabilidade que a comissão já possui. ### Divergência 5 - **Tema:** coexistência de duas carteiras. - **Atual:** a UI de recebíveis combina `orders` e `accounts_receivable` como bases paralelas. - **Correto:** a trilha operacional deve declarar claramente quando o saldo do pedido é apenas resumo comercial e quando há título financeiro oficial. ### Divergência 6 - **Tema:** reabertura de carteira. - **Atual:** a reabertura formal de saldo existe para `accounts_receivable` quando `receivable_receipts` é apagado, mas não há fluxo equivalente visível para pedido/pagamento. - **Correto:** a reversão financeira deve reabrir o saldo correto no domínio correto, sem depender de exclusão implícita. ## Como os Recebimentos Impactam Hoje ### Carteira - no universo de títulos manuais, `receivable_receipts` recalcula `accounts_receivable.paid_amount` e `status` via trigger; - no universo de pedidos, a carteira operacional é tratada por `orders.paid_amount` e `orders.financial_status`, sem vínculo materializado em `accounts_receivable`. ### Caixa - no caminho de títulos manuais, o recebimento tenta gerar `cash_flow` com `origin = RECEBER`; - no caminho de pedidos, o repositório pressupõe que exista `cash_flow PEDIDO`, mas essa criação não foi localizada de forma explícita; - no PDV, existe ainda uma trilha paralela por `pdv_cash_movements`. ### Relatórios - após `REL-001`, `REL-002` e `REL-003`, o relatório financeiro oficial usa: - `receivable_receipts` para recebido; - `accounts_receivable` para carteira e atraso; - `cash_flow` para caixa; - portanto, qualquer fragilidade transacional em `payments -> cash_flow` contamina conciliação e rastreabilidade, mesmo que os relatórios analíticos já estejam semanticamente corretos. ## Cenários que Hoje Quebram ou Permanecem Frágeis ### 1. Pagamento sem evidência clara de reflexo em caixa - o código visível insere `payments`; - a trilha correspondente de `cash_flow PEDIDO` não foi localizada no mesmo nível de evidência. ### 2. Estorno dependente de exclusão física - exclusão do pagamento ainda é o caminho principal; - reversão compensatória aparece como fallback, não como padrão primário universal. ### 3. Pedido cancelado com múltiplos efeitos laterais - PDV remove `payments`, `pdv_cash_movements` e tenta remover `cash_flow`; - o risco de divergência entre esses trilhos é alto em caso de falha parcial. ### 4. Auditoria assimétrica entre domínios - comissão já possui eventos `earned` e `reversal` formalizados; - caixa do pagamento ainda não mostra o mesmo padrão de vínculo explícito entre original e reverso. ### 5. Reabertura de saldo incompleta - títulos manuais podem reabrir saldo pela exclusão de `receivable_receipts`; - pagamentos de pedido não mostram equivalente transacional claro no repositório inspecionado. ## Dependências Entre REL-004, REL-005 e REL-006 ### REL-004 Responsável por: - trilha oficial entre `orders`, `payments` e `cash_flow`; - sincronização confiável do resumo financeiro do pedido; - cancelamento e reversão de pagamentos de pedido com impacto correto em caixa. ### REL-005 Responsável por: - trilha oficial entre `accounts_receivable`, `receivable_receipts` e `cash_flow`; - baixa de título, saldo remanescente e reabertura de carteira; - fechamento entre recebimento e título. ### REL-006 Responsável por: - padronização transversal de estorno, reversão e reabertura; - formalização do modelo imutável/append-only; - vínculo auditável entre evento original e reverso em todos os domínios financeiros. ### Conclusão de dependência - `REL-004` pode e deve ser diagnosticada isoladamente; - `REL-004` não aprova sozinha o `CT-015`; - `CT-015` continua dependendo do conjunto `REL-004 + REL-005 + REL-006`; - qualquer tentativa de fechar reversão completa só em `REL-004` invadirá escopo das histórias seguintes. ## Casos de Teste Afetados ### CT-002 - depende da coerência entre pedido válido, pagamento total e entrada correspondente em caixa. ### CT-004 - depende de cancelamento após recebimento com estorno formal e trilha auditável. ### CT-010 - depende de fluxo líquido correto em presença de entrada, saída e ajuste reverso. ### CT-015 - depende do modelo imutável, da reversão auditável e da reabertura correta do saldo quando aplicável. ## Arquivos que Provavelmente Precisarão Ser Alterados na Implementação da REL-004 ### Primários - `apps/admin/src/app/actions/financial.ts` - `apps/admin/src/app/api/pdv/checkout/route.ts` - `apps/admin/src/app/api/pdv/cancel-sale/route.ts` - nova migration financeira para consolidar a regra oficial de sincronização `payments -> cash_flow -> orders` ### Banco / procedures / triggers - `apps/admin/src/db/migrations/70_make_delete_payment_compatible_with_immutable_cash_flow.sql` - procedure sucessora ou complementar da `delete_payment_with_cleanup()` - possível trigger ou procedure oficial para criação do `cash_flow` do pagamento - possível rotina oficial para sincronização de `orders.paid_amount` e `orders.financial_status` ### Colaterais de risco - `apps/admin/src/db/migrations/63_add_commission_payment_engine.sql` - não é o alvo principal da `REL-004`; - mas deve ser preservado e revalidado, porque reage a insert/delete em `payments`. ## Arquivos que Não Devem Ser Alterados na Implementação da REL-004 - `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/api/accounts-receivable/[id]/receive/route.ts`, salvo extração mínima de infraestrutura compartilhada estritamente indispensável - `apps/admin/src/app/api/accounts-receivable/route.ts`, salvo ajuste absolutamente estrutural e comum às histórias seguintes Justificativa: - a camada analítica da Sprint 1 já foi tratada por `REL-001`, `REL-002` e `REL-003`; - `REL-004` pertence à trilha transacional de pedido/pagamento/caixa; - mexer novamente na camada de relatórios agora misturaria escopos. ## Riscos de Regressão ### 1. Histórico legado sem `cash_flow PEDIDO` rastreável - se existirem pagamentos históricos sem contrapartida oficial em `cash_flow`, qualquer endurecimento da trilha exigirá tratamento de legado. ### 2. Duplicidade entre caixa do PDV e caixa financeiro geral - `pdv_cash_movements` e `cash_flow` coexistem no mesmo processo; - a conciliação pode quebrar se a regra de geração/reversão não for unificada. ### 3. Efeito colateral em comissão - a exclusão de `payments` dispara reversão de comissão; - qualquer mudança de estratégia em pagamentos precisa preservar esse comportamento. ### 4. Divergência de resumo financeiro do pedido - se `orders.paid_amount` continuar sendo atualizado por caminho implícito ou externo, o sistema pode seguir com duas fontes de verdade concorrentes. ### 5. Reversão parcial não auditável - se alguns caminhos continuarem apagando e outros compensando, o histórico financeiro seguirá inconsistente para auditoria. ## Estratégia Recomendada ### Estratégia de implementação futura 1. Formalizar uma única rotina oficial para refletir `payments` em `cash_flow` e no resumo financeiro de `orders`. 2. Definir se o modelo será definitivamente imutável para `cash_flow` antes da implementação. 3. Tornar a reversão compensatória o padrão oficial quando já houver efeito financeiro. 4. Preservar `REL-004` estritamente no universo `orders`, `payments`, `cash_flow`. 5. Deixar a trilha `accounts_receivable`, `receivable_receipts`, `cash_flow` para `REL-005`. 6. Deixar a padronização transversal de estorno/reversão e reabertura formal para `REL-006`. ### Estratégia de validação futura - validar fechamento entre `payments` e `cash_flow` por `reference_id`; - validar fechamento entre soma dos pagamentos e `orders.paid_amount`; - validar cancelamento PDV com reversão líquida correta; - validar que não existam eventos órfãos após exclusão/cancelamento; - reexecutar `CT-002`, `CT-004`, `CT-010` e manter `CT-015` como fechamento conjunto das três histórias da Sprint 2. ## Critério de Aceite da REL-004 A `REL-004` só poderá ser considerada concluída quando: - todo `payments.insert` oficial tiver trilha correspondente em `cash_flow`; - todo `payments.delete` ou cancelamento equivalente tiver tratamento auditável e reproduzível; - `orders.paid_amount` e `orders.financial_status` fecharem com a política oficial do pagamento; - a venda PDV não depender de exclusão silenciosa para manter caixa líquido coerente; - o fluxo não invadir a governança específica de `accounts_receivable` e `receivable_receipts`, reservada a `REL-005`; - os cenários `CT-002`, `CT-004` e `CT-010` fiquem estruturalmente suportados; - o `CT-015` permaneça preparado, mas não artificialmente dado como encerrado antes de `REL-005` e `REL-006`. ## Conclusão Executiva O diagnóstico confirma que: - a trilha entre `orders`, `payments` e `cash_flow` está estruturalmente incompleta ou ao menos implícita demais para auditoria forte; - o repositório mostra consumo e reversão de `cash_flow PEDIDO`, mas não mostra sua criação com a mesma clareza; - a estratégia atual de reversão ainda é híbrida, variando entre apagar e compensar; - a história `REL-004` é real, necessária e coerente com a Sprint 2; - `REL-004` não substitui `REL-005` nem `REL-006`. ## Recomendação Formal - **REL-004 AUTORIZADA** ### Fundamentação 1. O problema é real e está comprovado no código inspecionado. 2. O escopo da história está claramente separável da camada analítica já concluída na Sprint 1. 3. A implementação futura pode ser restrita a `orders`, `payments`, `cash_flow` e respectivas procedures/triggers. 4. O diagnóstico também confirma os limites formais: - não iniciar `REL-005` dentro da `REL-004`; - não iniciar `REL-006` dentro da `REL-004`; - não prometer encerramento de `CT-015` apenas com `REL-004`. ### Ressalva obrigatória - A autorização da `REL-004` deve ser entendida como autorização da história isolada, e não como autorização implícita para fechar toda a rastreabilidade financeira da Sprint 2 em uma única entrega.