# Decisão Arquitetural - REL-004 ## Objetivo Executar exclusivamente a análise de autorização arquitetural da `REL-004`, definindo: - quais alterações estruturais são obrigatórias; - quais podem ser adiadas para `REL-005` ou `REL-006`; - qual é o menor conjunto de mudanças capaz de formalizar: - `payments -> cash_flow` - `payments -> orders` - cancelamento `PDV` auditável; - quais migrations, procedures e triggers são necessárias; - quais `CTs` passam após a história e quais continuam dependentes das demais histórias da Sprint 2. ## Base de Decisão Foram considerados como base exclusiva: - `DIAGNOSTICO_REL_004.md` - `AUDITORIA_DIAGNOSTICO_REL_004.md` - `BACKLOG_EXECUTIVO.md` - `PLANO_DE_CORRECAO.md` - `PLANO_DE_EXECUCAO.md` - `CASOS_DE_TESTE.md` - `DECISAO_CT_015.md` ## Síntese Executiva A análise arquitetural conclui que: - a `REL-004` tem escopo válido, real e suficientemente delimitado; - a história **não** deve tocar `accounts_receivable`, `receivable_receipts` nem a camada analítica de relatórios; - existe um conjunto mínimo de mudanças estruturais capaz de formalizar a trilha `orders -> payments -> cash_flow` sem invadir `REL-005` e `REL-006`; - esse conjunto mínimo exige, obrigatoriamente, alterações em banco, migrations, procedures e triggers; - portanto, a `REL-004` só deixa de estar bloqueada quando a Sprint 2 é autorizada explicitamente com esse pacote estrutural. ## Arquitetura Atual ### 1. Pagamento do pedido Hoje: - `financial.ts` valida o saldo pendente do pedido; - depois insere diretamente em `payments`; - o reflexo oficial em `cash_flow` não aparece de forma determinística e explícita no mesmo trilho visível; - a sincronização de `orders.paid_amount` e `orders.financial_status` também não aparece formalizada no código de aplicação. ### 2. Cancelamento e exclusão de pagamento Hoje: - exclusão manual usa `delete_payment_with_cleanup()`; - a procedure tenta apagar `cash_flow` com `origin = PEDIDO`; - apenas em fallback cria compensação; - depois exclui fisicamente `payments`. Conclusão: - o sistema ainda trata exclusão física como caminho principal; - a reversão auditável não é o padrão primário. ### 3. PDV Hoje: - `pdv/checkout/route.ts` cria `payments`; - cria `pdv_cash_movements` para dinheiro; - registra `cash_flow` explicitamente apenas para troco; - `pdv/cancel-sale/route.ts` remove `pdv_cash_movements`, tenta apagar `cash_flow PEDIDO`, apaga `payments` e zera o resumo financeiro do pedido. Conclusão: - o fluxo `PDV` contém lógica financeira relevante demais na rota; - a auditoria depende de exclusões e de fallback, não de uma regra única persistida. ### 4. Comissão Hoje: - o motor de comissão já reage a `payments` por trigger; - isso prova que o domínio de `payments` já tem automação persistida; - porém a trilha de caixa não segue o mesmo grau de formalização. ## Arquitetura Proposta Para a REL-004 ### Princípio central A `REL-004` deve formalizar um único eixo oficial: - `orders` - `payments` - `cash_flow` Sem assumir: - `accounts_receivable` - `receivable_receipts` - reabertura de carteira por título - política transversal completa de estorno auditável ### Fluxo proposto #### Inserção de pagamento 1. Aplicação insere em `payments`. 2. Trigger/procedure persistida cria o `cash_flow` oficial do pagamento com `origin = PEDIDO`. 3. Trigger/procedure persistida recalcula `orders.paid_amount`. 4. Trigger/procedure persistida recalcula `orders.financial_status`. #### Exclusão ou reversão de pagamento 1. A exclusão manual não apaga mais o `cash_flow` original como caminho primário. 2. A rotina oficial cria evento compensatório em `cash_flow`. 3. O pedido é recalculado com base nos pagamentos ativos remanescentes. 4. A reversão de comissão continua preservada pelo mecanismo já existente ou por chamada explícita equivalente. #### Cancelamento PDV 1. A rota deixa de ter responsabilidade principal sobre a regra financeira. 2. O cancelamento passa a reutilizar a mesma política oficial de reversão dos pagamentos do pedido. 3. O pedido é atualizado apenas após a reversão financeira oficial. 4. `order_history` continua registrando a narrativa operacional do cancelamento. ## Menor Conjunto de Mudanças Obrigatórias ## Mudanças obrigatórias ### 1. Formalizar `payments -> cash_flow` Obrigatório: - criar uma rotina persistida única para materializar o lançamento em `cash_flow` a partir de `payments`; - impedir que o lançamento `PEDIDO` fique implícito ou dependa de comportamento invisível; - garantir idempotência para não duplicar `cash_flow` do mesmo pagamento. ### 2. Formalizar `payments -> orders` Obrigatório: - criar uma rotina persistida única para recalcular `orders.paid_amount`; - recalcular `orders.financial_status` com base na soma dos pagamentos válidos; - impedir que esse resumo continue dependente de mecanismo opaco ou implícito. ### 3. Formalizar reversão auditável do pagamento Obrigatório: - substituir o modelo "apaga primeiro, compensa se falhar" por "compensa como regra oficial"; - manter `cash_flow` original do pagamento; - registrar evento reverso correspondente no caixa; - preservar a consistência de `orders` após a reversão. ### 4. Tirar a regra financeira principal de dentro do cancelamento PDV Obrigatório: - `pdv/cancel-sale/route.ts` deve passar a chamar a política oficial de reversão; - a rota deve deixar de ser o lugar onde a lógica de caixa é decidida; - a narrativa operacional pode continuar na rota, mas a regra transacional precisa ir para o banco/procedure. ### 5. Proteger contra duplicidade de reflexo financeiro Obrigatório: - adicionar proteção estrutural para que o mesmo `payment_id` não gere múltiplos `cash_flow PEDIDO` indevidos; - isso pode ser feito por índice parcial único ou regra equivalente de idempotência. ## Mudanças opcionais ### 1. Soft-delete ou status de reversão em `payments` Opcional na `REL-004`, recomendável para fase posterior: - adicionar `status`, `reversed_at`, `reversed_by`, `reversal_reason` em `payments`; - evitar exclusão física total do evento operacional. Decisão arquitetural: - desejável; - **não obrigatória** para o menor pacote da `REL-004`, desde que `cash_flow` preserve a trilha oficial e a reversão seja materializada corretamente. ### 2. Origem explícita de estorno em `cash_flow` Opcional na `REL-004`, recomendável para `REL-006`: - criar `origin` específico como `ESTORNO_PEDIDO`; - hoje o sistema já usa `AJUSTE` como fallback. Decisão arquitetural: - desejável para semântica futura; - **não obrigatória** se a reversão for padronizada com `reference_id`, descrição e razão de negócio. ### 3. Tornar `pdv_cash_movements` append-only Opcional na `REL-004`, recomendável para endurecimento futuro: - em vez de apagar movimentos do PDV, registrar movimentos compensatórios; - melhora a auditoria operacional do caixa local. Decisão arquitetural: - recomendável; - **não obrigatória** para formalizar a verdade financeira oficial, que pertence a `cash_flow`. ## O Que Pode Ser Adiado Para REL-005 - qualquer mudança em `accounts_receivable`; - qualquer mudança em `receivable_receipts`; - revisão da trigger `sync_accounts_receivable_status()`; - reversão formal de recebimentos de títulos; - reabertura de saldo de carteira por título; - coerência transacional entre título, recibo e caixa. ## O Que Pode Ser Adiado Para REL-006 - política transversal definitiva de fluxo imutável; - padrão universal entre exclusão, compensação e reversão; - vínculo auditável padronizado entre evento original e reverso em todos os domínios; - soft-delete universal dos eventos financeiros; - semântica final de recebido líquido pós-estorno em todos os universos; - fechamento completo do `CT-015`. ## Migrations Necessárias ## Migration 1 - Obrigatória ### Nome sugerido - `71_formalize_payments_cash_flow_pipeline.sql` ### Conteúdo mínimo - criar função `create_cash_flow_from_payment(p_payment_id uuid)`; - criar função `sync_order_payment_summary(p_order_id uuid)`; - criar função trigger `handle_payment_insert_effects()`; - criar trigger `AFTER INSERT ON public.payments`; - criar trigger `AFTER DELETE ON public.payments` para recalcular `orders`; - criar proteção de idempotência para `cash_flow PEDIDO` por `reference_id`. ### Objetivo - fechar o trilho oficial de pagamento do pedido no banco; - tornar o reflexo em caixa e pedido determinístico. ## Migration 2 - Obrigatória ### Nome sugerido - `72_replace_delete_payment_cleanup_with_auditable_reversal.sql` ### Conteúdo mínimo - substituir ou reescrever `delete_payment_with_cleanup()`; - trocar exclusão primária de `cash_flow` por criação de reversão oficial; - recalcular o resumo financeiro do pedido após a reversão; - preservar compatibilidade com comissão. ### Objetivo - transformar reversão compensatória em política oficial para pagamentos de pedido. ## Migration 3 - Condicional ### Nome sugerido - `73_harden_pdv_cancel_payment_reversal.sql` ### Conteúdo mínimo - opcionalmente criar helper para reversão em lote dos pagamentos do pedido; - opcionalmente padronizar como o `PDV` registra a trilha compensatória de caixa operacional. ### Objetivo - reduzir lógica transacional duplicada na rota `cancel-sale`. ### Decisão - recomendada; - pode ser absorvida pela `Migration 2` se o time preferir um pacote único. ## Procedures Necessárias ## Obrigatórias - `create_cash_flow_from_payment(p_payment_id uuid)` - cria o lançamento oficial `PEDIDO` em `cash_flow` - `sync_order_payment_summary(p_order_id uuid)` - recalcula `orders.paid_amount` - recalcula `orders.financial_status` - `delete_payment_with_cleanup(...)` reescrita - ou nova procedure compatível - precisa deixar de apagar `cash_flow` como fluxo primário - precisa registrar reversão oficial ## Prováveis - helper de reversão em lote para cancelamento de pedido/PDV - útil para reaproveitar a mesma política em `cancel-sale` ## Não obrigatórias na REL-004 - procedures de `accounts_receivable` - procedures de `receivable_receipts` - routines universais de estorno para todos os domínios financeiros ## Triggers Necessárias ## Obrigatórias - `AFTER INSERT ON public.payments` - criar `cash_flow PEDIDO` - sincronizar `orders` - `AFTER DELETE ON public.payments` - sincronizar `orders` - manter o resumo do pedido coerente após reversão ## Condicionais - trigger de guarda para impedir criação duplicada de `cash_flow` - dispensável se a idempotência for garantida por índice + função segura - trigger orientada a `UPDATE` em `payments` - só será necessária se a Ktalogu optar por modelo de soft-delete/status já na `REL-004` ## Não necessárias na REL-004 - triggers em `receivable_receipts` - triggers em `accounts_receivable` - triggers universais de estorno cross-domain ## Impactos ### payments - passa a ser o evento operacional formal do pedido; - deixa de depender de efeito implícito sobre caixa e resumo do pedido. ### cash_flow - passa a receber reflexo oficial e determinístico de cada pagamento do pedido; - passa a registrar reversão como política, não como fallback. ### orders - deixa de depender de sincronismo implícito; - passa a recalcular `paid_amount` e `financial_status` por rotina formal. ### PDV - reduz a lógica financeira transacional espalhada em rota; - passa a reutilizar a mesma política oficial do pagamento manual. ### comissão - precisa ser preservada e revalidada; - não é escopo funcional da `REL-004`, mas é risco técnico relevante. ### relatórios - não devem ser alterados; - apenas passam a consumir uma trilha transacional mais confiável. ## Riscos ### 1. Legado sem reflexo financeiro completo - pagamentos antigos podem não ter `cash_flow PEDIDO` consistente; - será necessário decidir se a correção é apenas prospectiva ou se haverá saneamento histórico. ### 2. Duplicidade de eventos - se o trigger de inserção não for idempotente, o mesmo pagamento pode gerar caixa duplicado. ### 3. Efeito colateral em comissão - a exclusão de `payments` já aciona reversão no motor de comissão; - qualquer mudança precisa preservar esse comportamento. ### 4. Divergência entre PDV local e caixa oficial - se `pdv_cash_movements` continuar apagando enquanto `cash_flow` vira append-only, haverá assimetria operacional; - isso é aceitável apenas como compromisso temporário claramente documentado. ### 5. Reabertura indevida de escopo - tocar `receive`, `accounts_receivable` ou relatórios nesta história quebrará a separação da Sprint 2. ## Estratégia Recomendada 1. Autorizar a Sprint 2 com escopo estritamente limitado à `REL-004`. 2. Implementar primeiro a formalização persistida de `payments -> cash_flow -> orders`. 3. Reescrever a procedure de exclusão/reversão antes de mexer na rota `cancel-sale`. 4. Adaptar `financial.ts` e `pdv/cancel-sale/route.ts` apenas para consumirem a política persistida oficial. 5. Preservar `REL-005` para títulos/recebimentos e `REL-006` para a política universal de estorno auditável. ## CTs que Passariam Após a REL-004 ### CT-002 - deve passar integralmente - motivo: pedido pago com entrada correspondente em caixa passa a ter trilha formal `payments -> cash_flow -> orders` ### CT-004 - deve passar no recorte oficial da `REL-004` - motivo: cancelamento de pedido pago com estorno financeiro passa a usar reversão auditável no domínio `pedido/pagamento/caixa` ### CT-010 - deve passar no recorte derivado de pagamentos e cancelamentos de pedido - motivo: o fluxo líquido do caixa passa a refletir entrada e reversão formal do universo `payments` ## CTs que Continuariam Dependendo de REL-005 - `CT-005` - `CT-006` - `CT-008` - `CT-009` Motivo: - todos pertencem ao domínio `accounts_receivable` / `receivable_receipts`. ## CTs que Continuariam Dependendo de REL-006 - `CT-015` Motivo: - a `REL-004` prepara o lado `pedido/pagamento/caixa`; - a `REL-005` fecha o lado `título/recebimento/caixa`; - a `REL-006` padroniza a política universal de reversão e o modelo imutável. ## CTs com Dependência Compartilhada Residual - `CT-004` - `CT-010` Observação: - a `REL-004` resolve o recorte do domínio de pagamento do pedido; - a padronização transversal completa ainda será consolidada pela `REL-006`. ## Conclusão Arquitetural Existe um pacote mínimo, claro e controlável para a `REL-004`: - trigger/procedure oficial para `payments -> cash_flow`; - trigger/procedure oficial para `payments -> orders`; - reescrita da reversão de pagamento para padrão compensatório auditável; - adaptação do cancelamento `PDV` para consumir a mesma política oficial. Esse pacote: - não exige tocar `accounts_receivable`; - não exige tocar `receivable_receipts`; - não exige reabrir relatórios; - não exige encerrar `CT-015`; - é compatível com a separação oficial entre `REL-004`, `REL-005` e `REL-006`. ## Conclusão Obrigatória - **A) Autorizar Sprint 2 e iniciar REL-004** ### Fundamentação 1. A auditoria anterior bloqueou corretamente a história sob as restrições antigas. 2. Esta decisão arquitetural define, de forma objetiva, o menor conjunto de mudanças estruturais necessário. 3. O escopo agora está suficientemente delimitado para execução sem invasão de `REL-005` e `REL-006`. 4. Os documentos oficiais já classificam a `REL-004` como história de banco e auditoria; a única condição faltante era a autorização arquitetural do pacote estrutural. ### Condição de autorização A autorização da Sprint 2 para `REL-004` deve ser entendida como autorização **somente** para: - alterar banco no recorte `orders`, `payments`, `cash_flow`; - criar as migrations mínimas descritas neste documento; - revisar a procedure de exclusão/reversão de pagamento; - criar triggers/funções mínimas para sincronização do pedido e reflexo em caixa; - adaptar `financial.ts`, `pdv/checkout/route.ts` e `pdv/cancel-sale/route.ts` apenas para consumirem a nova política oficial. ### Limites formais Essa autorização **não** inclui: - iniciar `REL-005`; - iniciar `REL-006`; - alterar `accounts_receivable`; - alterar `receivable_receipts`; - reabrir a camada de relatórios e exportações da Sprint 1; - declarar `CT-015` encerrado.