# Análise de Impacto Completa - REL-001

## Objetivo

Documentar o impacto da `REL-001` antes do início da codificação, garantindo que a correção dos KPIs financeiros não quebre funcionalidades existentes, exportações, gráficos, histórias futuras ou a governança já aprovada do módulo de `Relatórios`.

## Escopo da REL-001

Conforme o backlog executivo aprovado, a `REL-001` tem como objetivo:

- corrigir `Valor Recebido`;
- corrigir `Contas a Receber`;
- corrigir `Contas em Atraso`;
- remover a ambiguidade de `Faturamento` dentro da aba financeira.

A `REL-001` não deve, neste momento:

- redesenhar a tabela financeira inteira;
- redefinir toda a governança de filtros;
- implementar a rastreabilidade financeira transacional;
- reestruturar exportações;
- corrigir toda a camada gráfica da aba financeira além do necessário para manter aderência funcional;
- antecipar tarefas de `REL-002` e `REL-003` além do acoplamento estritamente necessário.

## Base Oficial de Referência

Esta análise se apoia exclusivamente nos documentos oficiais já aprovados:

- `docs/relatorios/ESPECIFICACAO_OFICIAL.md`
- `docs/relatorios/MATRIZ_DE_VERDADE.md`
- `docs/relatorios/BACKLOG_EXECUTIVO.md`
- `docs/relatorios/PLANO_DE_CORRECAO.md`
- `docs/relatorios/CASOS_DE_TESTE.md`
- `docs/relatorios/PLANO_DE_EXECUCAO.md`
- `docs/relatorios/STATUS.md`
- `docs/relatorios/NEXT_TASK.md`

## Cadeia de Execução Atual

### Chamadas de `buildFinancialReport()`

No código atual, a chamada direta identificada de `buildFinancialReport()` é:

- `apps/admin/src/lib/reports/service.ts`
  - `runReport(runtime, request)`
  - quando `request.tab === "financial"`, delega para `buildFinancialReport(runtime, request)`.

### Cadeia indireta de execução

A função `buildFinancialReport()` é consumida indiretamente pelo seguinte fluxo:

1. `apps/admin/src/components/reports/report-page-client.tsx`
   - chama `GET /api/reports` para opções.
   - chama `POST /api/reports` para buscar dados da aba financeira.
   - chama novamente `POST /api/reports` para comparação com período anterior.

2. `apps/admin/src/app/api/reports/route.ts`
   - recebe o request.
   - cria o runtime.
   - chama `runReport(runtime, payload)`.

3. `apps/admin/src/lib/reports/service.ts`
   - `runReport()` chama `buildFinancialReport()` para a aba `financial`.

4. `apps/admin/src/components/reports/report-page-client.tsx`
   - consome `report.kpis`, `report.charts`, `report.columns`, `report.rows`.

5. `apps/admin/src/app/api/reports/export/route.ts`
   - em exportações `CSV/XLSX`, também chama `runReport()`.
   - portanto, a alteração da `REL-001` afeta exportação de forma indireta e obrigatória.

6. `apps/admin/src/components/reports/report-page-client.tsx`
   - em exportações `PDF/Impressão`, usa `loadFullReportForExport()`, que chama novamente `POST /api/reports`.
   - isso significa que a `REL-001` impacta todos os formatos de exportação, mesmo sem alterar a UI.

## Arquivos Reais Impactados no Fluxo Financeiro

### Arquivos centrais do backend

| Caminho | Responsabilidade | Papel na REL-001 |
|---|---|---|
| `apps/admin/src/lib/reports/service.ts` | Núcleo de geração do relatório | Arquivo principal da correção |
| `apps/admin/src/lib/reports/contracts.ts` | Tipos e contratos do payload | Pode precisar ajuste de contrato, se a correção exigir mudança semântica explícita |
| `apps/admin/src/lib/reports/utils.ts` | Agregações, ordenação, utilitários analíticos | Pode ser tangenciado se a correção tocar na agregação mínima dos gráficos financeiros |
| `apps/admin/src/app/api/reports/route.ts` | Rota principal de geração do relatório | Consome o resultado da REL-001, mas não deve mudar salvo necessidade contratual |
| `apps/admin/src/app/api/reports/export/route.ts` | Exportação `CSV/XLSX` | Consome indiretamente o resultado da REL-001 |

