# Auditoria do Diagnóstico - REL-006

## Objetivo

Auditar exclusivamente o conteúdo de `DIAGNOSTICO_REL_006.md`, verificando se o documento:

- mapeia corretamente o `CT-015`;
- separa adequadamente `REL-004`, `REL-005` e `REL-006`;
- não invade escopo já concluído;
- identifica todas as dependências reais;
- classifica corretamente arquivos, migrations, procedures e triggers;
- propõe um plano que realmente fecha o `CT-015`;
- delimita corretamente o modelo imutável definitivo e a estratégia de rastreabilidade.

## Base auditada

Documento principal:

- `docs/relatorios/DIAGNOSTICO_REL_006.md`

Documentos de referência:

- `docs/relatorios/DECISAO_ARQUITETURAL_REL_004.md`
- `docs/relatorios/DECISAO_ARQUITETURAL_REL_005.md`
- `docs/relatorios/DECISAO_CT_015.md`

Arquivos reais validados para confronto:

- `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/lib/reports/service.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/72_replace_delete_payment_cleanup_with_auditable_reversal.sql`

## Achados

## 1. O diagnóstico separa corretamente `REL-004`, `REL-005` e `REL-006`

Achado:

- o documento mantém corretamente:
  - `REL-004` no domínio `orders -> payments -> cash_flow`;
  - `REL-005` no domínio `accounts_receivable -> receivable_receipts -> cash_flow`;
  - `REL-006` como história de padronização universal de reversão, imutabilidade e fechamento do `CT-015`.

Conclusão:

- esse ponto está correto;
- não há invasão indevida do escopo já concluído nas `REL-004` e `REL-005`.

## 2. O `CT-015` foi bem mapeado no eixo principal, mas não completamente

Achado:

- o diagnóstico acerta ao apontar que o `CT-015` depende de:
  - reversão auditável;
  - proibição de exclusão física como política oficial;
  - reabertura do título quando aplicável;
  - leitura líquida do relatório financeiro.

Lacuna:

- o documento não incorpora explicitamente a dependência já existente do subsistema de comissão sobre `payments`.

Evidência:

- `public.generate_commission_events_for_payment(p_payment_id uuid)` reage ao pagamento;
- `public.reverse_commission_events_for_payment(p_payment_id uuid, p_reason text)` reage hoje ao ciclo de remoção do pagamento;
- existem triggers:
  - `payments_generate_commission_events`
  - `payments_reverse_commission_events`
- a auditoria de comissão registra a ação textual `reversed_from_payment_delete`.

Conclusão:

- o `CT-015` não está completamente mapeado enquanto o impacto sobre comissão não for explicitamente incorporado ao pacote da `REL-006`, porque a troca de `DELETE` por reversão lógica em `payments` altera a base causal desse subsistema.

## 3. O diagnóstico identifica bem a assimetria entre `payments` e `receivable_receipts`

Achado:

- o documento descreve corretamente a principal lacuna atual:
  - `receivable_receipts` já suporta reversão lógica com metadados;
  - `payments` ainda usa compensação em `cash_flow` seguida de exclusão física.

Conclusão:

- esse ponto está correto e é central para a `REL-006`.

## 4. O diagnóstico subdimensiona as dependências reais

Achado:

- o documento mapeia dependências entre banco e APIs no eixo financeiro principal;
- porém não inclui a dependência estrutural com comissão, que já está acoplada a `payment_id`.

Dependências faltantes:

- `apps/admin/src/db/migrations/63_add_commission_payment_engine.sql`
- `apps/admin/src/db/migrations/64_add_commission_closure_and_payouts.sql`
- functions:
  - `generate_commission_events_for_payment(...)`
  - `reverse_commission_events_for_payment(...)`
- triggers:
  - `payments_generate_commission_events`
  - `payments_reverse_commission_events`
- tabela:
  - `public.commission_events`

Conclusão:

- as dependências reais não foram completamente identificadas.

## 5. A classificação dos arquivos obrigatórios está incompleta

Achado:

