# Decisão de Escopo - CT-015

## Objetivo

Determinar formalmente se o `CT-015` pertence ao escopo da `REL-001` ou se deve ser reclassificado para uma história futura, sem alterar código, banco ou documentação existente.

## 1. Definição Completa do CT-015

### Cenário

Conforme [CASOS_DE_TESTE.md](file:///c:/Users/Natan/Downloads/ktalogu-main/docs/relatorios/CASOS_DE_TESTE.md#L23-L23):

- recebimento de `R$ 700` já refletido em caixa;
- exclusão física não permitida;
- o sistema gera reversão compensatória.

### Objetivo

Garantir que, em ambiente com fluxo financeiro imutável:

- o relatório financeiro mostre o valor líquido correto;
- exista trilha auditável de reversão;
- a carteira/título reflita o saldo reaberto quando aplicável.

### Regra de negócio validada

Pelos documentos oficiais:

- `Valor Recebido` deve representar liquidação financeira válida, com tratamento correto de estornos quando a visão for líquida, conforme [ESPECIFICACAO_OFICIAL.md](file:///c:/Users/Natan/Downloads/ktalogu-main/docs/relatorios/ESPECIFICACAO_OFICIAL.md#L284-L296) e [MATRIZ_DE_VERDADE.md](file:///c:/Users/Natan/Downloads/ktalogu-main/docs/relatorios/MATRIZ_DE_VERDADE.md#L45-L55).
- `Contas a Receber` deve reabrir saldo quando houver estorno de recebimento, conforme [ESPECIFICACAO_OFICIAL.md](file:///c:/Users/Natan/Downloads/ktalogu-main/docs/relatorios/ESPECIFICACAO_OFICIAL.md#L298-L309) e [MATRIZ_DE_VERDADE.md](file:///c:/Users/Natan/Downloads/ktalogu-main/docs/relatorios/MATRIZ_DE_VERDADE.md#L56-L67).
- `Fluxo de Caixa` deve registrar reversão formal e rastreável, conforme [ESPECIFICACAO_OFICIAL.md](file:///c:/Users/Natan/Downloads/ktalogu-main/docs/relatorios/ESPECIFICACAO_OFICIAL.md#L324-L334) e [MATRIZ_DE_VERDADE.md](file:///c:/Users/Natan/Downloads/ktalogu-main/docs/relatorios/MATRIZ_DE_VERDADE.md#L80-L89).

## 2. Evidência Exata da Reprovação

### Resultado esperado

Conforme [CASOS_DE_TESTE.md](file:///c:/Users/Natan/Downloads/ktalogu-main/docs/relatorios/CASOS_DE_TESTE.md#L23-L23):

- relatório financeiro mostra valor líquido correto;
- trilha de reversão existe;
- carteira/título refletem o saldo reaberto quando aplicável.

### Resultado obtido

Conforme [VALIDACAO_FINAL_REL_001.md](file:///c:/Users/Natan/Downloads/ktalogu-main/docs/relatorios/VALIDACAO_FINAL_REL_001.md#L210-L241):

- `Fluxo de Caixa Liquido` **pode** refletir corretamente o efeito líquido se existir reversão compensatória em `cash_flow`;
- `Valor Recebido` continua sendo calculado por `receivable_receipts` do período, sem lógica explícita adicional de estorno líquido;
- a trilha de reversão e a consistência transacional completa permanecem dependentes das histórias de rastreabilidade financeira da Sprint 2.

### Diferença encontrada

| Item | Esperado | Obtido | Diferença |
|---|---|---|---|
| Valor líquido do recebido | Deve refletir recebimento líquido após reversão | O KPI usa `receivable_receipts` e não possui reversão líquida explícita | O relatório pode manter recebido bruto sem refletir estorno |
| Trilha de reversão | Deve existir vínculo auditável entre evento original e reverso | Só existe fallback parcial em alguns fluxos de `cash_flow` | A trilha não é universal nem formalizada para todos os recebimentos |
| Reabertura de carteira | O título deve voltar ao saldo aberto quando aplicável | Isso depende de exclusão/estorno de `receivable_receipts` com trigger subsequente | Não existe fluxo completo exposto e padronizado para esse cenário no módulo auditado |

## 3. Causa Raiz

## Classificação da causa

| Tipo | Se aplica? | Justificativa |
|---|---|---|
| Erro na implementação da REL-001 | Parcialmente | A `REL-001` não implementa lógica de recebido líquido por estorno, mas isso já excede seu escopo autorizado |
| Erro pré-existente | Sim | O sistema já não possuía fluxo padronizado e completo de reversão de recebimentos para suportar o caso |
| Limitação estrutural | Sim | O cenário depende de persistência e reconciliação entre múltiplas tabelas e eventos |
| Dependência transacional | Sim | O caso exige mudança no fluxo operacional de baixa, estorno e reversão |
| Dependência de banco | Sim | Há dependência de triggers/procedures e do comportamento do banco na exclusão/reversão |
| Dependência de rastreabilidade financeira | Sim | O critério central do caso é justamente a rastreabilidade auditável da reversão |

### Causa raiz consolidada

O `CT-015` reprova **não** porque a `REL-001` tenha deixado um ajuste visual ou meramente analítico pendente, mas porque o cenário exige uma cadeia transacional completa entre:

- `receivable_receipts`
- `accounts_receivable`
- `cash_flow`
- regras de estorno/reversão
- trilha auditável do evento original e do evento reverso

Essa cadeia hoje não está integralmente implementada nem governada no escopo da `REL-001`.

## 4. Arquivos que Precisariam ser Alterados para Aprovar o CT-015

### Arquivos analíticos

- [service.ts](file:///c:/Users/Natan/Downloads/ktalogu-main/apps/admin/src/lib/reports/service.ts)
  - para refletir corretamente recebido líquido e carteira após reversão, se a base transacional existir.

### Arquivos de fluxo financeiro

- [financial.ts](file:///c:/Users/Natan/Downloads/ktalogu-main/apps/admin/src/app/actions/financial.ts)
  - contém `registerPayment()` e `deletePayment()`, com impacto direto em pagamentos de pedidos.

- [receive route.ts](file:///c:/Users/Natan/Downloads/ktalogu-main/apps/admin/src/app/api/accounts-receivable/[id]/receive/route.ts)
  - registra `receivable_receipts` e insere `cash_flow`.
  - hoje existe fluxo de inclusão, mas não um fluxo formal equivalente de reversão auditável exposto neste caminho.

- [cancel-sale route.ts](file:///c:/Users/Natan/Downloads/ktalogu-main/apps/admin/src/app/api/pdv/cancel-sale/route.ts)
  - já implementa parte de reversão para pagamentos de PDV e fallback compensatório em `cash_flow`.
  - evidencia que o domínio de reversão pertence ao fluxo transacional, não ao builder de relatórios.

### Arquivos de banco / procedures / triggers

- [68_add_accounts_receivable_manual.sql](file:///c:/Users/Natan/Downloads/ktalogu-main/apps/admin/src/db/migrations/68_add_accounts_receivable_manual.sql#L39-L95)
  - trigger `sync_accounts_receivable_status()`
  - controla o recalculo de `paid_amount` e `status` ao inserir/atualizar/deletar `receivable_receipts`.

- [70_make_delete_payment_compatible_with_immutable_cash_flow.sql](file:///c:/Users/Natan/Downloads/ktalogu-main/apps/admin/src/db/migrations/70_make_delete_payment_compatible_with_immutable_cash_flow.sql#L1-L132)
  - procedure `delete_payment_with_cleanup()`
  - já trata reversão compensatória para pagamentos ligados a pedidos.

### Observação importante

Para aprovar integralmente o `CT-015`, não basta alterar apenas:

- `service.ts`

O cenário exige modificar a camada transacional e possivelmente a camada de banco.

## 5. Tipo de Correção Necessária

| Tipo de alteração | Necessária? | Justificativa |
|---|---|---|
| Alteração apenas em relatórios | Não | O relatório sozinho não consegue inventar a trilha de reversão nem reabrir saldo corretamente |
| Alteração em fluxo financeiro | Sim | É necessário controlar reversão de recebimentos/pagamentos de forma transacional |
| Alteração em procedures | Sim, muito provável | O padrão atual de reversão já usa procedure para pagamentos (`delete_payment_with_cleanup`) |
| Alteração em triggers | Sim, potencialmente | O recálculo de carteira depende de `sync_accounts_receivable_status()` e sua interação com exclusão/estorno |
| Alteração em banco | Sim | O comportamento auditável de reversão depende da camada persistida |
| Alteração em regras transacionais | Sim | O caso é primariamente transacional, não apenas analítico |

## 6. Classificação do CT-015

### Categoria escolhida

- **B) Deve ser movido para Sprint 2**

### Justificativa formal

O `CT-015` está mapeado não só em `REL-001`, mas também explicitamente em:

- `REL-004`
- `REL-005`
- `REL-006`

Conforme [BACKLOG_EXECUTIVO.md](file:///c:/Users/Natan/Downloads/ktalogu-main/docs/relatorios/BACKLOG_EXECUTIVO.md#L109-L114) e [PLANO_DE_EXECUCAO.md](file:///c:/Users/Natan/Downloads/ktalogu-main/docs/relatorios/PLANO_DE_EXECUCAO.md#L112-L126).

Além disso, a própria Fase 2 do [PLANO_DE_CORRECAO.md](file:///c:/Users/Natan/Downloads/ktalogu-main/docs/relatorios/PLANO_DE_CORRECAO.md#L9-L10) foi definida para:

- fortalecer a rastreabilidade financeira oficial;
- garantir recebimentos, estornos e reversões auditáveis;
- consolidar a trilha entre:
  - `payments`
  - `receivable_receipts`
  - `accounts_receivable`
  - `cash_flow`

Logo, o `CT-015` é tecnicamente e funcionalmente compatível com Sprint 2, não com o fechamento estrito da `REL-001`.

## 7. Recomendação Formal

### Recomendação

- **Reclassificar CT-015 e liberar encerramento da REL-001**

### Fundamentação

1. A `REL-001` tinha como foco:
   - `Valor Recebido`
   - `Contas a Receber`
   - `Contas em Atraso`
   - remoção da ambiguidade de `Faturamento` na aba financeira

2. O ponto remanescente de `Contas a Receber` já foi corrigido em `REL-001A`.

3. O `CT-015` depende de:
   - rastreabilidade financeira auditável;
   - regras transacionais de reversão;
   - possíveis ajustes em procedures, triggers e fluxo financeiro;
   - escopo explicitamente descrito nas histórias da Sprint 2.

4. Manter o `CT-015` como bloqueio formal da `REL-001` mistura:
   - correção analítica de KPI
   - com governança transacional de reversão financeira

5. Essa mistura contradiz a própria separação de fases e epics já aprovados no projeto.

## Conclusão Executiva

- O `CT-015` **não pertence mais ao encerramento da `REL-001`**.
- O `CT-015` deve ser **formalmente reclassificado para Sprint 2**, cobrindo as histórias:
  - `REL-004`
  - `REL-005`
  - `REL-006`
- Portanto, a recomendação executiva é:
  - **reclassificar o CT-015**
  - **remover o bloqueio formal da REL-001**
  - **liberar o encerramento da REL-001**
  - **sem iniciar automaticamente a REL-002 sem nova autorização**