# Diagnóstico Técnico - REL-003

## Objetivo

Diagnosticar exclusivamente a `REL-003`, sem alterar código, banco ou documentação existente, definindo:

- escopo real da história;
- arquivos impactados;
- dependências;
- riscos de regressão;
- regras atuais;
- regras corretas segundo `ESPECIFICACAO_OFICIAL.md` e `MATRIZ_DE_VERDADE.md`;
- estratégia recomendada;
- recomendação formal de autorização ou não para implementação.

## Escopo Oficial da REL-003

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

- corrigir filtros da aba `Financeiro`;
- aplicar corretamente a data de corte financeira;
- fazer a tabela analítica financeira reproduzir a verdade oficial;
- preservar o que já foi estabilizado em `REL-001`, `REL-002` e `REL-002A`.

Referências documentais principais:

- `BACKLOG_EXECUTIVO.md`: `REL-003 = Corrigir filtros, data de corte e tabela analítica financeira`
- `PLANO_DE_EXECUCAO.md`: `REL-003` pertence ao Marco 1 da Sprint 1
- `CASOS_DE_TESTE.md`: casos obrigatórios `CT-005`, `CT-008`, `CT-009`, `CT-010`, `CT-014`

## Arquivos Impactados

### Primários

- `apps/admin/src/lib/reports/service.ts`
  - concentra `loadOptions()` e `buildFinancialReport()`;
  - hoje é o núcleo da montagem de filtros, KPIs, gráficos e tabela da aba `Financeiro`.

- `apps/admin/src/components/reports/report-page-client.tsx`
  - define os filtros exibidos para a aba `Financeiro`;
  - controla exportações a partir do payload do relatório.

- `apps/admin/src/components/reports/report-data-table.tsx`
  - renderiza a grade analítica;
  - pode precisar acomodar colunas adicionais e/ou novos tipos de linha do universo financeiro.

### Secundários ou condicionais

- `apps/admin/src/lib/reports/contracts.ts`
  - hoje o payload de opções não contempla catálogos específicos de `conta bancária`, `categoria financeira` e `canal financeiro`;
  - pode precisar extensão mínima para suportar filtros oficiais da aba `Financeiro`.

- `apps/admin/src/app/api/reports/export/route.ts`
  - não contém a regra financeira em si, mas exporta exatamente `report.rows`;
  - qualquer limitação da tabela financeira atual é propagada para `CSV/XLSX`.

- `apps/admin/src/app/api/reports/route.ts`
  - tende a permanecer estável, mas deve ser revalidado por ser o ponto de entrada do relatório.

## Dependências

### Dependências já satisfeitas

- `REL-001` concluída: KPIs financeiros já aderentes à matriz de verdade.
- `REL-002` concluída: gráficos financeiros e ordenação temporal já ajustados.
- `REL-002A` concluída: comparação com período anterior e metadados mínimos de exportação já estabilizados.

### Dependências funcionais para a REL-003

- catálogo oficial de filtros financeiros definido na especificação:
  - período;
  - cliente;
  - forma de pagamento;
  - status financeiro;
  - conta bancária;
  - categoria financeira;
  - canal financeiro, quando aplicável.

- validação dos casos:
  - `CT-005`
  - `CT-008`
  - `CT-009`
  - `CT-010`
  - `CT-014`

### Dependências técnicas observadas no código

- disponibilidade de `bank_accounts` no serviço de relatórios;
- disponibilidade de `financial_categories` na base de código, ainda não conectada ao módulo de relatórios;
- definição confiável de `canal financeiro`, hoje apenas parcialmente inferido no fluxo `PEDIDO`.

## Regras Atuais Encontradas

### 1. Filtros financeiros exibidos hoje

Na interface, a aba `Financeiro` expõe apenas:

- `Cliente`
- `Forma de pagamento`
- `Status`

Ou seja, estão ausentes:

- `Conta bancária`
- `Categoria financeira`
- `Canal financeiro`

### 2. Catálogo de opções de filtro

O backend atual monta opções genéricas em `loadOptions()`:

- `paymentMethods` vem de `payments`, não do universo financeiro oficial da aba;
- `statuses` é uma lista misturada de status comerciais, de orçamento e financeiros;
- não há opções dedicadas para `bank_accounts`, `financial_categories` ou `channel`.

### 3. Aplicação atual dos filtros financeiros

No `buildFinancialReport()`:

- `client`, `paymentMethod` e `status` filtram `entries` de `cash_flow`;
- `client`, `paymentMethod` e `status` filtram `filteredReceipts` de `receivable_receipts`;
- `openReceivables` usa apenas `client` e `status` derivado da carteira;
- `paymentMethod` não tem efeito sobre `Contas a Receber` nem `Contas em Atraso`;
- não existe filtro por `bankAccount`, `category` ou `channel`.

### 4. Data de corte atual

Os KPIs de carteira usam `endDate` corretamente:

- `Contas a Receber` usa saldo aberto da carteira na data final;
- `Contas em Atraso` usa `due_date < endDate`.