### Arquivos centrais do frontend

| Caminho | Responsabilidade | Papel na REL-001 |
|---|---|---|
| `apps/admin/src/components/reports/report-page-client.tsx` | Carrega dados, monta request, renderiza KPIs, gráficos e tabela | Arquivo provavelmente alterado para labels/cards e para refletir a nova semântica dos KPIs |
| `apps/admin/src/components/reports/report-charts.tsx` | Exibe gráficos retornados pelo backend | Impactado indiretamente pelo novo payload financeiro |
| `apps/admin/src/components/reports/report-data-table.tsx` | Exibe tabela analítica e aciona exportação | Impactado indiretamente pelo novo payload e pela nova semântica da aba |
| `apps/admin/src/app/dashboard/reports/page.tsx` | Entrada da página de relatórios | Não deve precisar mudança |

### Arquivos estruturais da origem financeira

| Caminho | Responsabilidade | Papel na REL-001 |
|---|---|---|
| `apps/admin/src/db/migrations/68_add_accounts_receivable_manual.sql` | Estrutura de `accounts_receivable`, `receivable_receipts` e trigger de sincronização | Base de entendimento, não deve ser alterado na REL-001 |
| `apps/admin/src/db/migrations/69_update_cash_flow_origin_receber.sql` | Ajuste de origem `RECEBER` em `cash_flow` | Base de entendimento, não deve ser alterado na REL-001 |
| `apps/admin/src/db/migrations/70_make_delete_payment_compatible_with_immutable_cash_flow.sql` | Reversão compensatória de pagamento com fluxo imutável | Base de entendimento, não deve ser alterado na REL-001 |

## Funções e Pontos Técnicos Impactados

### Funções diretamente impactadas

| Arquivo | Função | Impacto |
|---|---|---|
| `service.ts` | `buildFinancialReport()` | Impacto direto máximo; é onde os KPIs financeiros são calculados hoje |
| `service.ts` | `runReport()` | Impacto indireto; continua sendo o despachante da aba `financial` |
| `report-page-client.tsx` | `loadReport()` | Impacto indireto; o request permanece, mas o consumo do payload muda semanticamente |
| `report-page-client.tsx` | `loadFullReportForExport()` | Impacto indireto; exportações usam o mesmo payload corrigido |
| `report-page-client.tsx` | `exportReport()` | Impacto indireto; todos os formatos passam a refletir os novos KPIs |

### Funções possivelmente tangenciadas

| Arquivo | Função | Motivo |
|---|---|---|
| `service.ts` | `loadOptions()` | Pode precisar revisão futura por coerência de filtros financeiros, mas isso é mais aderente à `REL-003` |
| `utils.ts` | `buildSeriesMap()` | Pode ser afetada se a REL-001 exigir corrigir imediatamente a coerência mínima entre KPI e gráfico |
| `report-page-client.tsx` | geração de `kpiCards` | Pode precisar ajuste de apresentação para labels oficiais |

## Componentes que Consomem os KPIs Financeiros

### Consumo direto

- `apps/admin/src/components/reports/report-page-client.tsx`
  - consome `report.kpis`;
  - monta `kpiCards`;
  - exibe os cards da aba financeira;
  - usa `previousReport.kpis` para variação/comparação.

### Consumo indireto

- `apps/admin/src/components/reports/report-page-client.tsx`
  - `drawPdfKpis()` na exportação PDF utiliza `report.kpis`.
- qualquer fluxo de exportação que reutiliza `report.kpis` será impactado.

## Gráficos Afetados

Os gráficos financeiros afetados por alteração do payload da `REL-001` são:

1. `Evolução do faturamento`
2. `Recebimentos por período`
3. `Distribuição por forma de pagamento`

### Nível de impacto por gráfico

| Gráfico | Impacto da REL-001 | Observação |
|---|---|---|
| `Evolução do faturamento` | Alto | O nome e a base atual não aderem ao universo financeiro correto |
| `Recebimentos por período` | Alto | Deve continuar coerente com o KPI `Valor Recebido` |
| `Distribuição por forma de pagamento` | Médio/Alto | Depende diretamente da fonte correta de recebido |

### Dependência com REL-002

