# Bloqueio Arquitetural - REL-006

## Objetivo

Registrar formalmente o bloqueio encontrado antes do início da implementação da `REL-006`, conforme instrução de interromper a execução caso surja necessidade de alterar algo fora do escopo permitido.

## Documentos lidos integralmente antes do bloqueio

- `docs/relatorios/DIAGNOSTICO_REL_006.md`
- `docs/relatorios/AUDITORIA_DIAGNOSTICO_REL_006.md`
- `docs/relatorios/DECISAO_ARQUITETURAL_REL_006.md`
- `docs/relatorios/STATUS.md`
- `docs/relatorios/DECISOES.md`
- `docs/relatorios/VALIDACAO_REL_004.md`
- `docs/relatorios/VALIDACAO_REL_005.md`

## Escopo mínimo que precisaria ser alterado

Antes de implementar, o pacote mínimo coerente com `DECISAO_ARQUITETURAL_REL_006.md` é:

### Banco / migrations

- novas migrations da `REL-006` em `apps/admin/src/db/migrations/`
  - para reversão lógica em `payments`
  - para vínculo estrutural original/reverso em `cash_flow`
  - para adaptação do motor de comissão

### APIs e ações

- `apps/admin/src/app/actions/financial.ts`
  - para substituir o consumo de exclusão física por reversão lógica oficial

- `apps/admin/src/app/api/pdv/cancel-sale/route.ts`
  - para parar de apagar trilha financeira oficial e consumir a nova rotina universal

- `apps/admin/src/app/api/accounts-receivable/route.ts`
  - para harmonizar a reversão mínima de recibo com o contrato universal

- `apps/admin/src/app/api/cash-flow/route.ts`
  - para ler reversões por vínculo estrutural, e não por convenção textual

### Componente operacional

- `apps/admin/src/components/orders/financial-section.tsx`
  - para deixar de expor a ação operacional como "excluir pagamento"

### Camada analítica

- `apps/admin/src/lib/reports/service.ts`
  - para corrigir o cálculo de `Valor Recebido`
  - para impedir que o relatório continue somando `receivable_receipts` brutos
  - para refletir o líquido oficial exigido pelo `CT-015`

## Bloqueio encontrado

Existe conflito entre:

### 1. Escopo aprovado na decisão arquitetural

A `DECISAO_ARQUITETURAL_REL_006.md` determina explicitamente que a história deve ajustar:

- `apps/admin/src/lib/reports/service.ts`
- a leitura do `cash_flow`
- a superfície operacional do pedido

para concluir o `CT-015`.

### 2. Restrição adicional da ordem de implementação

A instrução de implementação recebida também determina:

- não alterar relatórios da Sprint 1;
- não alterar regras de KPI;
- não alterar gráficos;
- não alterar exportações.

## Evidência objetiva do conflito

O fechamento do `CT-015` depende de corrigir a visão líquida de `Valor Recebido`, mas hoje:

- `apps/admin/src/lib/reports/service.ts` busca `receivable_receipts` diretamente;
- `totalReceived` é calculado por soma bruta dos recibos do período;
- o KPI `Valor Recebido` usa esse valor bruto;
- `apps/admin/src/app/api/reports/route.ts` e `apps/admin/src/app/api/reports/export/route.ts` consomem diretamente `runReport()` de `service.ts`.

Logo:

- sem alterar `service.ts`, o `CT-015` não fecha integralmente;
- ao alterar `service.ts`, a implementação necessariamente toca:
  - relatório da Sprint 1
  - KPI
  - exportação

o que entra em conflito com a restrição operacional da ordem atual.

## Conclusão do bloqueio

Neste estado, a implementação não pode prosseguir sem violar uma das duas condições abaixo:

- ou respeita a `DECISAO_ARQUITETURAL_REL_006.md` e altera `service.ts` para fechar o `CT-015`;
- ou respeita literalmente a restrição adicional e não toca relatórios/KPIs/exportações, mas então não conclui o `CT-015`.

Portanto:

- existe bloqueio arquitetural de escopo;
- a implementação foi interrompida antes de qualquer alteração de código;
- nenhum arquivo de implementação da `REL-006` foi modificado.

## Recomendação para destravar

Escolher formalmente uma destas direções:

### Opção A

Autorizar explicitamente a exceção controlada em:

- `apps/admin/src/lib/reports/service.ts`

com o entendimento de que:

- isso altera o KPI `Valor Recebido`;
- isso afeta a mesma verdade usada por tela e exportação;
- essa alteração fica restrita exclusivamente ao fechamento do `CT-015`.

### Opção B

Manter proibida qualquer alteração na camada analítica da Sprint 1 e:

- reclassificar o fechamento analítico do `CT-015` para uma história posterior;
- executar na `REL-006` apenas a parte transacional e de rastreabilidade.

## Estado final

- **Implementação da REL-006 interrompida por bloqueio arquitetural**