# Validação Técnica - REL-007

## Objetivo

Registrar a validação técnica da `REL-007`, implementada para:

- formalizar uma definição única de `pedido comercial válido` na camada de relatórios;
- remover pedidos cancelados e demais status inelegíveis do universo comercial compartilhado;
- reaplicar a mesma regra em `Vendas`, `Produtos`, `Clientes` e `Personalizados` onde houver consumo de pedidos;
- preservar integralmente o escopo das histórias futuras `REL-008` e `REL-009`.

## Escopo executado

Implementação realizada exclusivamente no pacote aprovado da `REL-007`:

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

Sem alteração em:

- banco
- migrations
- triggers
- procedures
- APIs
- camada financeira
- `REL-001` a `REL-006`
- `apps/admin/src/components/reports/report-page-client.tsx`

## Arquivo alterado e justificativa

### Camada analítica comercial

- `apps/admin/src/lib/reports/service.ts`
  - adiciona helper central para normalizar e validar a elegibilidade comercial de pedidos;
  - centraliza os status inelegíveis em um único ponto;
  - refatora `loadSalesBase()` para carregar apenas pedidos comercialmente válidos;
  - reaplica a mesma regra na leitura de pedidos de `buildCustomersReport()`;
  - reduz o catálogo do filtro de status comercial para os status visíveis do universo oficial de pedidos.

## Regra oficial implementada

### Definição central

- helper de normalização: `normalizeCommercialOrderStatus(status)`
- helper de elegibilidade: `isCommerciallyValidOrderStatus(status)`

### Política aplicada

- status inelegíveis centralizados:
  - `canceled`
  - `cancelled`
  - `draft`
- status sem valor explícito passam a ser normalizados para `pending_production`, preservando o comportamento operacional já adotado no domínio de pedidos;
- nenhuma outra regra comercial foi recalibrada nesta história.

## Superfícies impactadas

### 1. Base compartilhada comercial

- `loadSalesBase()` agora descarta pedidos inelegíveis antes de montar:
  - linhas de vendas;
  - base de produtos;
  - base do customizado;
  - relacionamentos auxiliares de cliente, item, pagamento e orçamento ligados aos pedidos elegíveis.

### 2. Aba `Vendas`

- passa a consumir exclusivamente a base comercial saneada;
- pedidos cancelados deixam de compor a tabela e os gráficos derivados da base compartilhada;
- nenhum cálculo de KPI foi redefinido nesta história.

### 3. Aba `Produtos`

- passa a herdar apenas itens originados de pedidos elegíveis;
- pedidos cancelados deixam de contaminar quantidade, receita, lucro e presença em rankings da base atual.

### 4. Aba `Clientes`

- a coleta de pedidos do cliente passa a ignorar pedidos inelegíveis;
- o escopo foi mantido restrito ao consumo de pedidos existente, sem antecipar a redefinição de `Novos`, `Ativos` ou `Inativos`, reservada às histórias futuras.

### 5. Aba `Personalizados`

- como utiliza `loadSalesBase()`, passa a herdar automaticamente a mesma base comercial saneada;
- não houve alteração de governança do customizado, preservando o escopo das histórias `REL-016+`.

## Evidências técnicas executadas

### Diagnósticos do editor

- `GetDiagnostics` sem erros em:
  - `apps/admin/src/lib/reports/service.ts`

### Validação de lint

- comando:
  - `npx eslint src/lib/reports/service.ts`
- resultado:
  - `exit code 0`

### Validação de TypeScript

- comando:
  - `npx tsc --noEmit`
- resultado:
  - `exit code 0`

### Validação automatizada existente

- comando:
  - `npm test`
- resultado:
  - `15` arquivos de teste aprovados
  - `29/29` testes aprovados

### Observação sobre build

- o comando `npm run build` foi iniciado com sucesso;
- a compilação avançou até:
  - `Compiled successfully`
  - `Running TypeScript`
  - `Collecting page data using 3 workers`
- a ferramenta interrompeu a coleta final do processo por limite operacional da sessão, sem evidência de erro de compilação até o ponto observado.

## Casos de teste revalidados

## CT-001

### Status

- **Aprovado por análise técnica sem regressão detectada**

### Evidência

- a `REL-007` não altera a base financeira;
- um pedido comercialmente válido continua pertencendo ao universo de vendas;
- a exclusão de inelegíveis não remove pedidos válidos sem recebimento.

## CT-002

### Status

- **Aprovado por análise técnica sem regressão detectada**

### Evidência

- a história não altera a trilha financeira oficial entregue nas `REL-004` a `REL-006`;
- pedidos válidos pagos continuam pertencendo ao universo comercial;
- `Vendas`, `Produtos` e `Personalizados` continuam consumindo o pedido quando ele permanece elegível.

## CT-003

### Status

- **Aprovado**

### Evidência

- pedidos com status `canceled` ou `cancelled` passam a ser barrados pela helper central;
- a exclusão ocorre antes da montagem da base compartilhada;
- com isso, o pedido cancelado deixa de contaminar:
  - `Vendas`
  - `Produtos`
  - `Clientes` no consumo de pedidos
  - `Personalizados` baseados em pedidos

## CT-004

### Status

- **Aprovado por análise técnica sem regressão detectada**

### Evidência

- a política financeira de estorno e reversão auditável permanece intacta;
- a `REL-007` atua apenas na elegibilidade comercial do pedido para relatórios;
- pedido cancelado após recebimento continua fora do universo comercial, sem reabrir a base financeira das `REL-004` e `REL-006`.

## Regressão nas abas comerciais

### Aba `Vendas`

- sem erro de tipo, lint ou diagnóstico;
- passa a usar a base com exclusão centralizada de pedidos inelegíveis.

### Aba `Produtos`

- sem erro de tipo, lint ou diagnóstico;
- herda a mesma exclusão pela base compartilhada.

### Aba `Clientes`

- sem erro de tipo, lint ou diagnóstico;
- pedidos cancelados deixam de influenciar os mapas de pedidos por cliente.

### Aba `Personalizados`

- sem erro de tipo, lint ou diagnóstico;
- a base detalhada usada pelo customizado passa a excluir pedidos inelegíveis.

## Riscos remanescentes

- a validação desta entrega foi técnica e estrutural, baseada em:
  - leitura integral da documentação oficial;
  - análise do código implementado;
  - diagnósticos do editor;
  - `eslint`;
  - `tsc`;
  - suíte automatizada existente;
- não foi executada bateria E2E com massa real instrumentada nesta sessão;
- `REL-008` e `REL-009` permanecem necessárias para corrigir, respectivamente:
  - KPIs e ranking comercial;
  - conversão real de orçamentos.

## Conclusão

A `REL-007` foi implementada dentro do escopo autorizado, restrita à camada analítica comercial em `apps/admin/src/lib/reports/service.ts`.

O sistema passa a preservar:

- uma única definição oficial de pedido comercial válido;
- reutilização central da regra na base compartilhada;
- exclusão estrutural de pedidos inelegíveis do universo comercial;
- isolamento do escopo, sem antecipar `REL-008` nem `REL-009`.

## Veredito final

- **CT-001 APROVADO**
- **CT-002 APROVADO**
- **CT-003 APROVADO**
- **CT-004 APROVADO**
- **REL-007 CONCLUÍDA**