- A `REL-002` trata explicitamente da correção dos gráficos financeiros e da ordenação temporal.
- A `REL-001` não deve “consumir” a `REL-002`, mas qualquer mudança em KPI que altere a base dos gráficos precisa manter consistência mínima.
- Estratégia segura:
  - `REL-001` corrige o universo e os números base.
  - `REL-002` consolida a semântica visual, títulos e agregações temporais finais.

## Exportações Afetadas

### Exportações diretamente afetadas

| Formato | Caminho técnico | Impacto |
|---|---|---|
| CSV | `apps/admin/src/app/api/reports/export/route.ts` | Alto |
| XLSX | `apps/admin/src/app/api/reports/export/route.ts` | Alto |
| PDF | `apps/admin/src/components/reports/report-page-client.tsx` via `loadFullReportForExport()` | Alto |
| Impressão | `apps/admin/src/components/reports/report-page-client.tsx` via `loadFullReportForExport()` | Alto |

### Motivo do impacto

- todas as exportações reutilizam o mesmo relatório financeiro gerado por `runReport()` / `buildFinancialReport()`;
- qualquer mudança na semântica dos KPIs altera diretamente:
  - cabeçalho de indicadores;
  - tabela resumida;
  - expectativa de fechamento entre tela e arquivo.

## Testes CT Impactados

### Impacto direto

Conforme backlog e plano aprovados, os testes diretamente obrigatórios da `REL-001` são:

- `CT-001`
- `CT-002`
- `CT-005`
- `CT-006`
- `CT-008`
- `CT-009`
- `CT-015`

### Impacto indireto

Também ficam indiretamente sensíveis após a `REL-001`:

- `CT-007`
  - porque a distribuição por forma de pagamento depende do universo correto de recebido.
- `CT-010`
  - porque o entendimento de `Fluxo de Caixa` versus `Recebido` precisa continuar coerente.
- `CT-014`
  - porque exportações e paridade tela-arquivo passam a refletir o novo payload.

### Dependência com REL-002 e REL-003

| História futura | Dependência gerada pela REL-001 | Risco se REL-001 for mal implementada |
|---|---|---|
| REL-002 | usa o payload financeiro estabilizado como base dos gráficos | gráficos podem ser corrigidos sobre números errados |
| REL-003 | depende da nova semântica dos KPIs para ajustar filtros e data de corte | filtros podem ser implementados sobre uma base analítica inconsistente |

## Possíveis Regressões

### Regressões funcionais

1. `Valor Recebido` continuar igual a `Faturamento total` por reutilização de lógica antiga.
2. `Contas a Receber` perder títulos futuros ainda abertos se a lógica de vencimento não for isolada corretamente.
3. `Contas em Atraso` continuar usando `today` em algum fluxo secundário.
4. comparação com período anterior passar a comparar universos diferentes se a correção não for aplicada igualmente ao request comparativo.
5. PDF/CSV/XLSX/Impressão divergirem da tela se algum caminho de exportação permanecer acoplado à lógica antiga.

### Regressões de UI

1. cards financeiros exibirem labels antigos com números novos.
2. legendas e títulos dos gráficos ficarem semanticamente incoerentes.
3. comparação visual de tendência ficar quebrada temporariamente até a `REL-002`.

### Regressões de governança

1. correção da `REL-001` invadir o escopo da `REL-002`.
2. correção da `REL-001` invadir o escopo da `REL-003`.
3. alteração indevida de migrations, rotas transacionais ou fluxos de banco que pertencem à Sprint 2.

## Arquivos que Precisarão ser Modificados

### Modificação obrigatória

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

### Modificação provável

- `apps/admin/src/components/reports/report-page-client.tsx`

### Modificação possível, mas somente se estritamente necessária

- `apps/admin/src/lib/reports/contracts.ts`
- `apps/admin/src/lib/reports/utils.ts`
- `apps/admin/src/components/reports/report-charts.tsx`

## Arquivos que Não Devem ser Modificados na REL-001

### Não devem ser alterados por escopo

- `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/70_make_delete_payment_compatible_with_immutable_cash_flow.sql`
- `apps/admin/src/app/api/accounts-receivable/[id]/receive/route.ts`
- `apps/admin/src/app/api/pdv/cancel-sale/route.ts`
- `apps/admin/src/app/actions/financial.ts`
- `apps/admin/src/app/dashboard/reports/page.tsx`

