# Decisão Arquitetural - REL-005 ## Objetivo Produzir a decisão arquitetural definitiva da `REL-005`, definindo: - o que pertence obrigatoriamente à `REL-005`; - o que pertence obrigatoriamente à `REL-006`; - qual é o menor conjunto de alterações capaz de aprovar: - `CT-005` - `CT-006` - `CT-008` - `CT-009` - quais migrations, triggers, procedures e rotas são obrigatórias; - quais arquivos não devem ser alterados; - como tratar: - baixa parcial - baixa total - recebimentos múltiplos - reabertura mínima de título - o que continua pendente para `CT-015` e deve permanecer em `REL-006`. ## Base de Decisão Documentos considerados: - `DIAGNOSTICO_REL_005.md` - `AUDITORIA_DIAGNOSTICO_REL_005.md` - `ESPECIFICACAO_OFICIAL.md` - `MATRIZ_DE_VERDADE.md` - `BACKLOG_EXECUTIVO.md` - `PLANO_DE_CORRECAO.md` - `PLANO_DE_EXECUCAO.md` - `STATUS.md` - `CHANGELOG.md` - `DECISOES.md` Também foram considerados os arquivos reais do fluxo atual: - `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` ## Síntese Executiva A `REL-005` já tem delimitação arquitetural suficiente para execução controlada. O menor pacote viável da história é: - formalizar o ciclo oficial do título em `accounts_receivable`; - formalizar a baixa em `receivable_receipts`; - formalizar o reflexo em `cash_flow`; - formalizar uma reabertura **mínima** do título no domínio de recebíveis; - impedir que `status` do título continue dependendo de mutação arbitrária ou trigger insuficiente. Esse pacote é suficiente para aprovar: - `CT-005` - `CT-006` - `CT-008` - `CT-009` Sem invadir: - política universal de fluxo imutável; - política transversal de estorno auditável de todos os domínios; - fechamento completo do `CT-015`. ## 1. O Que Pertence Obrigatoriamente à REL-005 Pertence obrigatoriamente à `REL-005`: - criação e manutenção controlada de títulos em `accounts_receivable`; - proteção do ciclo de vida do título financeiro; - baixa de título por `receivable_receipts`; - baixa parcial e total; - recebimentos múltiplos sobre o mesmo título; - recomputação oficial de `paid_amount` e `status`; - sincronização oficial de `receivable_receipts` com `cash_flow`; - reabertura **mínima** de saldo do título quando um recebimento do próprio domínio for revertido; - retirada da carteira híbrida como verdade operacional quando ela usa `orders` como pseudo-título; - garantia de que `accounts_receivable` seja a fonte oficial da carteira; - garantia de que `receivable_receipts` seja a fonte oficial do recebido; - garantia de que `cash_flow` seja o espelho financeiro do recebimento. ## 2. O Que Pertence Obrigatoriamente à REL-006 Pertence obrigatoriamente à `REL-006`: - política universal de estorno auditável para todos os domínios financeiros; - padronização global entre exclusão, reversão e compensação; - fechamento do modelo de fluxo imutável para `payments`, `receivable_receipts` e demais eventos; - padronização formal do vínculo entre evento original e evento reverso em todo o sistema; - fechamento transversal do `CT-015`; - regra única definitiva para reversões em `payments`, `receivable_receipts`, `cash_flow` e `accounts_receivable`. ## Separação formal entre REL-005 e REL-006 ### REL-005 Permite: - reverter minimamente um recibo para reabrir o saldo do próprio título; - ajustar `cash_flow` correspondente ao próprio recebimento; - manter coerência do domínio `accounts_receivable -> receivable_receipts -> cash_flow`. ### REL-006 Continua responsável por: - decidir a política universal de imutabilidade; - padronizar se todos os domínios usam compensação, soft-delete ou outro modelo definitivo; - consolidar a política de reversão cross-domain; - fechar `CT-015`. ## 3. Menor Conjunto de Alterações Para Aprovar CT-005, CT-006, CT-008 e CT-009 ## Pacote mínimo obrigatório ### 1. Formalizar a baixa do título no banco Necessário: - tirar da rota a responsabilidade principal de sincronizar título e caixa; - concentrar a baixa em routine persistida atômica. Objetivo: - garantir que toda baixa válida crie o recibo e o reflexo financeiro correspondente; - impedir inconsistência parcial entre `receivable_receipts` e `cash_flow`. ### 2. Reescrever a sincronização do título Necessário: - substituir a trigger atual por rotina que: - recalcule `paid_amount`; - recalcule o saldo aberto; - preserve `CANCELED`; - trate corretamente `PENDING`, `PARTIALLY_PAID`, `PAID`, `OVERDUE`. Objetivo: - fechar corretamente: - `CT-005` - `CT-008` - `CT-009` ### 3. Formalizar a trilha `receivable_receipts -> cash_flow` Necessário: - criar function/trigger oficial para refletir cada recibo em `cash_flow`; - impedir duplicidade por `receipt_id`; - remover dependência do fallback semântico `MANUAL`. Objetivo: - fechar corretamente: - `CT-005` - `CT-006` ### 4. Formalizar recebimentos múltiplos Necessário: - permitir múltiplos recibos válidos no mesmo título; - garantir soma consistente dos recibos; - preservar a granularidade por data e forma de pagamento. Objetivo: - fechar corretamente: - `CT-006` ### 5. Formalizar reabertura mínima do título Necessário: - criar uma reversão mínima do recibo no domínio da `REL-005`; - reabrir saldo do título quando o próprio recebimento for revertido; - refletir essa reversão em `cash_flow`. Objetivo: - preparar o domínio de recebíveis sem tentar fechar ainda a política universal da `REL-006`. ## O que não é necessário para aprovar CT-005, CT-006, CT-008 e CT-009 Não é necessário no pacote mínimo: - vincular obrigatoriamente todo título a `order_id`; - vincular obrigatoriamente todo recibo a `payment_id`; - alterar `REL-004`; - alterar a camada analítica da Sprint 1; - fechar `CT-015`. ## 4. Migrations Obrigatórias ## Migration 1 - Obrigatória ### Nome sugerido - `73_formalize_receivable_receipts_cash_flow_pipeline.sql` ### Conteúdo mínimo - criar function `create_cash_flow_from_receipt(p_receipt_id uuid)`; - criar function `sync_receivable_summary(p_receivable_id uuid)`; - criar function trigger `handle_receipt_after_insert()`; - criar trigger `AFTER INSERT ON public.receivable_receipts`; - criar índice ou proteção de idempotência para `cash_flow` de recibo; - remover dependência operacional do fallback `MANUAL`. ### Objetivo - formalizar a trilha `receivable_receipts -> cash_flow`; - recomputar o título após cada baixa. ## Migration 2 - Obrigatória ### Nome sugerido - `74_harden_accounts_receivable_lifecycle.sql` ### Conteúdo mínimo - endurecer a modelagem de `accounts_receivable`; - impedir que `CANCELED` seja reclassificado automaticamente pela rotina de saldo; - permitir governança do ciclo de vida do título; - revisar a trigger atual `sync_accounts_receivable_status()`. ### Objetivo - garantir coerência de status e saldo do título. ## Migration 3 - Obrigatória ### Nome sugerido - `75_add_minimal_receipt_reversal_support.sql` ### Conteúdo mínimo - adicionar trilha mínima de reversão em `receivable_receipts`; - registrar metadados de reversão do recibo; - permitir reabertura mínima do saldo do título; - refletir a reversão financeira correspondente em `cash_flow`. ### Objetivo - implementar a reabertura mínima do domínio de recebíveis sem fechar ainda a política universal da `REL-006`. ## Campos mínimos recomendados na modelagem ### Em `receivable_receipts` - `reversed_at` - `reversed_by` - `reversal_reason` - `reversed_receipt_id` ou equivalente semântico ### Em `accounts_receivable` Obrigatório mínimo: - revisão da governança de `status` Condicional: - `source_type` - `source_id` - `order_id` Decisão: - esses vínculos de origem são desejáveis; - não são parte comprovadamente obrigatória do menor pacote para `CT-005`, `CT-006`, `CT-008` e `CT-009`. ## 5. Triggers Obrigatórias ## Obrigatórias - `AFTER INSERT ON public.receivable_receipts` - cria o `cash_flow` do recebimento - sincroniza o título - trigger/routine de ressincronização do título - recalcula `paid_amount` - recalcula `status` - protege `CANCELED` ## Prováveis - trigger de guarda para impedir múltiplos `cash_flow` do mesmo recibo ## Condicionais - trigger `AFTER UPDATE ON public.receivable_receipts` - só será necessária se a reversão mínima for implementada por marcação de status/metadata no próprio recibo ## Não obrigatórias na REL-005 - triggers em `payments` - triggers em `orders` - triggers universais de reversão cross-domain ## 6. Procedures Obrigatórias ## Obrigatórias - `register_receipt_with_cash_flow(...)` - cria o recibo - cria o reflexo em `cash_flow` - sincroniza o título - `sync_receivable_summary(p_receivable_id uuid)` - recalcula `paid_amount` - recalcula `status` - preserva a semântica correta do ciclo de vida do título - `reverse_receipt_with_cash_flow(p_receipt_id uuid, p_reason text)` - reverte minimamente o recebimento - reabre saldo do título - cria a reversão correspondente em `cash_flow` ## Prováveis - helper para cancelamento controlado de título - útil se a Ktalogu decidir remover o `PATCH` livre de `status` ## Não obrigatórias na REL-005 - procedures de `payments` - procedures de `orders` - procedures universais de reversão de todos os módulos ## 7. Rotas Que Precisarão Ser Alteradas ## Obrigatórias - `apps/admin/src/app/api/accounts-receivable/route.ts` - deixar de permitir mutação inconsistente do ciclo de vida do título - endurecer criação/edição/cancelamento controlado - `apps/admin/src/app/api/accounts-receivable/[id]/receive/route.ts` - deixar de ser o lugar principal da sincronização entre recibo, título e `cash_flow` - passar a consumir a routine persistida oficial ## Prováveis - `apps/admin/src/app/api/cash-flow/route.ts` - acompanhar eventuais mudanças de leitura da reversão mínima e do enriquecimento de `RECEBER` ## Condicionais - rota dedicada de reversão de recibo - somente se a equipe decidir não concentrar a reabertura mínima em `accounts-receivable/route.ts` ## Rotas que não precisam ser alteradas para o pacote mínimo - `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` ## 8. Arquivos Que NÃO DEVEM Ser Alterados - `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` - `apps/admin/src/lib/reports/service.ts` - `apps/admin/src/components/reports/report-page-client.tsx` - `apps/admin/src/components/reports/report-charts.tsx` - `apps/admin/src/lib/reports/contracts.ts` - toda a camada de relatórios da Sprint 1 Justificativa: - pertencem à `REL-004` ou à camada analítica já congelada; - alterá-los reabriria escopo fora do recorte mínimo da `REL-005`. ## 9. Tratamento Funcional Obrigatório ## Baixa parcial Regra: - permitir recibo com valor menor que o saldo; - somar o recibo ao `paid_amount`; - manter `status = PARTIALLY_PAID` se ainda houver saldo; - refletir somente o valor efetivamente recebido em `cash_flow`. ## Baixa total Regra: - permitir recibo final que zere o saldo; - limitar `paid_amount` ao `total_amount`; - marcar `status = PAID`; - refletir o valor integral do recibo em `cash_flow`. ## Recebimentos múltiplos Regra: - tratar cada recibo como evento individual; - manter granularidade por: - `received_at` - `payment_method` - `bank_account_id` - recalcular o título pela soma de recibos válidos. ## Reabertura mínima de título Regra: - permitir reversão mínima de um recibo do próprio domínio; - reduzir o `paid_amount` do título; - reabrir o saldo correspondente; - reclassificar o título para: - `PARTIALLY_PAID` - `PENDING` - `OVERDUE` conforme saldo e vencimento; - registrar a saída reversa correspondente em `cash_flow`. ## Limite formal da reabertura mínima Essa reabertura: - pertence à `REL-005` somente no domínio do título e do recibo; - não equivale ainda à política universal definitiva de estorno auditável da `REL-006`. ## 10. O Que Continua Pendente Para CT-015 e Deve Permanecer em REL-006 Continua pendente para `CT-015`: - padronização global do fluxo imutável; - modelo único e definitivo de vínculo entre evento original e evento reverso; - política universal entre `payments`, `receivable_receipts` e demais eventos financeiros; - consolidação do caixa líquido cross-domain; - harmonização final entre `REL-004` e `REL-005` no comportamento universal de reversão. Conclusão: - a `REL-005` prepara o lado do título e do recebimento; - a `REL-006` fecha o comportamento universal de estorno e a aprovação integral do `CT-015`. ## 11. Classificação dos 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` ## Prováveis - `apps/admin/src/app/api/cash-flow/route.ts` - `apps/admin/src/app/dashboard/financial/receivables/page.tsx` ## Condicionais - `apps/admin/src/lib/financial-reporting.ts` - `apps/admin/src/lib/reports/service.ts` - endpoint dedicado de reversão de recibo, caso a API não seja absorvida nas rotas já existentes ## Não alterar - `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` - `apps/admin/src/components/reports/report-page-client.tsx` - `apps/admin/src/components/reports/report-charts.tsx` - `apps/admin/src/lib/reports/contracts.ts` - camada de relatórios da Sprint 1 ## 12. Impactos e Riscos ### 1. Carteira operacional atual - a remoção da carteira híbrida pode mudar números e percepção na página operacional de recebíveis. ### 2. Legado com `[RECEBER]` em `MANUAL` - a compatibilidade histórica pode exigir saneamento futuro. ### 3. Status cancelado - o redesenho da trigger precisa impedir reclassificação indevida de títulos cancelados. ### 4. Dupla verdade com REL-004 - sem reconciliação arquitetural posterior, `payments` e `receivable_receipts` ainda podem parecer portas paralelas de liquidação. ### 5. Invasão de REL-006 - tentar fechar a política universal de estorno nesta história ampliará indevidamente o escopo. ## 13. Estratégia Recomendada 1. Autorizar a `REL-005` como pacote estrutural de banco do domínio `accounts_receivable -> receivable_receipts -> cash_flow`. 2. Implementar primeiro a routine oficial de baixa e sincronização do título. 3. Implementar em seguida a formalização do reflexo em `cash_flow`. 4. Implementar por último a reabertura mínima do recibo no próprio domínio. 5. Tratar a carteira híbrida da página operacional apenas no necessário para não contradizer a nova fonte oficial. 6. Preservar integralmente a `REL-006` para a política universal de reversão auditável. ## Conclusão Arquitetural Existe um pacote mínimo, claro e controlável para a `REL-005`: - routine oficial de baixa do título; - routine oficial de sincronização do título; - formalização da trilha `receivable_receipts -> cash_flow`; - reabertura mínima do título no domínio de recebíveis; - endurecimento do ciclo de vida do título em `accounts_receivable`. Esse pacote: - aprova `CT-005`, `CT-006`, `CT-008` e `CT-009`; - não exige fechar o `CT-015`; - não exige alterar `REL-004`; - não exige reabrir a camada analítica da Sprint 1; - mantém a separação correta entre `REL-005` e `REL-006`. ## Decisão Formal - **REL-005 AUTORIZADA** ## Fundamentação Técnica Detalhada 1. O diagnóstico e a auditoria já identificaram o problema real e o recorte da história. 2. A presente decisão arquitetural fecha a lacuna que faltava: separar a reabertura mínima do título da política universal de reversão. 3. O menor conjunto de mudanças necessário já está claramente definido em migrations, triggers, procedures e rotas. 4. Os casos `CT-005`, `CT-006`, `CT-008` e `CT-009` podem ser aprovados sem invadir `REL-006`. 5. O `CT-015` continua corretamente reservado à integração final entre `REL-004`, `REL-005` e `REL-006`. ## Condição de Autorização A autorização da `REL-005` deve ser entendida como autorização **somente** para: - alterar banco no domínio `accounts_receivable`, `receivable_receipts` e `cash_flow`; - criar as migrations mínimas descritas neste documento; - revisar as rotas `accounts-receivable` e `receive`; - ajustar consumidores operacionais apenas no necessário para preservar a verdade oficial da carteira; - implementar a reabertura mínima do título no próprio domínio de recebíveis. ## Limites Formais Essa autorização **não** inclui: - iniciar `REL-006`; - padronizar a política universal de estorno; - fechar `CT-015`; - reabrir `REL-004`; - reabrir a camada de relatórios e exportações da Sprint 1.