Ou seja:

- a data de corte dos KPIs financeiros foi parcialmente corrigida em `REL-001/REL-001A`;
- porém a tabela não reproduz essa mesma verdade posicional.

### 5. Tabela analítica financeira atual

A tabela financeira é montada apenas com `filtered`, que deriva de `cash_flow`.

Efeito prático:

- a grade mostra movimentações de caixa;
- não mostra, de forma estruturada, títulos em aberto sem movimento no período;
- não mostra títulos futuros em carteira sem baixa;
- não mostra de forma explícita saldo aberto por título;
- não fecha integralmente com os cenários de carteira exigidos em `CT-005`, `CT-008` e `CT-009`.

### 6. Exportação atual

`CSV/XLSX` exportam exatamente `report.rows`, logo:

- se a tabela financeira está incompleta para a verdade oficial;
- a exportação dessa aba também ficará incompleta para a mesma verdade.

## Regras Corretas Segundo a Especificação e a Matriz de Verdade

### 1. Filtros oficiais da aba Financeiro

Segundo `ESPECIFICACAO_OFICIAL.md`, a aba `Financeiro` deve oferecer:

- período;
- cliente;
- forma de pagamento;
- status financeiro;
- conta bancária;
- categoria financeira;
- canal financeiro, quando aplicável.

### 2. Regras corretas por universo

- `Valor Recebido` pertence ao universo `Financeiro Caixa` e deve vir de `receivable_receipts`.
- `Fluxo de Caixa Líquido` pertence ao universo `Financeiro Caixa` e deve vir de `cash_flow`.
- `Contas a Receber` e `Contas em Atraso` pertencem ao universo `Financeiro Competência` e devem vir de `accounts_receivable`.

### 3. Regra correta de data de corte

- `Contas a Receber` deve ser posição de carteira na data final do relatório.
- `Contas em Atraso` deve usar a data final selecionada como data de corte.
- títulos futuros em aberto entram na carteira e não entram no atraso.

### 4. Regra correta da tabela analítica financeira

A tabela da aba `Financeiro` precisa reproduzir a verdade oficial do recorte selecionado, e não apenas um subconjunto do caixa.

Na prática, a grade financeira precisa ser coerente com:

- movimentações de caixa do período;
- recebimentos efetivos do período;
- carteira em aberto na data de corte;
- atraso na data de corte.

Isso é necessário para sustentar:

- `CT-005`: recebimento parcial;
- `CT-008`: conta vencida em aberto;
- `CT-009`: conta futura em aberto;
- `CT-010`: fluxo de caixa líquido;
- `CT-014`: tela e exportação coerentes.

### 5. Regras corretas dos filtros por impacto

Segundo a especificação:

- filtro de `forma de pagamento` afeta `Valor Recebido` e análises financeiras por forma;
- filtro de `status financeiro` afeta `Contas a Receber` e `Contas em Atraso`;
- filtro de `conta bancária` afeta caixa e recebimentos quando aplicável;
- filtro de `categoria financeira` afeta carteira e caixa quando a categoria fizer parte da consulta;
- filtros da aba devem afetar tela e exportação de forma idêntica.

## Divergências Principais Encontradas

### Divergência 1

- **Tema:** catálogo de filtros financeiros.
- **Atual:** a UI mostra só `cliente`, `forma de pagamento` e `status`.
- **Correto:** a aba deve oferecer também `conta bancária`, `categoria financeira` e `canal financeiro`, quando aplicável.

### Divergência 2

- **Tema:** origem das opções de filtro.
- **Atual:** `paymentMethods` vem de `payments` e `statuses` misturam universos.
- **Correto:** o catálogo do `Financeiro` precisa ser derivado do próprio universo financeiro oficial.

### Divergência 3

- **Tema:** efeito dos filtros sobre carteira.
- **Atual:** `paymentMethod` não afeta `Contas a Receber` nem `Contas em Atraso`, e não há regra explícita por universo dentro da tabela.
- **Correto:** cada filtro precisa atuar apenas sobre os subconjuntos oficiais em que faz sentido, sem misturar caixa e competência de forma implícita.

### Divergência 4

- **Tema:** tabela analítica financeira.
- **Atual:** a grade é essencialmente um espelho de `cash_flow`.
- **Correto:** a tabela deve reproduzir a verdade oficial do financeiro, cobrindo caixa e posição de carteira de modo auditável no mesmo recorte.

### Divergência 5

- **Tema:** data de corte na evidência tabular/exportável.
- **Atual:** os KPIs usam `endDate`, mas a grade não evidencia adequadamente títulos futuros ou vencidos sem movimento.
- **Correto:** a data de corte precisa refletir não só nos KPIs, mas também na grade e na exportação.

## Riscos de Regressão

### 1. Regressão em KPIs financeiros

Se a implementação misturar novamente `cash_flow`, `receivable_receipts` e `accounts_receivable` sem separação por universo, pode regredir:

