# Auditoria Técnica - DIAGNOSTICO_REL_005 ## Objetivo Auditar tecnicamente o conteúdo de `DIAGNOSTICO_REL_005.md` antes de qualquer implementação da `REL-005`, validando: - aderência do escopo à história correta; - separação com `REL-006`; - dependências estruturais de banco; - casos de teste impactados; - arquivos realmente obrigatórios; - arquivos adicionais relevantes; - delimitação entre `accounts_receivable`, `receivable_receipts`, `cash_flow`, `orders` e `payments`. ## Base Utilizada - `ESPECIFICACAO_OFICIAL.md` - `MATRIZ_DE_VERDADE.md` - `BACKLOG_EXECUTIVO.md` - `PLANO_DE_CORRECAO.md` - `PLANO_DE_EXECUCAO.md` - `DIAGNOSTICO_REL_005.md` - `STATUS.md` - `CHANGELOG.md` - `DECISOES.md` - `VALIDACAO_REL_004.md` Também foram revisados os arquivos reais do fluxo: - `apps/admin/src/app/api/accounts-receivable/route.ts` - `apps/admin/src/app/api/accounts-receivable/[id]/receive/route.ts` - `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/app/api/cash-flow/route.ts` - `apps/admin/src/app/dashboard/financial/receivables/page.tsx` ## Veredito Sobre o Diagnóstico O `DIAGNOSTICO_REL_005.md` está **correto no núcleo do problema**, mas **ainda não está suficientemente preciso para autorizar implementação imediata**. Acertos do diagnóstico: - identificou corretamente que a trilha atual cobre só o caso simples de título manual com baixa manual; - identificou corretamente que a baixa ainda depende da API e não de rotina persistida oficial; - identificou corretamente a ausência de trilha formal de estorno/reabertura de recebimentos; - identificou corretamente que a carteira operacional atual está fragmentada entre `orders` e `accounts_receivable`; - mapeou corretamente `CT-005`, `CT-006`, `CT-008`, `CT-009` e a dependência parcial de `CT-015`. Pontos que exigem correção de enquadramento: - o diagnóstico mistura parte do problema de reabertura/estorno mínimo da `REL-005` com a política universal de reversão da `REL-006`; - o diagnóstico subdocumenta dependências já existentes da própria API de títulos, especialmente o `PATCH` de `accounts-receivable`; - o diagnóstico classifica alguns arquivos de forma imprecisa, principalmente a tela operacional de recebíveis e o consumidor de `cash_flow`; - o diagnóstico ainda não fecha a decisão arquitetural sobre como a carteira oficial se relacionará com `orders` e `payments`. ## 1. Escopo Correto da REL-005 Pertence efetivamente à `REL-005`: - criação de títulos em `accounts_receivable`; - edição/cancelamento controlado do título financeiro; - baixa parcial e total por `receivable_receipts`; - múltiplos recebimentos sobre o mesmo título; - recomposição de `paid_amount` e `status` do título; - reflexo do recebimento em `cash_flow`; - reabertura do saldo do título quando um recebimento é revertido; - consistência da carteira oficial por `accounts_receivable`; - conciliação entre `accounts_receivable`, `receivable_receipts` e `cash_flow`. Justificativa: - a especificação e a matriz de verdade definem `accounts_receivable` como fonte oficial da carteira; - `receivable_receipts` é a fonte oficial do recebido; - `cash_flow` é o espelho auditável do evento financeiro de caixa; - o backlog oficial posiciona a `REL-005` exatamente como a trilha `títulos -> recebimentos -> caixa`. ## 2. Escopo Indevido Puxado Para Dentro da REL-005 O diagnóstico puxou, de forma excessiva, alguns pontos que não devem ser tratados como núcleo da `REL-005`: ### 2.1 Política universal de fluxo imutável Não pertence à `REL-005` como história autônoma: - padronização definitiva de estorno auditável para todos os domínios financeiros; - política transversal de exclusão versus compensação; - fechamento completo do modelo imutável da Sprint 2. Esses itens pertencem à `REL-006`. ### 2.2 Vínculo obrigatório pleno com `payments` O diagnóstico trata a ausência de `payment_id` como se a correção obrigatória da `REL-005` dependesse disso. Auditoria: - a ausência de relação explícita com `payments` é um problema real de arquitetura geral; - porém o núcleo da `REL-005` é fechar a trilha do título e do recibo; - obrigar que todo `receivable_receipt` passe a conhecer `payment_id` já empurra a história para um desenho integrado com `REL-004` e `REL-006`. Classificação correta: - registrar a ausência do vínculo: **sim** - tratar isso como dependência arquitetural compartilhada: **sim** - exigir como mudança obrigatória mínima da `REL-005`: **não comprovado** ### 2.3 Reconciliação total com `orders` O diagnóstico acerta ao apontar a carteira híbrida na tela. Mas é importante separar: - corrigir a verdade oficial da carteira e parar de tratar `orders` como pseudo-título: **pertence à REL-005** - definir vínculo estrutural definitivo entre venda comercial e título financeiro em todo o sistema: **ainda depende de decisão arquitetural adicional** ## 3. Dependência Oculta de Banco Não Documentada Foi identificada dependência estrutural não explicitada com precisão suficiente no diagnóstico: ### 3.1 A rota de título já possui mutação de status Arquivo: - `apps/admin/src/app/api/accounts-receivable/route.ts` Constatação: - além de `GET` e `POST`, o arquivo já expõe `PATCH`; - esse `PATCH` permite alterar: - `description` - `total_amount` - `due_date` - `status` - dados do cliente - conta bancária - categoria Impacto: - o ciclo de vida do título não está restrito a “criar” e “receber”; - qualquer implementação da `REL-005` que queira endurecer cancelamento, reabertura e integridade do título precisa considerar esse `PATCH`. Conclusão: - a dependência existe; - o diagnóstico não a explorou com profundidade suficiente. ### 3.2 A trigger atual não protege status cancelado Arquivo: - `68_add_accounts_receivable_manual.sql` Constatação: - `sync_accounts_receivable_status()` recalcula status somente por soma de recibos e vencimento; - o código atual não preserva explicitamente `CANCELED`. Impacto: - se a aplicação permitir cancelamento do título via `PATCH`, a trigger pode reclassificar o status depois; - isso confirma uma dependência oculta entre mutação do título e trigger atual. ### 3.3 O consumidor de `cash_flow` já conhece `RECEBER` Arquivo: - `apps/admin/src/app/api/cash-flow/route.ts` Constatação: - a API de `cash_flow` já reconhece `origin = 'RECEBER'`; - ela busca detalhes em `receivable_receipts` e `accounts_receivable`. Impacto: - qualquer mudança de modelagem de reversão, origem, descrição ou vínculo do recibo impactará essa API leitora; - isso é dependência de banco e de consumo, não só da rota de baixa. ### 3.4 A carteira operacional atual depende de uma composição híbrida Arquivo: - `apps/admin/src/app/dashboard/financial/receivables/page.tsx` Constatação: - a página consulta `orders`; - consulta `/api/accounts-receivable`; - mistura ambos em uma mesma lista de carteira. Impacto: - a inconsistência de carteira não será resolvida apenas no banco; - existe dependência funcional da tela operacional. ## 4. Classificação Correta dos Arquivos ## Arquivos obrigatórios - `apps/admin/src/app/api/accounts-receivable/route.ts` - `apps/admin/src/app/api/accounts-receivable/[id]/receive/route.ts` - `apps/admin/src/db/migrations/68_add_accounts_receivable_manual.sql` - `apps/admin/src/db/migrations/69_update_cash_flow_origin_receber.sql` Justificativa: - concentram criação, edição, cancelamento implícito, baixa, trigger atual e origem `RECEBER`. ## Arquivos prováveis - `apps/admin/src/app/api/cash-flow/route.ts` - `apps/admin/src/app/dashboard/financial/receivables/page.tsx` Justificativa: - o primeiro consome diretamente a trilha `RECEBER`; - o segundo materializa a carteira híbrida que o diagnóstico corretamente apontou como inconsistente. ## Arquivos condicionais - `apps/admin/src/lib/financial-reporting.ts` - `apps/admin/src/lib/reports/service.ts` Justificativa: - consomem ou analisam trilhas financeiras; - não há evidência, nesta auditoria, de que precisem ser alterados como parte mínima da `REL-005`; - só devem ser tocados se a implementação alterar semanticamente como recebimentos/reversões chegam ao consumo analítico. ## Arquivos que não devem ser alterados na REL-005 - `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/db/migrations/71_formalize_payments_cash_flow_pipeline.sql` - `apps/admin/src/db/migrations/72_replace_delete_payment_cleanup_with_auditable_reversal.sql` - camada de relatórios da Sprint 1 (`service.ts`, `report-page-client.tsx`, `report-charts.tsx`, `contracts.ts`) Justificativa: - pertencem ao eixo `orders -> payments -> cash_flow` ou à camada analítica já congelada; - alterá-los reabriria `REL-004` ou Sprint 1 sem necessidade comprovada. ## 5. Migrations, Triggers e Procedures ## Migrations obrigatórias Auditoria confirma: - serão necessárias migrations novas para endurecer a trilha `receivable_receipts -> cash_flow`; - serão necessárias migrations novas para reversão/reabertura mínima do título; - será necessário revisar a estrutura de `accounts_receivable` e `receivable_receipts`. ## Trigger obrigatória Auditoria confirma: - a trigger atual é insuficiente; - uma trigger ou routine oficial de ressincronização do título continuará sendo necessária. ## Procedures obrigatórias Auditoria confirma: - a `REL-005` precisa de routine oficial para registrar baixa; - precisa de routine oficial para reversão mínima do recibo; - precisa de routine oficial para reabertura do saldo do título. ## Invasão indevida de REL-006 O ponto crítico da auditoria é este: - uma **reversão mínima do recibo**, necessária para reabrir o saldo do título e corrigir `cash_flow` daquele recebimento, pertence à `REL-005`; - a **política universal e definitiva de estorno auditável**, padronizada para todos os domínios, pertence à `REL-006`. Portanto: - o diagnóstico acertou ao exigir reversão para o domínio de recebíveis; - errou ao não separar com suficiente nitidez o que é reversão mínima de título/recibo daquilo que já é política universal da Sprint 2. ## 6. Delimitação Correta Entre os Universos ## accounts_receivable Papel correto: - fonte oficial da carteira em aberto; - título financeiro de competência. ## receivable_receipts Papel correto: - evento de liquidação do título; - base oficial do valor recebido. ## cash_flow Papel correto: - livro caixa oficial; - espelho auditável do recebimento, quando houver baixa em caixa. ## orders Papel correto: - obrigação comercial; - não é título financeiro oficial. ## payments Papel correto: - evento operacional/comercial do pagamento do pedido; - não substitui, por si só, a trilha oficial do título e do recibo. ## Delimitação final - `orders` e `payments` devem ser tratados como dependência de contexto e reconciliação; - o núcleo da `REL-005` continua sendo `accounts_receivable`, `receivable_receipts` e `cash_flow`. ## 7. Validação dos Cenários Auditados ## Criação de títulos Veredito: - corretamente classificada dentro da `REL-005` Observação: - o diagnóstico subestimou que o mesmo arquivo também controla mutações posteriores do título via `PATCH`. ## Baixa parcial Veredito: - corretamente classificada dentro da `REL-005` Observação: - o diagnóstico está correto ao apontar que o caso simples funciona, mas sem trilha reversa. ## Baixa total Veredito: - corretamente classificada dentro da `REL-005` Observação: - o diagnóstico abordou o efeito por soma, embora tenha focado mais nos parciais e múltiplos. ## Recebimentos múltiplos Veredito: - corretamente classificados dentro da `REL-005` Observação: - a trigger atual suporta a soma; - o problema está na ausência de política de reversão e auditoria. ## Reabertura de títulos Veredito: - pertence à `REL-005` no recorte mínimo do domínio de recebíveis Observação: - o diagnóstico acerta ao tratar isso como lacuna real; - precisa apenas separar melhor a reabertura mínima da política universal da `REL-006`. ## Vínculo com pedidos Veredito: - deve permanecer como dependência arquitetural e de consistência; - não está comprovado que todo o vínculo estrutural completo precise ser implementado já na `REL-005`. ## Vínculo com pagamentos Veredito: - deve permanecer como dependência de reconciliação e arquitetura compartilhada; - não está comprovado como mudança mínima obrigatória da `REL-005`. ## Sincronização com cash_flow Veredito: - corretamente classificada como parte central da `REL-005` Observação: - o diagnóstico está correto em apontar que a sincronização atual é frágil. ## Consistência da carteira Veredito: - corretamente classificada como parte da `REL-005` Observação: - a tela híbrida confirma que a consistência da carteira ainda não está formalmente resolvida. ## 8. Casos de Teste ## CT-005 - classificação do diagnóstico: **correta** - motivo: parcial do título, saldo aberto e recebido ## CT-006 - classificação do diagnóstico: **correta** - motivo: múltiplos recebimentos em datas distintas ## CT-008 - classificação do diagnóstico: **correta** - motivo: título vencido parcialmente pago ## CT-009 - classificação do diagnóstico: **correta** - motivo: título futuro em aberto sem contaminar atraso ## CT-015 - classificação do diagnóstico: **parcialmente correta** - motivo: - a parte de reabertura do saldo do título pertence à `REL-005` - o fechamento transversal do fluxo imutável continua pertencendo à `REL-006` ## 9. Riscos de Regressão ### 1. Reclassificação da carteira operacional - ao retirar a mistura entre `orders` e `accounts_receivable`, a tela de recebíveis pode mudar substancialmente. ### 2. Dados históricos com `origin = 'MANUAL'` - o fallback atual `[RECEBER]` pode exigir saneamento ou compatibilidade retroativa. ### 3. Reclassificação indevida de títulos cancelados - a trigger atual pode sobrescrever estados sensíveis se não for redesenhada. ### 4. Duplicidade conceitual com a REL-004 - sem decisão arquitetural explícita, `payments` e `receivable_receipts` podem continuar parecendo duas portas de liquidação concorrentes. ### 5. Invasão de escopo na REL-006 - se a implementação tentar fechar a política universal de reversão já na `REL-005`, a Sprint 2 perde separação funcional. ## 10. Estratégia Recomendada 1. Refinar oficialmente o escopo da `REL-005` para o domínio do título e do recibo. 2. Incluir explicitamente `accounts-receivable/route.ts` como superfície completa do ciclo de vida do título, não só criação. 3. Tratar `cash-flow/route.ts` e `financial/receivables/page.tsx` como arquivos prováveis, não automaticamente obrigatórios. 4. Separar formalmente: - reversão mínima do recibo para reabrir o título: `REL-005` - política universal de estorno auditável e fluxo imutável: `REL-006` 5. Exigir decisão arquitetural prévia sobre o vínculo entre carteira oficial e origem comercial antes de autorizar implementação. ## Conclusão Final O `DIAGNOSTICO_REL_005.md`: - está correto ao identificar que a trilha `accounts_receivable -> receivable_receipts -> cash_flow` está incompleta; - está correto ao classificar a história como crítica; - está correto ao apontar necessidade de banco, migrations, triggers e procedures; - mas ainda não separa com precisão suficiente a `REL-005` da `REL-006`; - e ainda não documenta todas as superfícies obrigatórias e dependências ocultas do fluxo atual. ## Classificação Final - **REL-005 NÃO AUTORIZADA** ## Justificativa Técnica Detalhada 1. O diagnóstico acerta o problema, mas não fecha a delimitação arquitetural mínima da história. 2. Ainda há sobreposição entre “reversão mínima do recibo” e “política universal de estorno”. 3. A dependência do `PATCH` de `accounts-receivable/route.ts` não foi tratada com a importância necessária. 4. A classificação de arquivos precisa ser refinada antes de implementação controlada. 5. O vínculo entre carteira oficial e origem comercial ainda depende de decisão arquitetural adicional. ### Condição para futura autorização A `REL-005` poderá ser autorizada após: - revisão do diagnóstico com separação formal entre `REL-005` e `REL-006`; - classificação final dos arquivos impactados; - definição arquitetural explícita sobre o vínculo entre título financeiro e origem comercial; - autorização explícita para pacote estrutural de banco, migrations, triggers e procedures.