# Diagnóstico Técnico - REL-008 ## Objetivo Delimitar tecnicamente a `REL-008`, história responsável por corrigir os indicadores comerciais da aba `Vendas` com base obrigatória na definição oficial de `pedido comercial válido` já entregue na `REL-007`. Este diagnóstico não implementa nenhuma alteração. ## Base documental obrigatória revisada Leitura integral confirmada dos documentos: - `BACKLOG_EXECUTIVO.md` - `PLANO_DE_EXECUCAO.md` - `PLANO_DE_CORRECAO.md` - `MATRIZ_DE_VERDADE.md` - `CASOS_DE_TESTE.md` - `STATUS.md` - `NEXT_TASK.md` - `CHANGELOG.md` - `VALIDACAO_REL_007.md` ## Conclusão executiva A `REL-008` está tecnicamente pronta para execução porque: - a dependência obrigatória `REL-007` foi concluída; - a base oficial de pedidos válidos já existe e está centralizada; - os cálculos da aba `Vendas` estão concentrados principalmente em um único ponto da camada analítica; - o escopo pode ser isolado sem tocar banco, APIs, camada financeira ou trilhas das histórias anteriores. Entretanto, existe uma inconsistência documental a ser observada: - a documentação oficial ainda vincula `CT-011` à `REL-008`; - tecnicamente, `CT-011` valida conversão real de orçamentos, que pertence ao escopo da `REL-009`, não da `REL-008`. ## Estado atual após a REL-007 A `REL-007` deixou o sistema em condição adequada para iniciar a `REL-008`: - `loadSalesBase()` já exclui pedidos inelegíveis do universo comercial; - `Vendas`, `Produtos`, `Clientes` e `Personalizados` já herdam a nova elegibilidade comercial onde consomem pedidos; - a `REL-008` não precisa redefinir `pedido válido`, apenas reutilizar a base saneada. ## Escopo exato da REL-008 ### O que entra - correção do KPI comercial de `Faturamento Total` da aba `Vendas`; - correção do KPI comercial de `Ticket Médio`; - correção do `Ranking de Clientes` da aba `Vendas`; - correção dos gráficos da aba `Vendas` que dependem desses cálculos; - reconciliação entre cards, gráfico, tabela e exportações da aba `Vendas`; - preservação da base oficial de pedidos válidos formalizada na `REL-007`. ### O que não entra - conversão real de orçamentos; - redefinição de orçamentos elegíveis; - vínculo `quote -> order`; - qualquer ajuste na aba `Produtos`; - qualquer redefinição da aba `Clientes`; - qualquer mudança em banco, migrations, triggers, procedures ou APIs; - qualquer recalibração financeira. ## Limite formal em relação à REL-009 Tudo que envolve `Conversão de Orçamentos` permanece fora da `REL-008`. Isso inclui: - KPI `Taxa de conversão`; - gráfico `Conversão de orçamentos`; - regra de denominador de orçamentos elegíveis; - regra de numerador por conversão real; - validação via `orders.quote_id`; - `CT-011`. Se a `REL-008` tocar nessa parte, haverá invasão direta do escopo da `REL-009`. ## Auditoria do código atual ## Funções hoje envolvidas ### Obrigatórias no diagnóstico - `loadSalesBase()` - `buildSalesReport()` ### Funções de apoio potencialmente envolvidas - `buildSeriesMap()` - `monthLabel()` - lógica de alinhamento de gráficos comparativos por período ## KPIs da aba Vendas: diagnóstico atual ### 1. Total de pedidos ### Situação atual - calculado por quantidade distinta de `orderId` na base comercial já saneada. ### Diagnóstico - estruturalmente aderente como indicador auxiliar; - não é o foco principal da `REL-008`, mas serve de base para ticket e reconciliação. ### 2. Valor vendido ### Situação atual - calculado pela soma de `orderTotal` em pedidos distintos da base comercial válida. ### Diagnóstico - a fórmula atual está estruturalmente alinhada à Matriz de Verdade para `Faturamento Total comercial`; - o principal ajuste pendente não é a fonte, e sim garantir nomenclatura oficial, coerência com gráfico e reconciliação total com a tabela. ### Divergência residual - o card ainda está nomeado como `Valor vendido`, enquanto a documentação oficial trabalha com `Faturamento Total`. - isso é uma divergência de contrato analítico/semântico, não necessariamente de fórmula. ### 3. Ticket médio ### Situação atual - calculado como `soldValue / totalOrders`, usando apenas pedidos válidos. ### Diagnóstico - a fórmula atual está estruturalmente correta segundo a Matriz de Verdade; - a história precisa validar coerência final com filtros, gráfico e exportação da aba `Vendas`. ### Divergência residual - não há erro estrutural evidente de fórmula após a `REL-007`; - ainda exige validação de paridade com os demais elementos da aba na mesma entrega. ### 4. Taxa de conversão ### Situação atual - calculada como `approvedQuotes / nonDraftQuotes`. ### Diagnóstico - está incorreta perante a Matriz de Verdade; - mede aprovação de orçamento, não conversão real em pedido; - pertence tecnicamente à `REL-009`, não à `REL-008`. ### Conclusão - este KPI está errado hoje, mas não deve ser corrigido dentro da `REL-008`. ### 5. Ranking visual dos clientes ### Situação atual - calculado por soma de `lineTotal` da base detalhada; - agrupado por `clientName`. ### Diagnóstico - está estruturalmente divergente da Matriz de Verdade; - a matriz exige `sum(total_amount)` por cliente a partir de `orders` e `clients`; - o cálculo atual depende dos itens, não da soma oficial do pedido; - pedidos sem itens detalhados podem ficar subcontabilizados no ranking; - clientes homônimos podem ser fundidos indevidamente porque a chave atual é o nome exibido, não o identificador do cliente. ### Conclusão - este é o principal erro de negócio que pertence claramente à `REL-008`. ## Gráficos impactados pela REL-008 ### 1. Evolução de vendas ### Dependência - depende diretamente do total vendido por pedido válido no período. ### Situação atual - usa pedidos distintos da base saneada, mas monta a série a partir de rótulos já formatados por mês. ### Divergência - a agregação atual passa por `buildSeriesMap()` com ordenação textual de labels; - isso pode ordenar os meses alfabeticamente, e não cronologicamente; - para uma série temporal comercial, isso é divergência funcional. ### Impacto - a `REL-008` deve revalidar a cronologia do gráfico ao corrigir a camada comercial da aba `Vendas`. ### 2. Conversão de orçamentos ### Dependência - depende da lógica de conversão comercial. ### Situação atual - reflete a regra incorreta de `approved / non-draft`. ### Conclusão - está errado hoje, mas é dependência da `REL-009`. - não deve ser corrigido dentro da `REL-008`. ### 3. Ranking visual dos clientes ### Dependência - depende da agregação de valor comprado por cliente. ### Situação atual - herda o erro da agregação baseada em `lineTotal` e chave por `clientName`. ### Conclusão - pertence diretamente à `REL-008`. ## Tabelas impactadas ### Tabela analítica da aba Vendas #### Situação atual - usa uma linha por pedido, com `orderTotal`, cliente, vendedor, forma de pagamento, status e status do orçamento. #### Diagnóstico - a tabela já está baseada em pedido e não em item; - isso a torna a principal referência de reconciliação para `Faturamento Total` e `Ticket Médio`; - a tabela não possui ranking próprio, mas precisa permanecer compatível com os cards e com o gráfico de evolução. #### Conclusão - a tabela é impactada por paridade analítica, mesmo que não precise de mudança estrutural de colunas. ## Exportações impactadas ### Impacto direto - `PDF` - `Impressão` ### Motivo - ambas incorporam KPIs, gráficos e tabela do payload completo da aba `Vendas`. ### Impacto indireto - `CSV` - `Excel` ### Motivo - hoje exportam apenas a tabela; - como a `REL-008` deve manter reconciliação entre card, gráfico e tabela, essas exportações precisam ser revalidadas; - porém não há indício forte de que exijam alteração de código própria nesta história. ## Divergências atuais em relação à MATRIZ_DE_VERDADE.md ### Divergências confirmadas 1. `Taxa de conversão`: - hoje mede aprovação de orçamento; - a matriz exige conversão real por vínculo em pedido; - pertence à `REL-009`. 2. `Ranking de clientes`: - hoje soma `lineTotal` por nome de cliente; - a matriz exige soma de `total_amount` por cliente a partir de `orders` e `clients`; - pertence à `REL-008`. 3. `Evolução de vendas`: - a série temporal comercial pode sair em ordem textual e não cronológica; - a matriz e o plano operacional exigem coerência temporal do gráfico comercial; - pertence à `REL-008`. ### Divergências semânticas ou de contrato 1. `Valor vendido`: - a matriz e o backlog usam o conceito oficial `Faturamento Total comercial`; - a fórmula atual parece correta, mas a nomenclatura ainda não está plenamente alinhada. ## Casos de teste da REL-008 ### Mapeamento oficial atual Segundo o backlog e o plano de execução, a `REL-008` está vinculada a: - `CT-001` - `CT-002` - `CT-003` - `CT-011` - `CT-014` ### Leitura técnica recomendada Para manter a fronteira correta entre `REL-008` e `REL-009`: - `CT-001`, `CT-002`, `CT-003` e `CT-014` devem permanecer como validações da `REL-008`; - `CT-011` deve ser tratado como caso de teste dependente da `REL-009`, pois valida conversão real de orçamento. ## Funções que deverão ser alteradas ### Obrigatórias - `buildSalesReport()` ### Prováveis - `loadSalesBase()`, apenas se a solução precisar enriquecer a base de vendas para garantir agregação segura por cliente e por pedido sem duplicidade; - helper temporal reutilizável hoje coberto por `buildSeriesMap()` ou lógica equivalente, caso a correção cronológica do gráfico seja implementada fora de `buildSalesReport()`. ### Condicionais - alinhamento de comparação de período anterior para gráfico temporal de vendas, se a implementação exigir ajuste específico no cliente. ## Classificação dos arquivos ### Obrigatórios - `apps/admin/src/lib/reports/service.ts` ### Prováveis - `apps/admin/src/lib/reports/utils.ts` - `apps/admin/src/components/reports/report-page-client.tsx` ### Condicionais - `apps/admin/src/lib/reports/contracts.ts` - `apps/admin/src/components/reports/report-charts.tsx` - `apps/admin/src/components/reports/report-data-table.tsx` ### Não devem ser alterados - `apps/admin/src/app/api/reports/route.ts` - `apps/admin/src/app/api/reports/export/route.ts` - banco de dados - migrations - triggers - procedures - camada financeira - arquivos de `REL-001` a `REL-007` - `STATUS.md` - `CHANGELOG.md` - `DECISOES.md` - `NEXT_TASK.md` ## Justificativa da classificação ### `service.ts` - concentra a regra da aba `Vendas`; - concentra KPIs, gráficos e linhas da tabela; - é o ponto natural de correção da `REL-008`. ### `utils.ts` - é provável porque o gráfico de evolução comercial depende de agregação temporal; - a utilidade atual ordena labels textualmente, o que é inadequado para série temporal comercial. ### `report-page-client.tsx` - é provável apenas se for necessário alinhar comparação entre período atual e período anterior no gráfico temporal de vendas; - hoje o alinhamento temporal especial existe apenas para a aba financeira. ### `contracts.ts`, `report-charts.tsx` e `report-data-table.tsx` - ficam como condicionais; - os contratos e componentes atuais já suportam cards, gráficos, ranking e tabela; - só precisariam mudar se a solução exigir metadado adicional, novo tipo de série ou ajuste visual específico. ## Riscos de regressão ### Riscos altos - alterar `buildSalesReport()` e mudar os totais percebidos pelo Comercial; - corrigir ranking e expor divergência histórica em painéis já usados; - corrigir a evolução de vendas e alterar a leitura temporal já acostumada pelo usuário. ### Riscos médios - quebrar reconciliação entre card, gráfico e tabela da aba `Vendas`; - afetar `PDF` e `Impressão`, que usam o payload completo da aba; - afetar `CSV` e `Excel` indiretamente, se a tabela precisar de ajuste para manter paridade. ### Riscos de fronteira - tocar acidentalmente no KPI de conversão e invadir a `REL-009`; - tentar resolver ranking da aba `Clientes`, que pertence às histórias `REL-013` a `REL-015`; - antecipar produto/margem, que pertencem às `REL-010` a `REL-012`. ## Dependências com histórias futuras ### Dependência direta com REL-009 - `Taxa de conversão` e `Conversão de orçamentos` continuam erradas até a `REL-009`; - a `REL-008` não pode assumir qualquer definição de conversão real. ### Dependência com REL-010, REL-011 e REL-012 - a aba `Produtos` já herda a base saneada da `REL-007`, mas sua inteligência analítica oficial é futura; - a `REL-008` não deve reabrir lógica de produtos. ### Dependência com REL-013, REL-014 e REL-015 - ranking e status analítico da aba `Clientes` permanecem em histórias futuras; - a `REL-008` deve tratar apenas o ranking visual da aba `Vendas`. ### Dependência com REL-019 e REL-020 - exportações precisam ser revalidadas por paridade; - porém governança final de exportação e paridade total pertencem a histórias posteriores. ## Recomendação formal ## REL-008 AUTORIZADA ### Justificativa técnica - a dependência `REL-007` está concluída; - o escopo comercial de vendas está suficientemente isolado; - a maior parte da correção está concentrada em `buildSalesReport()`; - existe clareza sobre o que pertence à `REL-008` e o que deve permanecer congelado para `REL-009`; - não há necessidade técnica de mexer em banco ou API para executar a história. ### Ressalva obrigatória Antes da implementação, a execução deve adotar explicitamente a seguinte fronteira: - `REL-008` corrige `Faturamento Total`, `Ticket Médio`, `Ranking de Clientes` da aba `Vendas` e seus gráficos derivados; - `REL-009` corrige `Taxa de conversão`, gráfico de conversão e qualquer lógica baseada em `quote -> order`. ### Observação de governança Embora a recomendação seja `REL-008 AUTORIZADA`, recomenda-se registrar no início da execução que: - `CT-011` será tratado como dependência documental da `REL-009`; - a homologação da `REL-008` deve focar em `CT-001`, `CT-002`, `CT-003` e `CT-014`, sem reabrir conversão.