- `Valor Recebido`
- `Contas a Receber`
- `Contas em Atraso`
- `Fluxo de Caixa Líquido`

### 2. Regressão em gráficos já aprovados na REL-002

Se a `REL-003` alterar indevidamente a base do `Financeiro` sem preservar os subconjuntos corretos:

- gráficos podem deixar de fechar com os KPIs;
- filtros podem introduzir divergência entre gráfico e card.

### 3. Regressão em exportações

Como `CSV/XLSX/PDF/Print` consomem o relatório já montado:

- qualquer erro na composição de `rows` ou `appliedFilters`;
- será propagado diretamente para exportação.

### 4. Regressão de UX e contrato

Adicionar filtros oficiais do `Financeiro` impacta:

- payload de metadata;
- composição visual da barra de filtros;
- persistência de presets;
- ordenação e visibilidade de colunas da tabela.

### 5. Risco de origem incompleta para categoria/canal

- `financial_categories` já existe no código-base, mas não está conectado ao módulo de relatórios;
- `channel` financeiro não possui hoje fonte explícita e confiável para todos os tipos de movimento.

## Estratégia Recomendada

### 1. Congelar o princípio de separação por universo

Antes de codificar, a implementação deve preservar explicitamente:

- `caixa` para `cash_flow` e `receivable_receipts`;
- `competência` para `accounts_receivable`;
- sem reconciliação implícita entre os dois.

### 2. Corrigir primeiro o catálogo de filtros financeiros

Em `loadOptions()` e no contrato de opções:

- separar catálogo financeiro do catálogo genérico atual;
- adicionar `bankAccounts`;
- adicionar `financialCategories`;
- adicionar `channels` quando houver origem confiável;
- manter `client`, `paymentMethod` e `status`, mas com semântica financeira oficial.

### 3. Corrigir a barra de filtros da aba Financeiro

Em `report-page-client.tsx`:

- exibir os filtros oficiais da aba;
- não reutilizar a configuração simplificada atual.

### 4. Reestruturar a tabela financeira no serviço

Em `buildFinancialReport()`:

- manter os KPIs e gráficos já aprovados;
- reconstruir a grade analítica para representar a verdade oficial do recorte;
- separar explicitamente linhas de `caixa/recebimento` e linhas de `carteira`, se necessário;
- garantir que títulos futuros e títulos vencidos sem movimento apareçam de forma auditável.

### 5. Validar exportação por consequência do relatório

Sem mudar a semântica de exportação:

- fazer `CSV/XLSX/PDF/Print` herdarem a nova grade correta;
- revalidar se o total de linhas exportadas e o conjunto filtrado reproduzem exatamente a tela.

### 6. Preservar restrições já aprovadas

- não alterar banco;
- não criar migrations;
- não alterar triggers ou procedures;
- não alterar lógica transacional;
- não alterar a correção temporal da `REL-002`;
- não alterar KPIs já aprovados.

## Casos de Teste Diretamente Afetados

- `CT-005`: exige que a tabela consiga evidenciar recebimento parcial e saldo remanescente.
- `CT-008`: exige que a tabela reflita saldo vencido em aberto na data de corte.
- `CT-009`: exige que a tabela reflita título futuro em aberto na carteira, sem classificá-lo como atraso.
- `CT-010`: exige que a tabela continue coerente com o fluxo líquido oficial.
- `CT-014`: exige que exportação e tela reflitam a mesma grade filtrada.

## Autorização Recomendada para Implementação

### Recomendação

**SIM, com autorização condicional para implementação.**

### Justificativa

- a `REL-003` já tem dependências principais satisfeitas (`REL-001`, `REL-002`, `REL-002A`);
- o problema atual está concentrado na camada de relatórios, sem exigir mudança obrigatória de banco;
- as divergências encontradas são claras, reproduzíveis e aderentes ao escopo oficial da história;
- a implementação pode ser feita prioritariamente em `service.ts`, `report-page-client.tsx`, `report-data-table.tsx` e, se indispensável, `contracts.ts`.

### Condições para autorização

- preservar integralmente as fontes oficiais já consolidadas;
- não reinterpretar KPI nem gráfico da `REL-001`/`REL-002`;
- tratar `canal financeiro` apenas quando existir origem confiável;
- revalidar obrigatoriamente `CT-005`, `CT-008`, `CT-009`, `CT-010` e `CT-014`;
- validar tela e exportação como um único comportamento.

## Conclusão Executiva

A `REL-003` está corretamente posicionada como a história que fecha o bloco financeiro analítico após `REL-001` e `REL-002`.

O diagnóstico mostra que:

- os KPIs e gráficos principais já foram corrigidos;
- porém os filtros financeiros ainda não representam o catálogo oficial;
- a tabela financeira ainda não reproduz a verdade oficial da carteira e do caixa;
- a exportação herda essa limitação porque consome `report.rows`.

Portanto:

- a `REL-003` **não está implementada**;
- a necessidade da história é **real e tecnicamente comprovada**;
- a implementação é **recomendada e pode ser autorizada condicionalmente**.