### Motivo

- esses arquivos pertencem à base transacional, rastreabilidade financeira ou entrada da página;
- alterações neles antecipariam escopo de `REL-004`, `REL-005` e `REL-006`;
- a `REL-001` deve ser resolvida primeiro na camada analítica do relatório.

## Estratégia de Implementação Segura

### Estratégia recomendada

1. Corrigir primeiro a semântica dos KPIs apenas no backend analítico.
2. Só depois ajustar labels e consumo no frontend.
3. Não alterar filtros além do que for indispensável para evitar incoerência evidente.
4. Não mexer em triggers, procedures, migrations ou rotas transacionais nesta história.
5. Garantir que o request normal e o request de comparação com período anterior usem exatamente a mesma regra analítica corrigida.
6. Validar exportações usando o mesmo serviço, sem criar caminhos paralelos.

### Princípio operacional

- primeiro corrigir o número;
- depois corrigir o nome;
- depois validar exportação;
- só então avançar para a camada gráfica mais ampla em `REL-002`.

## Ordem Exata de Implementação Recomendada

1. Revisar e isolar a lógica de KPI financeiro em `buildFinancialReport()`.
2. Corrigir a origem e fórmula de:
   - `Valor Recebido`
   - `Contas a Receber`
   - `Contas em Atraso`
   - `Fluxo de Caixa Líquido` ou estrutura equivalente aprovada para a aba
3. Garantir que o payload `ReportResponse.kpis` reflita a nova semântica.
4. Validar o mesmo comportamento no request de comparação com período anterior.
5. Ajustar `report-page-client.tsx` para exibir labels oficiais e não quebrar os cards.
6. Validar exportação `CSV/XLSX` via `/api/reports/export`.
7. Validar exportação `PDF/Impressão` via `loadFullReportForExport()`.
8. Executar os casos diretos da história.
9. Executar os casos indiretos sensíveis.
10. Congelar a base para início da `REL-002`.

## Critério Seguro para Início da Codificação

A codificação da `REL-001` só deve começar quando os seguintes critérios estiverem explícitos e aceitos:

- definição final do conjunto de KPIs que permanecerão na aba `Financeiro` para esta história;
- decisão formal sobre o tratamento de `Valor Recebido` na visão oficial aprovada;
- confirmação de que `REL-001` não vai alterar banco, trigger, procedure ou rotas transacionais;
- concordância de que qualquer ajuste visual mais amplo de gráfico ficará para `REL-002`;
- concordância de que qualquer saneamento de filtro semântico mais profundo ficará para `REL-003`;
- casos de teste diretos da `REL-001` preparados:
  - `CT-001`
  - `CT-002`
  - `CT-005`
  - `CT-006`
  - `CT-008`
  - `CT-009`
  - `CT-015`

## Resumo Executivo

### Arquivos afetados

- Obrigatório:
  - `apps/admin/src/lib/reports/service.ts`
- Provável:
  - `apps/admin/src/components/reports/report-page-client.tsx`
- Possíveis, se estritamente necessários:
  - `apps/admin/src/lib/reports/contracts.ts`
  - `apps/admin/src/lib/reports/utils.ts`
  - `apps/admin/src/components/reports/report-charts.tsx`

### Risco de regressão

- **Alto**, porque a `REL-001` altera o núcleo semântico do financeiro e afeta:
  - cards;
  - gráficos;
  - comparação com período anterior;
  - exportações;
  - base para `REL-002` e `REL-003`.

### Estratégia recomendada

- corrigir primeiro o backend analítico;
- ajustar frontend apenas para refletir a nova verdade;
- não antecipar banco nem trilha transacional;
- validar tela e exportações com a mesma base;
- congelar o resultado como base oficial da Sprint 1.

### Ordem exata de implementação

1. `service.ts`
2. `report-page-client.tsx`
3. validação de exportação
4. execução dos CTs diretos
5. execução dos CTs indiretos

### Critério seguro para início da codificação

- documentação oficial carregada;
- escopo da `REL-001` mantido sem invadir `REL-002` e `REL-003`;
- massa de teste preparada;
- consenso funcional sobre os KPIs financeiros finais desta história;
- autorização explícita para iniciar a alteração do backend analítico.