# Diagnóstico Técnico - REL-005 ## Objetivo Mapear completamente a trilha: - `accounts_receivable` - `receivable_receipts` - `cash_flow` Com foco em: - criação de títulos; - baixa de títulos; - recebimentos parciais; - recebimentos múltiplos; - reabertura de títulos; - sincronização com `cash_flow`; - sincronização com `orders`; - sincronização com `payments`; - inconsistências atuais. ## Base Documental Utilizada - `ESPECIFICACAO_OFICIAL.md` - `MATRIZ_DE_VERDADE.md` - `BACKLOG_EXECUTIVO.md` - `PLANO_DE_CORRECAO.md` - `PLANO_DE_EXECUCAO.md` - `STATUS.md` - `CHANGELOG.md` - `DECISOES.md` - `VALIDACAO_REL_004.md` ## Síntese Executiva A `REL-005` é necessária e o problema é real. Hoje existe uma trilha funcional mínima para títulos manuais: - criação manual de título em `accounts_receivable`; - baixa manual por `receivable_receipts`; - reflexo de entrada em `cash_flow` com `origin = 'RECEBER'`; - trigger `sync_accounts_receivable_status()` para recomputar `paid_amount` e `status`. Porém a implementação atual está incompleta para uma trilha financeira oficial e auditável: - os títulos manuais não possuem vínculo estrutural com `orders`; - os recibos não possuem vínculo estrutural com `payments`; - a tela de recebíveis mistura `orders` e `accounts_receivable` como se fossem a mesma carteira; - não existe fluxo oficial de estorno/reversão de `receivable_receipts`; - não existe fluxo oficial de reabertura de saldo do título; - o reflexo em `cash_flow` depende da rota de API, e não de rotina persistida no banco; - a trigger do título recalcula status, mas não resolve rastreabilidade nem reversão. Conclusão: - a `REL-005` não está implementada; - o recorte da história está corretamente localizado na Sprint 2; - a necessidade de banco, migrations, triggers e procedures é alta; - a história é crítica para `CT-005`, `CT-006`, `CT-008`, `CT-009` e para a parte de carteira de `CT-015`. ## Regra Correta Segundo a Especificação e a Matriz de Verdade ### Contas a Receber Fonte oficial: - `accounts_receivable` Regra correta: - `paid_amount` do título deve ser igual à soma de `receivable_receipts.amount`; - saldo aberto deve ser `max(0, total_amount - paid_amount)`; - títulos `PAID` e `CANCELED` não entram na carteira; - títulos vencidos com saldo aberto entram no atraso; - se houver estorno de recebimento, o saldo do título deve reabrir. ### Valor Recebido Fonte oficial: - `receivable_receipts` Regra correta: - cada baixa financeira válida entra por sua data `received_at`; - recebimentos parciais e múltiplos são eventos normais; - múltiplas formas de pagamento devem ser registradas por evento de liquidação; - cancelamento comercial não elimina recebimento passado sem estorno formal. ### Fluxo de Caixa Fonte oficial: - `cash_flow` Regra correta: - cada `receivable_receipt` válido deve gerar evento correspondente em `cash_flow`, quando a política financeira exigir baixa em caixa; - estorno nunca deve ser simples desaparecimento histórico; - reversão deve existir como evento rastreável. ## Fluxo Atual Mapeado ## 1. Criação de títulos ### Implementação atual Arquivo: - `apps/admin/src/app/api/accounts-receivable/route.ts` Comportamento: - `POST /api/accounts-receivable` cria título manual em `accounts_receivable`; - o título recebe: - `company_id` - `description` - `client_name` - `client_company` - `total_amount` - `due_date` - `bank_account_id` - `category_id` - `notes` - `status = 'PENDING'` - não existe vínculo com: - `orders` - `payments` - origem comercial certificada ### Diagnóstico Este fluxo cobre apenas: - títulos manuais. Não cobre: - títulos originados de pedido; - trilha oficial de competência derivada da venda; - reconciliação entre carteira manual e carteira comercial. ## 2. Baixa de títulos ### Implementação atual Arquivo: - `apps/admin/src/app/api/accounts-receivable/[id]/receive/route.ts` Comportamento: - busca o título por `id` e `company_id`; - bloqueia baixa se o título já estiver `PAID`; - calcula `remaining = total_amount - paid_amount`; - impede baixa acima do saldo; - insere `receivable_receipts`; - em seguida insere `cash_flow` manualmente na própria rota com: - `type = 'IN'` - `origin = 'RECEBER'` - `reference_id = receipt.id` - se o banco antigo não aceitar `origin = 'RECEBER'`, cai em fallback: - `origin = 'MANUAL'` - `description = '[RECEBER] ...'` - se a inserção em `cash_flow` falhar, apaga o recibo recém-criado; - o retorno final relê o título já recalculado. ### Diagnóstico A baixa existe, mas com fragilidades claras: - o reflexo em `cash_flow` está na rota e não em function/trigger oficial; - há fallback semântico para `MANUAL`, o que enfraquece a origem financeira oficial; - a atomicidade é parcial: a rota compensa falha apagando o recibo, mas não existe rotina formal de transação financeira auditável; - não há trilha de estorno do recebimento. ## 3. Recebimentos parciais ### Implementação atual Base: - `accounts_receivable.total_amount` - `accounts_receivable.paid_amount` - `receivable_receipts.amount` Mecanismo: - a rota de baixa permite valor menor que o saldo; - a trigger `sync_accounts_receivable_status()` soma todos os recibos do título; - se a soma for parcial, o status vira `PARTIALLY_PAID`. ### Diagnóstico O parcial funciona conceitualmente para o caso simples: - um título; - múltiplos recibos; - soma controlada. Mas ainda falta: - estorno parcial; - reabertura parcial com trilha reversa; - vínculo auditável entre baixa original e reversão. ## 4. Recebimentos múltiplos ### Implementação atual A trigger em `68_add_accounts_receivable_manual.sql` faz: - `SUM(receivable_receipts.amount)` por `receivable_id`; - atualiza `accounts_receivable.paid_amount`; - atualiza `accounts_receivable.status`. ### Diagnóstico O modelo suporta múltiplas baixas no mesmo título. Isso cobre o núcleo do `CT-006` no cenário positivo, mas não cobre o ciclo completo porque: - não existe política oficial de reversão de um ou mais recibos; - não existe proteção formal contra exclusão histórica indevida do recibo; - a origem do caixa depende da API e não do banco. ## 5. Reabertura de títulos ### Implementação atual Não foi encontrado no repositório: - endpoint dedicado de estorno de `receivable_receipts`; - endpoint de reabertura de `accounts_receivable`; - function ou procedure dedicada para reversão de baixa; - trigger de reversão financeira equivalente à política aplicada na `REL-004`. Superfície real encontrada para recebíveis: - `apps/admin/src/app/api/accounts-receivable/route.ts` - `apps/admin/src/app/api/accounts-receivable/[id]/receive/route.ts` ### Diagnóstico Hoje não existe fluxo oficial de reabertura. Isso significa que o sistema: - consegue baixar; - consegue somar recibos; - não consegue reverter a baixa de forma auditável. Este é um bloqueio estrutural para: - `CT-015`; - rastreabilidade de estorno; - coerência entre carteira e caixa após reversão. ## 6. Sincronização com cash_flow ### Implementação atual Base: - `69_update_cash_flow_origin_receber.sql` - `POST /api/accounts-receivable/[id]/receive` - `GET /api/cash-flow` Comportamento: - a migration `69` permite `origin = 'RECEBER'` em `cash_flow`; - a rota de recebimento cria a entrada em caixa usando `reference_id = receipt.id`; - `GET /api/cash-flow` reconhece `origin = 'RECEBER'` e enriquece a leitura com: - `payment_method` - categoria do título ### Diagnóstico A sincronização existe, mas ainda é frágil: - depende da API e não de procedure/trigger; - pode cair em fallback `MANUAL` para compatibilidade; - não existe evento reverso oficial do recebimento; - não existe vínculo explícito entre movimento original e estorno futuro. ## 7. Sincronização com orders ### Implementação atual Na camada operacional: - não existe `order_id` em `accounts_receivable`; - não existe `order_id` em `receivable_receipts`; - não existe routine que reconcilie título com pedido. Na UI de recebíveis: - `apps/admin/src/app/dashboard/financial/receivables/page.tsx` busca: - `orders` como carteira de pedidos; - `accounts_receivable` como carteira manual; - depois mistura ambos na mesma lista. ### Diagnóstico Hoje existe uma carteira híbrida: - pedidos entram como pseudo-recebíveis por `orders.paid_amount` e `orders.financial_status`; - títulos manuais entram por `accounts_receivable`. Isso é incompatível com a regra oficial da `REL-005`, porque: - `accounts_receivable` deveria ser a fonte oficial da carteira; - `orders` é obrigação comercial, não título financeiro oficial; - a mistura esconde a ausência de vínculo formal entre venda e título. ## 8. Sincronização com payments ### Implementação atual Não foi encontrado: - `payment_id` em `accounts_receivable`; - `payment_id` em `receivable_receipts`; - routine ligando recibo de título ao evento operacional em `payments`. ### Diagnóstico Hoje os dois trilhos coexistem sem reconciliação oficial: - `REL-004`: `orders -> payments -> cash_flow` - `REL-005`: `accounts_receivable -> receivable_receipts -> cash_flow` Sem vínculo estrutural entre eles, o sistema fica sujeito a: - duplicidade conceitual de liquidação; - dificuldade de explicar se o caixa veio de `payments` ou de `receivable_receipts`; - impossibilidade de fechar totalmente `CT-015`. ## Estrutura de Banco Atual ## accounts_receivable Origem: - `68_add_accounts_receivable_manual.sql` Campos relevantes: - `id` - `company_id` - `description` - `client_name` - `client_company` - `total_amount` - `paid_amount` - `due_date` - `status` - `bank_account_id` - `category_id` - `notes` Limitações estruturais: - não possui `order_id`; - não possui `source_type`; - não possui `source_id`; - não possui campos de reversão/reabertura; - não distingue título manual de título originado por venda formal. ## receivable_receipts Origem: - `68_add_accounts_receivable_manual.sql` Campos relevantes: - `id` - `company_id` - `receivable_id` - `amount` - `received_at` - `payment_method` - `bank_account_id` - `notes` Limitações estruturais: - não possui `payment_id`; - não possui `order_id`; - não possui `reversed_at`; - não possui `reversed_by`; - não possui `reversal_reason`; - não possui `reversed_receipt_id` ou vínculo equivalente; - não possui status próprio de reversão. ## Trigger atual ### `sync_accounts_receivable_status()` Função atual: - soma recibos do título; - atualiza `paid_amount`; - atualiza `status`. Mérito: - resolve o fechamento básico do saldo aberto. Limitações: - usa `current_date` para classificar `OVERDUE`, e não uma política analítica de data de corte; - não protege `CANCELED` de ser reclassificado automaticamente; - não trata reversão auditável; - não sincroniza `cash_flow`; - não sincroniza `orders` nem `payments`. ## Inconsistências Atuais ### 1. Verdade de carteira fragmentada - a UI de recebíveis usa `orders` como carteira operacional e `accounts_receivable` como carteira manual; - isso quebra a ideia de fonte única oficial para competência. ### 2. Baixa depende da API, não do banco - `receivable_receipts` e `cash_flow` são sincronizados na rota; - ausência de function/trigger deixa a trilha mais frágil. ### 3. Fallback semântico para `MANUAL` - quando `RECEBER` não é aceito, a baixa vira `MANUAL` com prefixo textual; - isso enfraquece a rastreabilidade por origem. ### 4. Ausência de estorno/reabertura - não existe fluxo oficial de reversão de recibo; - não existe mecanismo formal de reabrir saldo do título. ### 5. Ausência de vínculo com venda/pagamento - `accounts_receivable` e `receivable_receipts` não conhecem `orders` nem `payments`; - a conciliação entre caixa de pedido e caixa de recebimento permanece implícita. ### 6. Trigger limitada ao status do título - a trigger recalcula saldo e status; - não fecha a trilha transacional ponta a ponta. ### 7. Cancelamento do título ainda não está endurecido - não foi encontrada rota dedicada de cancelamento de título; - também não foi encontrada proteção específica contra baixa posterior em fluxo cancelado além do status atual carregado. ## Arquivos Obrigatórios para a REL-005 - `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/dashboard/financial/receivables/page.tsx` Justificativa: - concentram criação de título, baixa, trigger atual, origem `RECEBER` e a carteira híbrida exibida ao usuário. ## Arquivos Prováveis - `apps/admin/src/app/api/cash-flow/route.ts` - `apps/admin/src/lib/financial-reporting.ts` - `apps/admin/src/lib/reports/service.ts` Justificativa: - consomem a trilha `RECEBER` e provavelmente precisarão acompanhar qualquer endurecimento da origem, estorno ou vínculo categórico. ## Migrations Necessárias ### Obrigatórias - migration para formalizar a trilha `receivable_receipts -> cash_flow` - migration para formalizar estorno/reversão auditável de recibos - migration para endurecer a modelagem de origem do título e do recibo ### Fortemente recomendadas - adicionar vínculo de origem do título: - `source_type` - `source_id` - e/ou `order_id`, se a arquitetura escolhida for essa - adicionar trilha de reversão em `receivable_receipts`: - `reversed_at` - `reversed_by` - `reversal_reason` - `reversed_receipt_id` ou equivalente ## Triggers Necessárias ### Obrigatórias - trigger persistida para criar/reforçar `cash_flow` a partir de `receivable_receipts` - trigger ou routine persistida para ressincronizar `accounts_receivable` após insert/delete/reversal de recibos ### Prováveis - trigger de guarda para impedir múltiplos lançamentos indevidos em `cash_flow` para o mesmo recibo - trigger para proteger títulos `CANCELED` de recomputação indevida ## Procedures Necessárias ### Obrigatórias - procedure oficial para registrar baixa auditável do título - procedure oficial para estornar recebimento - procedure oficial para reabrir saldo do título com reflexo em `cash_flow` ### Prováveis - helper de reconciliação entre título e origem comercial quando a modelagem da Ktalogu decidir como ligar a carteira a `orders` ## Riscos de Regressão ### 1. Regressão de carteira atual - a UI atual depende de mistura entre pedidos e títulos manuais; - ao separar a fonte oficial, a página pode mudar números e comportamento. ### 2. Regressão no fluxo de caixa - qualquer mudança em `RECEBER` pode afetar `cash_flow` e seus relatórios consumidores. ### 3. Regressão em relatórios financeiros - `REL-003` fechou a camada analítica com a base atual; - qualquer mudança na trilha transacional exigirá nova reconciliação funcional, sem necessariamente reabrir a história. ### 4. Risco de legado - podem existir recibos históricos lançados como `MANUAL` com prefixo `[RECEBER]`; - normalização futura pode exigir migração de saneamento. ### 5. Risco de dupla verdade com REL-004 - sem arquitetura clara entre `payments` e `receivable_receipts`, o caixa pode continuar com duas portas de entrada sem reconciliação oficial. ## Impacto nos Casos de Teste ## CT-005 - impactado diretamente - motivo: exige recebimento parcial e saldo correto do título ## CT-006 - impactado diretamente - motivo: exige recebimentos múltiplos em datas diferentes e distribuição temporal correta ## CT-008 - impactado diretamente - motivo: exige título vencido parcialmente pago com atraso igual ao saldo aberto ## CT-009 - impactado diretamente - motivo: exige título futuro em aberto sem contaminar atraso ## CT-015 - impactado parcialmente - motivo: a parte de reabertura do saldo do título e reversão do recebimento depende da `REL-005`, mas o fechamento total continua dependente também da `REL-006` ## Delimitação com REL-004 e REL-006 ### REL-004 Pertence à `REL-004`: - `orders` - `payments` - `cash_flow` por pagamento do pedido ### REL-005 Pertence à `REL-005`: - `accounts_receivable` - `receivable_receipts` - `cash_flow` por baixa de título - reabertura do saldo do título - sincronização da carteira ### REL-006 Pertence à `REL-006`: - padronização universal de estorno e reversão - política definitiva de fluxo imutável - fechamento transversal do `CT-015` ## Estratégia Recomendada 1. Formalizar `accounts_receivable` como fonte oficial da carteira, eliminando a dependência de carteira híbrida baseada em `orders` na camada operacional. 2. Levar a geração do `cash_flow` de recebimento para routine persistida no banco. 3. Criar estorno/reversão auditável de `receivable_receipts`. 4. Criar reabertura formal do saldo do título. 5. Definir explicitamente a arquitetura de vínculo entre título e origem comercial, sem misturar a execução da `REL-005` com a `REL-006`. ## Conclusão - a `REL-005` é necessária; - a trilha atual cobre apenas o caso simples de título manual + baixa simples; - não há trilha oficial de reabertura ou estorno; - não há vínculo estrutural com `orders` e `payments`; - a verdade de carteira está fragmentada entre `orders` e `accounts_receivable`; - a história exige alterações de banco, migrations, triggers e procedures. ## Recomendação Formal - **REL-005 AUTORIZÁVEL SOMENTE COM PACOTE ESTRUTURAL DE BANCO** ### Condição A implementação da `REL-005` só deve ser autorizada quando incluir explicitamente: - alterações em banco; - migrations; - triggers; - procedures; - revisão controlada da página/rotas de recebíveis no recorte da história.