Relatórios Estratégicos

Pré-requisitos de acesso

• Permissão (módulo): admin (guard de rota AuthGuardService com data.module = admin) — é o relatório de inteligência mais restrito do BackOffice.
• Licença/Feature: Nenhuma.
• Contêiner do menu: GERAL → grupo Dashboard

O que é / quando usar

Conjunto de relatórios analíticos de inteligência comercial (somente leitura) gerados pelo microsserviço StrategicReportsService. Diferente dos painéis do Dashboard (que apenas somam o que já aconteceu), aqui há cálculos derivados: segmentação RFM de clientes, tendências de venda com comparação de período, funil de conversão, performance de produto/projeto, mix de meios de pagamento e sazonalidade. Use para decisões de marketing, retenção e priorização de produto — não como demonstrativo contábil.

A tela é um container com abas (/strategic-reports). Ao abrir, ela redireciona automaticamente para RFM (/strategic-reports/rfm-analysis). Cada aba é uma rota-filha que dispara sua própria consulta ao backend; trocar de aba refaz a busca daquela análise.

Pré-condições

• Permissão: módulo admin na role do operador (permissão dupla — enum CPM no backend + módulo dinâmico no DB). Sem admin, a rota é bloqueada pelo guard e o item nem aparece no menu.
• Licença/Feature: Nenhuma.
• Dependências de outras telas: os relatórios consomem o agregador de ordens do StrategicReportsService, que cruza ordens gerais (compras de token/NFT) e crowdfunding. Só ordens pagas (wasPaid = true) entram em RFM; nas demais análises o filtro wasPaid é configurável conforme a consulta.

Passo a passo

1. Acesse o menu Dashboard → Relatórios estratégicos.
2. A tela abre já na aba RFM; aguarde o gráfico carregar.
3. Ajuste o período (data inicial/final) da análise — o padrão da RFM é últimos 365 dias até hoje.
4. (Onde houver) escolha os tipos de ordem (geral, crowdfunding) e o agrupamento (dia/semana/mês/ano).
5. Troque de aba para gerar outra análise — cada aba consulta seu próprio endpoint.

Abas (relatórios disponíveis)

A barra de abas expõe sete relatórios. Há mais dois endpoints previstos no código (Origem de Cadastro e Perfil do Cliente) que ainda não estão implementados no backend e não aparecem como aba — ver "Regras de negócio".

Aba	Endpoint (API-Gateway /v1/strategic-reports/...)	O que entrega	Parâmetros de filtro
RFM	rfm-analysis	Segmentação de clientes por Recência, Frequência e Valor monetário. Distribui a base em segmentos (Champions, Loyal, At Risk, Hibernating, Lost, etc.) com contagem, % e receita por segmento.	from, to, orderTypes
Tendências de Venda	sales-trends	Série temporal de vendas com opção de comparar com o período anterior.	from, to, groupBy (dia/semana/mês/ano), compareWithPreviousPeriod, orderTypes
Análise de Conversão	conversion-analysis	Taxa de conversão (ex.: cadastro → primeira compra; pedido → pago).	from, to, storeId, projectId, orderTypes
Performance de Produto	product-performance	Ranking de produtos por receita/quantidade (limit para top-N).	from, to, storeId, orderTypes, limit, wasPaid
Performance de Loja/Projeto	store-project-performance	Comparativo por loja e por projeto de crowdfunding.	from, to, orderTypes, wasPaid
Meio de Pagamento	payment-method-analysis	Distribuição de receita por método de pagamento.	from, to, storeId, orderTypes, wasPaid
Sazonalidade	seasonality-analysis	Padrões sazonais (picos por mês/dia da semana).	from, to, storeId, projectId, orderTypes, wasPaid

Filtros e parâmetros

Filtro	O que é	Efeito no sistema/backend
Data inicial / final (from/to)	Janela da análise	Enviadas em ISO ao endpoint; limitam o conjunto de ordens agregadas. Na RFM, o to também é o "agora" usado para calcular a recência (dias desde a última compra).
Tipos de ordem (orderTypes)	geral e/ou crowdfunding	Define quais fluxos de ordem entram no cruzamento. all é normalizado para general. RFM separa contagem/valor por tipo (generalOrders* vs crowdfundingOrders*).
Agrupamento (groupBy)	Granularidade da série (só Tendências/Origem)	Agrupa a série por dia, semana, mês ou ano.
Comparar com período anterior	Espelha o intervalo para trás	Quando ligado em Tendências, o backend calcula o mesmo intervalo imediatamente anterior para variação %.
wasPaid	Considerar só ordens pagas	Em Produto/Loja/Pagamento/Sazonalidade é configurável; na RFM é forçado true (só compras efetivamente pagas pontuam).
storeId / projectId	Restringir a uma loja/projeto	Filtra a agregação àquela loja ou projeto de crowdfunding.

Como a RFM classifica os clientes

A RFM é o relatório mais elaborado e o único marcado como aba inicial. Entender a lógica evita leituras erradas:

1. Para cada cliente com ordens pagas no período, o agregador calcula Recência (dias desde a última compra), Frequência (nº de compras) e Monetário (total gasto).
2. Cada métrica recebe uma nota de 1 a 5 por percentis da base (p20/p40/p60/p80). Recência é "quanto menor melhor"; frequência e valor são "quanto maior melhor".
3. A combinação das três notas define o segmento (regras em cascata no backend): por exemplo, R≥4 F≥4 M≥4 = Champions; R≤2 F≥3 M≤2 = At Risk; e o que não casa em nenhuma regra cai em Lost.
4. O relatório devolve, por segmento, contagem, percentual e receita total/média, além do segmento dominante e médias de R/F/M da base.

As notas são relativas à base, não absolutas

O score RFM é calculado por percentis da população do período, não por faixas fixas. Isso significa que "ser Champion" depende de como o cliente se compara aos outros no mesmo recorte. Mudar o período ou os orderTypes reclassifica todo mundo. Não compare segmentos entre dois recortes diferentes como se fossem categorias estáveis.

Regras de negócio / cuidados

Atenção

• Origem de Cadastro e Perfil do Cliente não estão implementados. Os endpoints registration-source e customer-profile existem no service Angular e no handler do backend, mas o handler retorna "report not yet implemented" (falha). Eles não aparecem na barra de abas. Não documente/prometa esses dois relatórios ao usuário final até serem entregues.
• Erro ≠ zero. Cada aba mostra estado de carregamento (loading) e, em falha, não plota nada (a RFM zera os gráficos). Um gráfico vazio pode ser período sem dados ou indisponibilidade do StrategicReportsService — não leia como "zero vendas".
• Período padrão amplo. A RFM abre com 365 dias; em bases grandes a agregação pode levar alguns segundos. Os demais relatórios usam o período que você definir.
• Somente leitura. Nenhuma aba escreve dados; são relatórios derivados. Para conciliação oficial use Contabilidade e os Jornais.

• Valores financeiros: os somatórios de receita são calculados sobre valores monetários reais (tratados como BigNumber na agregação) — trate os números como indicadores analíticos, sem arredondar na leitura.
• Escopo dos dados: a agregação cruza ordens gerais + crowdfunding; uma análise que ignore um dos tipos precisa do filtro orderTypes ajustado.

Telas relacionadas

• Dashboard
• Saldos
• Compras automáticas (Dashboard)