# Decisão Arquitetural - REL-006 ## Objetivo Produzir a decisão arquitetural definitiva da `REL-006`, definindo: - o menor conjunto de alterações capaz de fechar o `CT-015`; - o que pertence obrigatoriamente à `REL-006`; - o que deve permanecer fora do escopo; - quais migrations, procedures, triggers, APIs e componentes são obrigatórios; - como a reversão universal deve afetar: - `orders` - `payments` - `accounts_receivable` - `receivable_receipts` - `cash_flow` - `commission_events` - qual deve ser o contrato obrigatório de rastreabilidade entre evento original e reverso; - quais `CTs` serão aprovados após a história. ## Base obrigatória Documentos considerados: - `docs/relatorios/DIAGNOSTICO_REL_006.md` - `docs/relatorios/AUDITORIA_DIAGNOSTICO_REL_006.md` - `docs/relatorios/DECISAO_CT_015.md` Arquivos reais validados para fechamento da decisão: - `apps/admin/src/app/actions/financial.ts` - `apps/admin/src/components/orders/financial-section.tsx` - `apps/admin/src/app/api/pdv/cancel-sale/route.ts` - `apps/admin/src/app/api/accounts-receivable/route.ts` - `apps/admin/src/app/api/cash-flow/route.ts` - `apps/admin/src/lib/reports/service.ts` - `apps/admin/src/lib/financial-reporting.ts` - `apps/admin/src/db/migrations/61_create_commission_foundation.sql` - `apps/admin/src/db/migrations/63_add_commission_payment_engine.sql` - `apps/admin/src/db/migrations/64_add_commission_closure_and_payouts.sql` - `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/db/migrations/73_formalize_receivable_receipts_cash_flow_pipeline.sql` - `apps/admin/src/db/migrations/74_harden_accounts_receivable_lifecycle.sql` - `apps/admin/src/db/migrations/75_add_minimal_receipt_reversal_support.sql` ## Síntese executiva A auditoria da `REL-006` corrigiu o ponto que faltava no diagnóstico: o problema não está apenas em `payments`, `receivable_receipts` e `cash_flow`, mas também no motor de comissão, que hoje deriva eventos de `payment_id` e ainda trata a reversão como consequência de `DELETE`. Com essa correção incorporada, a decisão arquitetural conclui que: - a `REL-006` continua sendo a história correta para fechar o `CT-015`; - o menor pacote viável **não** exige reabrir `REL-004` nem `REL-005`, mas exige complementar o que elas deixaram deliberadamente em aberto; - a `REL-006` deve substituir a exclusão física de `payments` por reversão lógica auditável; - a `REL-006` deve harmonizar `receivable_receipts` ao mesmo contrato universal, sem desfazer a reversão mínima já entregue; - a `REL-006` deve formalizar o vínculo entre evento original, evento reverso, motivo, executor e timestamp; - a `REL-006` deve adaptar o motor de comissão para reagir à reversão lógica do pagamento, e não mais ao `DELETE`; - a `REL-006` deve corrigir a leitura operacional e analítica para refletir o líquido oficial; - após esse pacote, o `CT-015` passa integralmente. ## 1. O Que Pertence Obrigatoriamente à REL-006 Pertence obrigatoriamente à `REL-006`: - substituir exclusão física de `payments` por reversão lógica auditável; - padronizar o contrato universal de reversão entre `payments`, `receivable_receipts`, `cash_flow` e `commission_events`; - endurecer a proibição de `DELETE` em eventos financeiros oficiais; - adaptar o cancelamento `PDV` para consumir o novo contrato sem apagar trilha financeira oficial; - preservar o evento original e registrar explicitamente o evento reverso; - garantir vínculo formal entre original e reverso no caixa e nas trilhas derivadas; - ajustar o motor de comissão para reversão lógica por `payment_id`; - corrigir `Valor Recebido` para visão líquida oficial quando houver reversão formal; - garantir que `cash-flow/route.ts` leia reversões por metadados estruturais, e não por convenção textual apenas; - fechar o `CT-015` com evidência transversal entre operação, caixa, carteira e comissão. ## 2. O Que Não Pertence à REL-006 Não pertence à `REL-006`: - reabrir a implementação base da `REL-004`; - reabrir a implementação base da `REL-005`; - alterar a criação normal de pagamentos; - alterar a criação normal de recibos; - redesenhar `accounts_receivable` como vínculo obrigatório de `orders`; - criar fusão estrutural entre `payments` e `receivable_receipts`; - alterar `checkout` do `PDV` como fluxo primário; - alterar relatórios fora do recorte necessário para `CT-015`; - alterar `commission_periods`, `commission_payouts`, `commission_statement_items` ou fechamento de comissão; - iniciar nova história fora do eixo de reversão auditável universal. ## Separação formal entre REL-004, REL-005 e REL-006 ### REL-004 Permanece responsável por: - `orders -> payments -> cash_flow`; - criação oficial do caixa do pagamento; - sincronização oficial do resumo do pedido; - reversão compensatória inicial do domínio de pagamento. ### REL-005 Permanece responsável por: - `accounts_receivable -> receivable_receipts -> cash_flow`; - baixa parcial, total e múltipla; - reabertura mínima do título; - sincronização oficial da carteira. ### REL-006 Passa a ser exclusivamente responsável por: - eliminar exclusão física como fluxo oficial dos eventos financeiros principais; - padronizar o contrato universal de reversão; - completar a rastreabilidade entre domínios; - alinhar comissão ao novo contrato; - fechar o `CT-015`. ## 2. Dependência de comissão incorporada ## Estado atual Hoje já existe acoplamento direto entre `payments` e comissão: - `generate_commission_events_for_payment(p_payment_id uuid)` gera `commission_events` na inserção do pagamento; - `reverse_commission_events_for_payment(p_payment_id uuid, p_reason text)` gera a reversão derivada; - a trigger `payments_generate_commission_events` roda `AFTER INSERT ON public.payments`; - a trigger `payments_reverse_commission_events` roda `BEFORE DELETE ON public.payments`; - a auditoria de comissão ainda usa ação textual `reversed_from_payment_delete`. ## Decisão A dependência com comissão **não é opcional** na `REL-006`. Logo: - o motor de comissão faz parte do pacote obrigatório da história; - a semântica de comissão deve migrar de "reversão por delete" para "reversão por evento lógico"; - o vínculo `payment_id` deve continuar preservado; - `commission_events` deve manter: - evento original; - evento reverso; - referência ao evento original via `reversed_event_id`; - motivo de reversão coerente com o novo contrato; - auditoria textual sem dependência do termo `payment_delete`. ## 3. Menor Conjunto de Alterações Para Fechar o CT-015 ## Pacote mínimo obrigatório ### 1. Tornar `payments` reversível sem `DELETE` Necessário: - adicionar metadados de reversão em `payments`; - trocar o fluxo oficial de `delete_payment_with_cleanup(...)` por `reverse_payment_with_cash_flow(...)`; - recalcular `orders` por reversão lógica em vez de `AFTER DELETE`. Objetivo: - preservar o evento original de pagamento; - manter trilha auditável completa; - eliminar a exclusão física como política oficial. ### 2. Harmonizar `receivable_receipts` ao contrato universal Necessário: - manter `reverse_receipt_with_cash_flow(...)`; - alinhar o contrato de reversão do recibo aos mesmos metadados e vínculos estruturais do pagamento; - parar de depender apenas de prefixo textual para identificar reversão no caixa. Objetivo: - unificar o comportamento entre os dois domínios sem reabrir a `REL-005`. ### 3. Formalizar o vínculo universal em `cash_flow` Necessário: - registrar explicitamente qual lançamento reverso compensa qual lançamento original; - impedir leitura ambígua de reversão; - manter o caixa append-only para trilha financeira oficial. Objetivo: - fazer `Fluxo de Caixa Líquido` e reconciliação financeira dependerem de estrutura, não de convenção textual. ### 4. Adaptar comissão ao novo contrato lógico Necessário: - manter geração de comissão na criação do pagamento; - substituir a reversão baseada em `BEFORE DELETE ON payments`; - fazer a reversão derivada reagir à reversão lógica do pagamento; - preservar `payment_id`, `reversed_event_id`, `reason`, `actor` e `timestamp`. Objetivo: - fechar a rastreabilidade completa do `CT-015`. ### 5. Corrigir a leitura operacional e analítica Necessário: - ajustar `cash-flow/route.ts` para leitura por metadados estruturais; - ajustar `service.ts` para `Valor Recebido` líquido oficial; - ajustar a superfície de pedido para deixar de expor "exclusão de pagamento" como verbo oficial. Objetivo: - alinhar contrato técnico, contrato operacional e contrato analítico. ## O que não é necessário para fechar o CT-015 Não é necessário: - vincular `accounts_receivable` a `orders` por chave obrigatória; - vincular `receivable_receipts` a `payment_id`; - redesenhar a carteira oficial da `REL-005`; - reabrir a camada completa de exportações e gráficos fora do campo "recebido líquido"; - revisar fechamento, aprovação e payout de comissão; - alterar `pdv/checkout/route.ts`. ## 4. Contrato Universal Obrigatório de Reversão ## Regra central Todo evento financeiro reversível coberto pela `REL-006` deve obedecer ao seguinte contrato: - o evento original permanece persistido; - o evento reverso é um novo evento explícito ou uma marcação lógica equivalente, sem apagar o original; - o motivo da reversão é obrigatório; - o usuário executor é obrigatório; - o timestamp auditável é obrigatório; - o vínculo entre original e reverso é obrigatório e estrutural; - efeitos derivados também precisam ser reversíveis e rastreáveis. ## Vínculo obrigatório entre original e reverso ### Em `payments` Obrigatório mínimo: - `reversed_at` - `reversed_by` - `reversal_reason` - marcador lógico que impeça novo uso financeiro do pagamento revertido Decisão: - o pagamento original deve continuar existindo; - a reversão do caixa e da comissão deve apontar para o mesmo `payment_id`. ### Em `receivable_receipts` Obrigatório mínimo: - preservar os campos já introduzidos: - `reversed_at` - `reversed_by` - `reversal_reason` - `reversed_receipt_id` Decisão: - a `REL-006` não substitui esse modelo; - ela o harmoniza ao contrato universal. ### Em `cash_flow` Obrigatório mínimo: - vínculo explícito entre lançamento original e lançamento reverso; - motivo da reversão; - executor; - timestamp auditável do lançamento reverso. Decisão: - `reference_id` sozinho não é suficiente; - o caixa precisa de um campo estrutural de pareamento, como `reversal_of_id` ou equivalente semântico obrigatório. ### Em `commission_events` Obrigatório mínimo: - manter `reversed_event_id`; - preservar `payment_id`; - registrar razão de reversão compatível com reversão lógica; - registrar executor e timestamp auditável. Decisão: - `commission_events` deve continuar append-only; - a reversão deve deixar de ser semanticamente dependente de `payment_delete`. ## Fonte da verdade do vínculo - `orders` e `accounts_receivable` continuam como agregados derivados; - a fonte da verdade do vínculo original/reverso fica nos próprios eventos operacionais e financeiros: - `payments` - `receivable_receipts` - `cash_flow` - `commission_events` ## 5. Como a Reversão Universal Deve Afetar Cada Domínio ## `orders` Deve: - recalcular `paid_amount` ignorando pagamentos revertidos; - recalcular `financial_status` sem depender de `DELETE`; - continuar sendo agregado derivado, não fonte primária da reversão. Não deve: - virar fonte de vínculo original/reverso; - carregar a lógica principal de auditoria. ## `payments` Deve: - permanecer persistido; - ganhar metadados obrigatórios de reversão; - deixar de ser fisicamente excluído; - disparar reversão oficial em `cash_flow`; - disparar reversão derivada em comissão; - tornar `deletePayment(...)` apenas um alias operacional de reversão ou ser substituído por ação nominalmente correta. ## `accounts_receivable` Deve: - continuar recebendo recomputação oficial via `sync_receivable_summary(...)`; - reabrir saldo quando um recibo válido for revertido; - continuar como agregado da carteira, não como armazenador primário do vínculo universal. ## `receivable_receipts` Deve: - continuar como evento persistido; - continuar reversível sem exclusão física; - aderir ao mesmo contrato estrutural de reversão do pagamento; - deixar de depender apenas de prefixo textual no reflexo financeiro. ## `cash_flow` Deve: - preservar entrada original e saída reversa; - registrar pareamento estrutural original/reverso; - proibir remoção física do fluxo oficial; - servir de fonte oficial do líquido financeiro. ## `commission_events` Deve: - continuar sendo derivado de `payment_id`; - gerar evento reverso por reversão lógica do pagamento; - manter `reversed_event_id`; - abandonar a semântica "reversed_from_payment_delete"; - permanecer auditável sem apagar evento original. ## 6. Migrations Necessárias ## Migration 1 - Obrigatória ### Nome sugerido - `76_replace_payment_delete_with_logical_reversal.sql` ### Conteúdo mínimo - adicionar metadados de reversão em `payments`; - substituir a semântica oficial de exclusão por reversão lógica; - introduzir rotina de sincronização de `orders` compatível com pagamento revertido; - bloquear `DELETE` físico comum em `payments`. ### Objetivo - remover o principal ponto de violação do modelo imutável. ## Migration 2 - Obrigatória ### Nome sugerido - `77_finalize_cash_flow_reversal_contract.sql` ### Conteúdo mínimo - adicionar vínculo estrutural entre `cash_flow` original e reverso; - endurecer proteção contra remoção física de `cash_flow` oficial; - harmonizar reversão de `receivable_receipts` com o novo contrato; - eliminar dependência exclusiva de prefixo textual para classificação de reversão. ### Objetivo - tornar o caixa a fonte oficial inequívoca do líquido financeiro. ## Migration 3 - Obrigatória ### Nome sugerido - `78_adapt_commission_engine_to_logical_payment_reversal.sql` ### Conteúdo mínimo - adaptar `generate_commission_events_for_payment(...)` se necessário para não duplicar eventos no novo contrato; - adaptar `reverse_commission_events_for_payment(...)` para reversão lógica; - substituir trigger orientada a `BEFORE DELETE`; - corrigir o audit trail textual de comissão. ### Objetivo - fechar a trilha derivada de comissão no `CT-015`. ## Migration 4 - Condicional ### Nome sugerido - `79_harden_pdv_operational_audit_trail.sql` ### Conteúdo mínimo - tornar `pdv_cash_movements` append-only ou equivalente; - impedir remoção indevida de `cash_flow` vinculada ao cancelamento `PDV`. ### Decisão - recomendada; - condicional ao entendimento final se o `CT-015` exigirá também endurecimento operacional completo do `PDV`, além da trilha financeira oficial. ## 7. Procedures Obrigatórias ## Obrigatórias - `reverse_payment_with_cash_flow(p_payment_id uuid, p_reason text DEFAULT NULL)` - substitui o fluxo de exclusão física do pagamento - marca o pagamento como revertido - cria a reversão oficial em `cash_flow` - sincroniza `orders` - `reverse_receipt_with_cash_flow(p_receipt_id uuid, p_reason text DEFAULT NULL)` - permanece existente - deve ser harmonizada ao contrato universal - `reverse_commission_events_for_payment(p_payment_id uuid, p_reason text DEFAULT NULL)` - permanece existente - deve deixar de depender semanticamente de `payment_delete` - helper persistido de pareamento universal de reversão - pode ser nova function dedicada - ou pode ser absorvido pelas routines de reversão - precisa garantir vínculo estrutural entre original e reverso ## Prováveis - substituição de `reverse_pdv_order_payments_with_cleanup(p_order_id uuid)` - para consumir `reverse_payment_with_cash_flow(...)` - helper de reversão operacional do `PDV` - se a implementação absorver também a trilha operacional local ## Não obrigatórias no pacote mínimo - procedures de criação de pagamento; - procedures de criação de recibo; - procedures de fechamento de comissão; - procedures de payout de comissão. ## 8. Triggers Obrigatórias ## Obrigatórias - trigger/routine em `payments` orientada à reversão lógica - para sincronizar `orders` sem `DELETE` - trigger de guarda `BEFORE DELETE ON public.payments` - para bloquear exclusão física comum - trigger de guarda `BEFORE DELETE ON public.cash_flow` - para proteger trilha financeira oficial - revisão da trigger `payments_reverse_commission_events` - deve deixar de depender de `BEFORE DELETE` ## Prováveis - trigger de guarda `BEFORE DELETE ON public.receivable_receipts` - para consolidar o princípio universal - trigger de guarda em `pdv_cash_movements` - se a história absorver append-only também para o caixa operacional do `PDV` ## Não obrigatórias no pacote mínimo - triggers em `orders` fora do resumo financeiro; - triggers em relatórios; - triggers em fechamento de comissão. ## 9. APIs Obrigatórias ## Obrigatórias - `apps/admin/src/app/actions/financial.ts` - trocar consumo de `delete_payment_with_cleanup(...)` por rotina oficial de reversão lógica - `apps/admin/src/app/api/pdv/cancel-sale/route.ts` - parar de remover trilha financeira oficial - passar a consumir a nova routine oficial de reversão de pagamento - `apps/admin/src/app/api/accounts-receivable/route.ts` - manter a reversão mínima de recibo - exigir integração com o novo contrato universal quando aplicável - `apps/admin/src/app/api/cash-flow/route.ts` - ler reversões por vínculo estrutural - não depender apenas de prefixo textual - `apps/admin/src/app/api/reports/route.ts` - consumidor indireto obrigatório da correção em `service.ts` - `apps/admin/src/app/api/reports/export/route.ts` - consumidor indireto obrigatório da mesma verdade analítica ## Prováveis - `apps/admin/src/app/api/accounts-receivable/[id]/receive/route.ts` - só se a harmonização do contrato exigir metadado adicional já na criação do recibo ## Não obrigatórias - `apps/admin/src/app/api/pdv/checkout/route.ts` - rotas de leitura de comissão - rotas de payout ou fechamento de comissão ## 10. Componentes Obrigatórios ## Obrigatórios - `apps/admin/src/components/orders/financial-section.tsx` - precisa deixar de expor exclusão física como ação oficial ## Prováveis - `apps/admin/src/app/dashboard/financial/cash-flow/page.tsx` - se a leitura de origem/reversão depender de pequeno ajuste visual - `apps/admin/src/app/dashboard/financial/receivables/page.tsx` - se a apresentação do título reaberto exigir ajuste operacional mínimo ## Condicionais - `apps/admin/src/components/reports/report-page-client.tsx` - `apps/admin/src/components/reports/report-charts.tsx` - `apps/admin/src/lib/reports/contracts.ts` Decisão: - só entram se a mudança de semântica analítica exigir novo shape de resposta; - o pacote mínimo preferencial deve preservar o contrato atual de consumo. ## 11. Classificação de Arquivos ## Obrigatórios - `apps/admin/src/app/actions/financial.ts` - `apps/admin/src/components/orders/financial-section.tsx` - `apps/admin/src/app/api/pdv/cancel-sale/route.ts` - `apps/admin/src/app/api/accounts-receivable/route.ts` - `apps/admin/src/app/api/cash-flow/route.ts` - `apps/admin/src/lib/reports/service.ts` - novas migrations em `apps/admin/src/db/migrations/` ## Prováveis - `apps/admin/src/lib/financial-reporting.ts` - `apps/admin/src/app/dashboard/financial/cash-flow/page.tsx` - `apps/admin/src/app/dashboard/financial/receivables/page.tsx` - `apps/admin/src/app/api/accounts-receivable/[id]/receive/route.ts` ## Condicionais - `apps/admin/src/components/reports/report-page-client.tsx` - `apps/admin/src/components/reports/report-charts.tsx` - `apps/admin/src/lib/reports/contracts.ts` - helper ou endpoint dedicado para reversão universal, se o time preferir não concentrar a ação em `financial.ts` e `cancel-sale` ## Não alterar - `docs/relatorios/STATUS.md` - `docs/relatorios/CHANGELOG.md` - `docs/relatorios/DECISOES.md` - `apps/admin/src/db/migrations/61_create_commission_foundation.sql` - `apps/admin/src/db/migrations/63_add_commission_payment_engine.sql` - `apps/admin/src/db/migrations/64_add_commission_closure_and_payouts.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/71_formalize_payments_cash_flow_pipeline.sql` - `apps/admin/src/db/migrations/72_replace_delete_payment_cleanup_with_auditable_reversal.sql` - `apps/admin/src/db/migrations/73_formalize_receivable_receipts_cash_flow_pipeline.sql` - `apps/admin/src/db/migrations/74_harden_accounts_receivable_lifecycle.sql` - `apps/admin/src/db/migrations/75_add_minimal_receipt_reversal_support.sql` - `apps/admin/src/app/api/pdv/checkout/route.ts` - rotas e componentes de payout, fechamento e statement de comissão ## 12. CTs Que Serão Aprovados Após a REL-006 ## CT aprovado pela REL-006 - `CT-015` ## Fundamentação Após a `REL-006`, o sistema passa a ter: - reversão sem exclusão física como política oficial; - trilha auditável entre evento original e reverso; - reabertura do título quando aplicável; - caixa líquido estruturalmente reconciliado; - `Valor Recebido` líquido oficial; - reversão derivada de comissão coerente com o mesmo `payment_id`. ## CTs que não são alvo novo da REL-006 - `CT-002` - `CT-004` - `CT-005` - `CT-006` - `CT-008` - `CT-009` - `CT-010` Decisão: - esses casos já pertencem ao fechamento anterior de `REL-004` e `REL-005`; - a `REL-006` pode endurecer a coerência transversal deles, mas não deve reclassificá-los como alvo primário. ## 13. Riscos e limites ## Riscos principais - risco de manter UI e banco com verbos diferentes se a superfície de pedido não for ajustada; - risco de rastreabilidade parcial se comissão continuar semanticamente presa a `payment_delete`; - risco de leitura líquida divergente se `service.ts` e `cash-flow/route.ts` forem corrigidos por convenção textual em vez de vínculo estrutural; - risco de assimetria operacional residual no `PDV` se o caixa operacional local continuar apagável. ## Limite formal da história A `REL-006` fecha o `CT-015` somente se: - a exclusão física deixar de ser política oficial dos eventos financeiros principais; - comissão estiver integrada ao mesmo contrato; - relatório financeiro e fluxo de caixa convergirem para o mesmo líquido oficial; - carteira e pedido refletirem corretamente o estado pós-reversão. ## Conclusão arquitetural Com a dependência de comissão explicitamente incorporada, o problema da `REL-006` fica definitivamente delimitado: - `REL-004` não precisa ser reaberta; - `REL-005` não precisa ser reaberta; - o pacote mínimo da `REL-006` é claro, controlável e tecnicamente justificável; - existe um menor conjunto coerente de migrations, procedures, triggers, APIs e componentes capaz de fechar o `CT-015`. O ponto que bloqueava a autorização na auditoria não era a inviabilidade da história, mas a ausência de uma dependência real no diagnóstico. Essa dependência agora está explicitamente absorvida pela decisão arquitetural. ## Recomendação formal - **A) REL-006 AUTORIZADA** ## Condição de autorização A autorização da `REL-006` deve ser entendida como autorização **somente** para: - complementar o banco com novas migrations da história; - substituir exclusão física por reversão lógica auditável em `payments`; - harmonizar `receivable_receipts` ao contrato universal; - adaptar `cash_flow` ao vínculo estrutural original/reverso; - adaptar `commission_events` à reversão lógica do pagamento; - ajustar apenas as APIs, componentes e leituras analíticas estritamente necessários para fechar o `CT-015`. ## Limites formais Essa autorização **não** inclui: - reabrir `REL-004` como nova história; - reabrir `REL-005` como nova história; - redesenhar o módulo de comissão além do vínculo com reversão de pagamento; - remodelar carteiras, relatórios ou exportações fora do recorte do `CT-015`; - iniciar qualquer história posterior sem nova autorização explícita.