# Diagnóstico Técnico - REL-002

## Objetivo

Documentar a análise completa da `REL-002`, sem iniciar implementação, para corrigir os gráficos financeiros e a ordenação temporal do módulo de `Relatórios`, com base exclusiva em:

- `ESPECIFICACAO_OFICIAL.md`
- `MATRIZ_DE_VERDADE.md`
- `BACKLOG_EXECUTIVO.md`
- `PLANO_DE_CORRECAO.md`
- `CASOS_DE_TESTE.md`
- `PLANO_DE_EXECUCAO.md`
- `STATUS.md`
- `NEXT_TASK.md`
- `DECISOES.md`
- `CHANGELOG.md`
- `ENCERRAMENTO_REL_001.md`

## Escopo da REL-002

Conforme [BACKLOG_EXECUTIVO.md](file:///c:/Users/Natan/Downloads/ktalogu-main/docs/relatorios/BACKLOG_EXECUTIVO.md#L83-L85), a `REL-002` tem como objetivo:

- corrigir gráficos financeiros;
- corrigir ordenação temporal;
- garantir que os gráficos financeiros reflitam a semântica oficial;
- alinhar gráficos com os KPIs da aba `Financeiro`.

Conforme [PLANO_DE_CORRECAO.md](file:///c:/Users/Natan/Downloads/ktalogu-main/docs/relatorios/PLANO_DE_CORRECAO.md#L7-L10), a `REL-002` permanece dentro da camada de relatórios e **não exige alteração de banco**.

## Arquivos Impactados

### Arquivos analisados

- `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`
- `docs/relatorios/DECISOES.md`
- `docs/relatorios/CHANGELOG.md`
- `docs/relatorios/ENCERRAMENTO_REL_001.md`
- `apps/admin/src/lib/reports/service.ts`
- `apps/admin/src/lib/reports/utils.ts`
- `apps/admin/src/lib/reports/contracts.ts`
- `apps/admin/src/components/reports/report-charts.tsx`
- `apps/admin/src/components/reports/report-page-client.tsx`
- `apps/admin/src/components/reports/report-data-table.tsx`
- `apps/admin/src/app/api/reports/route.ts`
- `apps/admin/src/app/api/reports/export/route.ts`

### Arquivos que precisarão ser alterados na REL-002

- `apps/admin/src/lib/reports/service.ts`
  - núcleo dos gráficos financeiros atuais;
  - origem, agregação, títulos e ids dos charts.

- `apps/admin/src/lib/reports/utils.ts`
  - hoje a ordenação temporal usa `label` humanizado;
  - precisará preservar chave cronológica real.

- `apps/admin/src/lib/reports/contracts.ts`
  - alteração potencial, caso seja necessário enriquecer o contrato do gráfico com chave temporal bruta ou metadado de série;
  - não é obrigatória, mas é um arquivo potencialmente impactado.

- `apps/admin/src/components/reports/report-charts.tsx`
  - alteração provável para acomodar o novo conjunto de gráficos da aba `Financeiro`;
  - especialmente se passar a existir gráfico `compare` para fluxo de caixa ou gráfico adicional de carteira por status.

- `apps/admin/src/components/reports/report-page-client.tsx`
  - impacto indireto em PDF/Print, porque os gráficos renderizados e exportados em PDF vêm de `report.charts`;
  - pode precisar de ajuste mínimo se a quantidade, ordem ou ids dos gráficos mudar.

### Arquivos que não devem ser alterados na REL-002

- `apps/admin/src/db/migrations/*`
- `apps/admin/src/app/actions/financial.ts`
- `apps/admin/src/app/api/accounts-receivable/[id]/receive/route.ts`
- `apps/admin/src/app/api/pdv/cancel-sale/route.ts`
- `docs/relatorios/STATUS.md`
- `docs/relatorios/CHANGELOG.md`
- `docs/relatorios/DECISOES.md`

Esses arquivos pertencem a:

- rastreabilidade financeira transacional;
- Sprint 2;
- governança documental fora do escopo desta análise.

## Funções Impactadas

### Backend

- `buildFinancialReport()` em [service.ts](file:///c:/Users/Natan/Downloads/ktalogu-main/apps/admin/src/lib/reports/service.ts#L618-L970)
  - monta os 3 gráficos financeiros atuais;
  - hoje é a principal fonte das divergências da `REL-002`.

- `runReport()` em [service.ts](file:///c:/Users/Natan/Downloads/ktalogu-main/apps/admin/src/lib/reports/service.ts#L1518-L1519)
  - despacha `financial` para `buildFinancialReport()`;
  - não precisa de mudança conceitual, mas entra no fluxo de impacto.

- `buildSeriesMap()` em [utils.ts](file:///c:/Users/Natan/Downloads/ktalogu-main/apps/admin/src/lib/reports/utils.ts#L172-L181)
  - agrega séries e ordena por `label`;
  - hoje é a principal causa da ordenação temporal incorreta.

- `takeTopSeries()` em [utils.ts](file:///c:/Users/Natan/Downloads/ktalogu-main/apps/admin/src/lib/reports/utils.ts#L183-L186)
  - relevante para o donut de forma de pagamento.

- `monthLabel()` em [utils.ts](file:///c:/Users/Natan/Downloads/ktalogu-main/apps/admin/src/lib/reports/utils.ts#L222-L227)
  - transforma a chave `YYYY-MM` em label amigável;
  - hoje é usada cedo demais, antes da ordenação definitiva.

### Frontend

- `ReportCharts()` em [report-charts.tsx](file:///c:/Users/Natan/Downloads/ktalogu-main/apps/admin/src/components/reports/report-charts.tsx#L478-L519)
  - renderiza todos os gráficos retornados pelo backend.

- `ChartBody()` em [report-charts.tsx](file:///c:/Users/Natan/Downloads/ktalogu-main/apps/admin/src/components/reports/report-charts.tsx#L470-L476)
  - seleciona o componente visual por tipo.

- `renderPdfCharts()` em [report-page-client.tsx](file:///c:/Users/Natan/Downloads/ktalogu-main/apps/admin/src/components/reports/report-page-client.tsx#L474-L511)
  - exporta para PDF os mesmos `report.charts`;
  - se o payload gráfico estiver semanticamente errado, o PDF também estará.

- `loadReport()` em [report-page-client.tsx](file:///c:/Users/Natan/Downloads/ktalogu-main/apps/admin/src/components/reports/report-page-client.tsx#L589-L635)
  - carrega `report` e `previousReport`;
  - qualquer alteração de ids/títulos/quantidade de gráficos impacta a comparação entre períodos.

## Gráficos Impactados

### Gráficos atuais da aba Financeiro

Conforme [service.ts](file:///c:/Users/Natan/Downloads/ktalogu-main/apps/admin/src/lib/reports/service.ts#L905-L942), hoje a aba `Financeiro` retorna:

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

### Gráficos exigidos pela especificação oficial

Conforme [ESPECIFICACAO_OFICIAL.md](file:///c:/Users/Natan/Downloads/ktalogu-main/docs/relatorios/ESPECIFICACAO_OFICIAL.md#L82-L87), a aba `Financeiro` deve exibir:

1. `Recebimentos por período`
2. `Fluxo de caixa por período`
3. `Distribuição do recebido por forma de pagamento`
4. `Carteira por status`

## Origem de Dados de Cada Gráfico Atual

| Gráfico atual | Origem atual | Agregação atual | Ordenação atual | Situação |
|---|---|---|---|---|
| `Evolução do faturamento` | `cash_flow` filtrado por `type === IN` | soma de `amount` por `monthLabel(periodKey(entry.date))` | alfabética por `label` em `buildSeriesMap()` | Incorreto semanticamente |
| `Recebimentos por período` | `cash_flow` filtrado por `type === IN` | soma de `amount` por `monthLabel(periodKey(entry.date))` | alfabética por `label` em `buildSeriesMap()` | Incorreto e duplicado |
| `Distribuição por forma de pagamento` | `cash_flow` filtrado por `type === IN` | soma de `amount` por `paymentMethod` | decrescente por valor após `takeTopSeries()` | Incorreto semanticamente |

## Origem de Dados Correta por Gráfico

| Gráfico oficial | Fonte oficial | Agregação correta | Ordenação correta |
|---|---|---|---|
| `Recebimentos por período` | `receivable_receipts` | soma de `amount` por período de `received_at` | cronológica ascendente |
| `Fluxo de caixa por período` | `cash_flow` | soma de `IN`, soma de `OUT` e saldo líquido por período | cronológica ascendente |
| `Distribuição do recebido por forma de pagamento` | `receivable_receipts` | soma de `amount` por `payment_method` | decrescente por valor |
| `Carteira por status` | `accounts_receivable` | soma de saldo aberto por status oficial | ordem fixa por status |

## Divergências Encontradas

### 1. Gráfico de faturamento dentro da aba Financeiro

#### Regra atual

- existe um gráfico chamado `Evolução do faturamento`;
- ele usa `cash_flow IN`.

#### Regra correta

- a aba `Financeiro` não deve exibir faturamento comercial nesse bloco;
- o gráfico correto esperado é `Fluxo de caixa por período`.

#### Impacto

- mistura universo comercial com universo financeiro;
- repete erro conceitual já corrigido parcialmente nos KPIs da `REL-001`.

#### Risco

- alto

### 2. Duplicidade de universo entre `Evolução do faturamento` e `Recebimentos por período`

#### Regra atual

- ambos os gráficos usam exatamente a mesma base:
  - `filtered.filter((entry) => entry.type === "IN")`
- ambos agregam por mês da mesma forma.

#### Regra correta

- `Recebimentos por período` deve usar `receivable_receipts`;
- `Fluxo de caixa por período` deve usar `cash_flow`;
- não deve existir duplicidade conceitual.

#### Impacto

- dois gráficos diferentes contam o mesmo universo;
- o usuário acredita estar vendo duas óticas analíticas distintas, quando não está.

#### Risco

- alto

### 3. Inconsistência entre KPI `Valor Recebido` e gráfico `Recebimentos por período`

#### Regra atual

- KPI `Valor Recebido` usa `receivable_receipts`;
- gráfico `Recebimentos por período` usa `cash_flow IN`.

#### Regra correta

- ambos devem usar o mesmo universo oficial de `recebido`.

#### Impacto

- KPI e gráfico podem divergir no mesmo período;
- quebra a confiança do usuário;
- invalida leitura executiva rápida da tela.

#### Risco

- crítico

### 4. Inconsistência entre KPI `Fluxo de Caixa Liquido` e ausência de gráfico correspondente

#### Regra atual

- existe KPI `Fluxo de Caixa Liquido`;
- não existe `Fluxo de caixa por período`.

#### Regra correta

- o KPI precisa de um gráfico coerente com o mesmo universo.

#### Impacto

- o KPI não tem desdobramento visual;
- a leitura temporal de caixa fica indisponível.

#### Risco

- alto

### 5. Ausência de `Carteira por status`

#### Regra atual

- não existe gráfico de carteira na aba `Financeiro`.

#### Regra correta

- a especificação exige `Carteira por status`.

#### Impacto

- a aba não entrega a visão de composição da carteira;
- usuário fica sem leitura visual de `Pendente`, `Parcial`, `Em atraso`.

#### Risco

- alto

### 6. Ordenação temporal incorreta

#### Regra atual

- `buildSeriesMap()` transforma a chave em `label` amigável;
- depois ordena alfabeticamente por `label`.

#### Evidência

```ts
return Array.from(grouped.entries())
  .map<ReportChartSeriesPoint>(([label, value]) => ({ label, value }))
  .sort((a, b) => a.label.localeCompare(b.label, "pt-BR", { numeric: true }));
```

#### Regra correta

- a série deve preservar chave cronológica real e ordenar por ela antes de exibir o label.

#### Impacto

- meses podem aparecer fora de sequência;
- tendência financeira fica visualmente incorreta.

#### Risco

- alto

### 7. Consistência fraca entre tabela financeira e gráficos

#### Regra atual

- tabela financeira usa `filtered` derivado de `cash_flow`;
- KPI `Valor Recebido` usa `filteredReceipts`;
- gráficos atuais usam `filtered` derivado de `cash_flow`.

#### Regra correta

- é aceitável que a tabela siga sendo de movimentações financeiras;
- mas os gráficos precisam declarar e respeitar seus universos.

#### Impacto

- a tabela fica mais alinhada ao `Fluxo de Caixa`;
- o gráfico de `Recebimentos` fica desalinhado da tabela e do KPI.

#### Risco

- médio/alto

### 8. Consistência com exportações

#### Regra atual

- `CSV/XLSX` exportam apenas a tabela;
- `PDF/Print` usam `report.kpis` e `report.charts`.

#### Impacto prático

- o PDF pode perpetuar gráficos semanticamente incorretos;
- `CSV/XLSX` podem parecer “corretos” porque não carregam os gráficos.

#### Risco

- médio

## Consistência Entre KPI, Gráficos, Tabela e Exportações

| Elemento | Universo atual | Situação |
|---|---|---|
| KPI `Valor Recebido` | `receivable_receipts` | Correto após REL-001 |
| KPI `Contas a Receber` | `accounts_receivable` | Correto após REL-001A |
| KPI `Contas em Atraso` | `accounts_receivable` | Correto após REL-001 |
| KPI `Fluxo de Caixa Liquido` | `cash_flow` | Correto após REL-001 |
| Tabela financeira | `cash_flow` enriquecido | Parcialmente correta para movimento financeiro |
| Gráfico `Evolução do faturamento` | `cash_flow IN` | Incorreto |
| Gráfico `Recebimentos por período` | `cash_flow IN` | Incorreto |
| Gráfico `Distribuição por forma de pagamento` | `cash_flow IN` | Incorreto |
| Exportação PDF/Print | usa `report.charts` | Herda erro gráfico atual |
| Exportação CSV/XLSX | usa `report.rows` | Não corrige nem agrava o erro gráfico |

## Correções Necessárias

### Correções obrigatórias de semântica

1. Remover o gráfico `Evolução do faturamento` da aba `Financeiro`.
2. Criar/retornar `Fluxo de caixa por período` no lugar dele.
3. Refazer `Recebimentos por período` com base em `receivable_receipts`.
4. Refazer `Distribuição do recebido por forma de pagamento` com base em `receivable_receipts`.
5. Adicionar `Carteira por status` com base em `accounts_receivable`.

### Correções obrigatórias de agregação temporal

1. Parar de ordenar séries temporais pelo label humanizado.
2. Preservar chave de período real.
3. Só formatar o label após a ordenação cronológica.

### Correções obrigatórias de consistência

1. Garantir que o gráfico de `Recebimentos por período` feche com o KPI `Valor Recebido`.
2. Garantir que o gráfico de `Distribuição do recebido por forma de pagamento` feche com o mesmo universo do KPI `Valor Recebido`.
3. Garantir que `Fluxo de caixa por período` feche com o universo do KPI `Fluxo de Caixa Liquido`.
4. Garantir que `Carteira por status` seja compatível com `Contas a Receber` e `Contas em Atraso`.
5. Garantir que PDF/Print reflitam os novos gráficos corretos.

## Casos de Teste Afetados

### Diretamente afetados

- `CT-002`
  - recebido total e entrada em caixa precisam refletir gráficos corretos.

- `CT-006`
  - recebimento parcelado em múltiplas datas;
  - impacta diretamente `Recebimentos por período`.

- `CT-007`
  - recebimento com múltiplas formas;
  - impacta diretamente `Distribuição do recebido por forma de pagamento`.

- `CT-010`
  - fluxo de caixa com entrada, saída e ajuste;
  - impacta diretamente `Fluxo de caixa por período`.

- `CT-014`
  - exportações;
  - impacta PDF/Print e coerência entre tela e exportação.

### Indiretamente afetados

- `CT-005`
  - ajuda a validar se a carteira visual e os gráficos não contradizem a posição financeira.

- `CT-008`
  - impacta `Carteira por status`, especialmente status vencido.

- `CT-009`
  - impacta `Carteira por status`, especialmente separação entre aberto futuro e atraso.

## Riscos de Regressão

### Nível geral

- **Alto**

### Principais riscos

1. Quebra de comparação com período anterior
   - `ReportCharts` compara gráficos por `chart.id`;
   - se ids mudarem sem estratégia, a comparação visual pode desaparecer ou parear gráficos errados.

2. Regressão no PDF
   - `renderPdfCharts()` usa `report.charts`;
   - qualquer inconsistência de tipo ou formato impacta o PDF.

3. Regressão no layout visual
   - a inclusão do quarto gráfico financeiro muda a ocupação do grid;
   - o componente já suporta 3 colunas, mas o arranjo final precisa ser pensado.

4. Regressão de consistência com filtros atuais
   - a `REL-002` não deve redesenhar os filtros;
   - mas os gráficos novos precisarão respeitar o comportamento atual sem invadir a `REL-003`.

5. Regressão de ordenação em gráficos não financeiros
   - se `buildSeriesMap()` for alterado globalmente, o impacto pode alcançar `Vendas`, `Produtos` e `Clientes`.

## Estratégia de Implementação

### Estratégia segura

1. Corrigir primeiro o backend dos gráficos financeiros em `service.ts`, sem mexer em filtros estruturais.
2. Tratar a ordenação temporal em `utils.ts` com cuidado para não quebrar gráficos não financeiros.
3. Ajustar `report-charts.tsx` apenas se o novo payload exigir.
4. Validar `PDF/Print` porque usam `report.charts`.
5. Não tocar em `CSV/XLSX`, banco, migrations, triggers, procedures ou fluxos financeiros transacionais.

## Ordem Exata de Codificação

1. `apps/admin/src/lib/reports/service.ts`
   - substituir o bloco `charts` da aba `Financeiro`;
   - alinhar títulos, ids, origens e agregações.

2. `apps/admin/src/lib/reports/utils.ts`
   - ajustar estratégia de ordenação temporal preservando chave cronológica real.

3. `apps/admin/src/components/reports/report-charts.tsx`
   - adaptar apenas se necessário para o novo conjunto/tipo de gráficos.

4. `apps/admin/src/components/reports/report-page-client.tsx`
   - validar impacto indireto em `renderPdfCharts()` e comparação entre períodos.

5. Revalidar exportação PDF/Print e consistência com `report.charts`.

## Critérios de Aceite da REL-002

Conforme os documentos oficiais, a `REL-002` só deve ser considerada aprovada se:

1. `Recebimentos por período` usar `receivable_receipts` e fechar com o KPI `Valor Recebido`.
2. `Fluxo de caixa por período` existir e fechar com o KPI `Fluxo de Caixa Liquido`.
3. `Distribuição do recebido por forma de pagamento` usar `receivable_receipts` e fechar com o total recebido do recorte.
4. `Carteira por status` existir e ser coerente com `Contas a Receber` e `Contas em Atraso`.
5. Toda série temporal financeira estiver em ordem cronológica correta.
6. O PDF/Print refletir exatamente os gráficos financeiros corrigidos.
7. Os casos de teste vinculados forem aprovados:
   - `CT-002`
   - `CT-006`
   - `CT-007`
   - `CT-010`
   - `CT-014`

## Observação de Governança

- `STATUS.md` está coerente com a autorização de análise da `REL-002`.
- `NEXT_TASK.md` ainda aponta para `REL-001`, embora [STATUS.md](file:///c:/Users/Natan/Downloads/ktalogu-main/docs/relatorios/STATUS.md#L5-L7) e [DECISOES.md](file:///c:/Users/Natan/Downloads/ktalogu-main/docs/relatorios/DECISOES.md#L29-L31) já definam `REL-002` como próxima história autorizada.
- Essa inconsistência documental foi apenas registrada neste diagnóstico e **não foi alterada**, por restrição explícita do escopo atual.

## Conclusão Executiva

- Os gráficos financeiros atuais da aba `Financeiro` **não estão semanticamente corretos**.
- Existe duplicidade de universo analítico entre dois gráficos.
- Existe divergência objetiva entre KPIs e gráficos.
- A ordenação temporal atual é tecnicamente inadequada.
- As exportações PDF/Print herdam diretamente esses problemas.

### Nível de risco

- **Alto**

### Implementação está autorizada?

- **Não automaticamente**

A implementação da `REL-002` só deve começar após aprovação explícita deste diagnóstico.