- o diagnóstico classifica corretamente como obrigatórios:
  - `apps/admin/src/app/actions/financial.ts`
  - `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

Correção necessária:

- `apps/admin/src/components/orders/financial-section.tsx` não deve permanecer apenas como provável.

Justificativa:

- a UI atual chama `deletePayment(...)`;
- a confirmação ainda fala em "excluir este pagamento";
- o modelo imutável definitivo exige que a superfície operacional pare de expor exclusão física como verbo oficial.

Conclusão:

- `financial-section.tsx` deve ser classificado como **obrigatório** ou, no mínimo, como obrigatório se a `REL-006` eliminar definitivamente o fluxo de exclusão física do pagamento.

## 6. Há migrations, procedures e triggers faltando no diagnóstico

### Migrations faltando

- migration de adaptação do motor de comissão ao novo contrato de reversão de `payments`;
- essa mudança pode ficar:
  - como migration dedicada;
  - ou incorporada à migration que substituir a semântica de `DELETE` em `payments`.

### Procedures faltando

- revisão obrigatória de `reverse_commission_events_for_payment(...)`, porque hoje sua semântica e seu audit trail assumem `payment_delete`;
- possível manutenção compatível de `generate_commission_events_for_payment(...)` para não duplicar eventos sob o novo contrato.

### Triggers faltando

- revisão obrigatória da trigger `payments_reverse_commission_events`;
- possível revisão da trigger `payments_generate_commission_events`, caso a modelagem de `payments` passe a adotar status/metadados de reversão em vez de `DELETE`.

Conclusão:

- o diagnóstico não lista todo o pacote estrutural realmente necessário.

## 7. O plano proposto ainda não fecha sozinho o `CT-015`

Achado:

- o plano fecha corretamente a maior parte do problema:
  - remove a exclusão física de `payments`;
  - preserva a reversão mínima de `receivable_receipts`;
  - ajusta leitura de `cash_flow`;
  - corrige `Valor Recebido` em `service.ts`.

Lacuna residual:

- sem tratar a dependência de comissão, a rastreabilidade completa do evento financeiro ainda fica parcial no domínio `payments`.

Conclusão:

- o plano proposto **quase** fecha o `CT-015`, mas ainda não o fecha integralmente.

## 8. O modelo imutável definitivo está bem delimitado, mas a estratégia ainda não está completa

Achado:

- o diagnóstico delimita corretamente que o modelo definitivo exige:
  - preservação do evento original;
  - evento reverso explícito;
  - leitura líquida consistente;
  - proibição de exclusão física como política oficial.

Lacuna:

- a estratégia de rastreabilidade ainda não cobre integralmente todos os efeitos derivados do `payment`, especialmente:
  - `commission_events`;
  - nomenclatura e auditoria ainda orientadas a `payment_delete`.

Conclusão:

- a delimitação conceitual está correta;
- a suficiência prática da estratégia ainda não está demonstrada.

## Riscos

## 1. Risco de autorização prematura

- autorizar a `REL-006` com o diagnóstico atual pode levar a uma implementação que fecha o eixo financeiro principal, mas quebra ou obscurece a trilha derivada de comissão.

## 2. Risco de dupla semântica operacional

- se a UI de pedido continuar oferecendo "excluir pagamento" enquanto o banco passar a operar em reversão lógica, haverá divergência entre contrato técnico e contrato operacional.

## 3. Risco de rastreabilidade parcial

- sem revisar o contrato de `commission_events`, o sistema continuará com parte da auditoria ancorada em `payment_delete`, o que enfraquece a coerência do modelo imutável definitivo.

## 4. Risco de trigger incorreta por mudança de paradigma

- se `payments` deixar de ser removido fisicamente, triggers atualmente orientadas a `AFTER DELETE` ou semântica equivalente podem deixar de refletir corretamente o novo fluxo.

## Ajustes necessários

## 1. Corrigir o mapeamento do `CT-015`

- incluir explicitamente a dependência do motor de comissão no diagnóstico;
- declarar que a aprovação integral do `CT-015` depende também da preservação da trilha derivada de `payment_id`.

## 2. Corrigir a classificação de arquivos

- promover `apps/admin/src/components/orders/financial-section.tsx` para arquivo obrigatório;
- manter `apps/admin/src/lib/financial-reporting.ts` como provável, salvo se a decisão final da `REL-006` exigir KPI líquido adicional fora de `service.ts`.

## 3. Corrigir as dependências estruturais

- incluir `commission_events` no mapa de dependências reais;
- incluir as functions e triggers de comissão conectadas a `payments`.

## 4. Corrigir o pacote de banco

- acrescentar ao menos uma revisão obrigatória das routines de comissão ligadas ao pagamento;
- deixar explícito que o novo contrato universal de reversão precisa refletir também o audit trail de comissão.

## 5. Corrigir o critério de fechamento do `CT-015`

- o caso só pode ser considerado integralmente coberto quando:
  - o evento original permanecer rastreável;
  - o evento reverso permanecer rastreável;
  - o título reabrir quando aplicável;
  - `cash_flow` e `Valor Recebido` refletirem visão líquida;
  - os efeitos derivados de comissão continuarem coerentes e auditáveis.

## Arquivos obrigatórios corrigidos

- `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/`
- revisão das migrations de comissão em nova migration complementar da `REL-006`

## Dependências corrigidas

## Dependências já corretamente identificadas no diagnóstico

- `orders`
- `payments`
- `accounts_receivable`
- `receivable_receipts`
- `cash_flow`
- `financial.ts`
- `pdv/cancel-sale/route.ts`
- `accounts-receivable/route.ts`
- `cash-flow/route.ts`
- `service.ts`

## Dependências que precisam ser adicionadas

- `public.commission_events`
- `public.generate_commission_events_for_payment(...)`
- `public.reverse_commission_events_for_payment(...)`
- trigger `payments_generate_commission_events`
- trigger `payments_reverse_commission_events`
- `apps/admin/src/db/migrations/63_add_commission_payment_engine.sql`
- `apps/admin/src/db/migrations/64_add_commission_closure_and_payouts.sql`

## Veredito final

O `DIAGNOSTICO_REL_006.md` está tecnicamente bem orientado no eixo central da história e separa corretamente `REL-004`, `REL-005` e `REL-006`.

Entretanto, a auditoria conclui que o documento **não** identifica todas as dependências reais e **não** demonstra, de forma completa, que o plano proposto fecha integralmente o `CT-015`, porque deixa de fora o acoplamento já existente entre `payments` e o motor de comissão.

Enquanto essa dependência não for incorporada ao diagnóstico e ao pacote estrutural mínimo da história, a autorização arquitetural permanece incompleta.

- **REL-006 NÃO AUTORIZADA**