Base do projeto/docs/analytics-operacao

Analytics - Operação

O projeto agora possui uma camada interna de analytics focada na operação da loja.

Recorte da seçãoBase estrutural do projeto

Nota de referência para contratos, arquitetura, runbook e organização do workspace. É a camada mais estável da documentação.

Atualizado19 de mar. de 2026

Seções15

Tags4

analyticsoperacaoecommerceecommpanel

Papel do módulo

O projeto agora possui uma camada interna de analytics focada na operação da loja.

Ela não substitui Google Tag Manager ou Google Analytics.

Ela existe para responder, dentro do próprio produto:

quantas sessões estão ativas;
quanto tempo as sessões permanecem;
quais páginas recebem mais navegação;
quais buscas e cliques estão acontecendo;
como o carrinho está sendo movimentado;
quantas compras foram concluídas;
qual é a receita, ticket médio e método de pagamento dominante;
quais localizações aparecem com mais frequência.

Onde isso aparece

Painel

Rota:

/ecommpanel/admin/analytics

Essa tela reúne:

visão de sessões ativas e sessões totais;
volume de páginas vistas, buscas e cliques;
compras concluídas, receita e ticket médio;
ranking de páginas, buscas, cliques, pagamentos, localizações e dispositivos;
linha do tempo diária;
eventos recentes;
configuração da coleta interna;
configuração de GTM e GA4.

Loja

O storefront passa a enviar eventos automaticamente durante o uso normal.

Hoje a coleta cobre:

page_view
heartbeat
interaction_click
search_submit
cart_update
checkout_step
purchase_complete

Como a coleta funciona

Persistência

Os eventos agora podem operar em três modos:

files: grava somente em src/data/ecommpanel/analytics/events/YYYY-MM-DD.ndjson;
hybrid: grava no PostgreSQL e mantém os arquivos como espelho/fallback;
database: grava e lê somente do PostgreSQL para o dashboard administrativo.

Em produção, a recomendação passa a ser:

ECOM_ANALYTICS_EVENTS_PERSISTENCE_MODE=database

Os arquivos continuam úteis para desenvolvimento, fallback local e espelhamento operacional.

Configuração administrativa

Arquivo administrativo:

src/data/ecommpanel/analytics/config.json

Modo de persistência:

ECOM_PANEL_SETTINGS_PERSISTENCE_MODE=files: configuração administrativa em arquivo;
ECOM_PANEL_SETTINGS_PERSISTENCE_MODE=hybrid: painel prefere PostgreSQL para a configuração e mantém arquivo/snapshot em sincronia;
ECOM_PANEL_SETTINGS_PERSISTENCE_MODE=database: PostgreSQL vira a fonte administrativa da configuração.

Snapshot publicado para a loja:

src/data/site-runtime/analytics/config.published.json

Se ECOM_CONTENT_PATH estiver configurado, o snapshot publicado passa a ir para a pasta externa equivalente.

O que o storefront rastreia hoje

Navegação e sessão

visualização de página a cada troca de rota;
heartbeat periódico para manter a sessão viva;
cálculo de usuários ativos por janela curta;
cálculo de duração média por sessão.

Interação

cliques em botões, links e elementos interativos;
busca enviada pelo header;
mudanças relevantes no carrinho;
avanço no checkout;
compra concluída no endpoint de checkout.

Comercial

Na conclusão de compra, o sistema armazena:

valor total;
quantidade de itens;
método de pagamento;
custo de frete;
desconto;
localização coarse do pedido quando disponível.

Google Tag Manager e Google Analytics

O painel agora aceita operação sem mudança de código.

A lógica ficou assim:

se as integrações Google estiverem desligadas, nada é injetado;
se GTM estiver habilitado e o container for válido, o script entra no storefront;
se GA4 estiver habilitado e o measurement id for válido, o gtag entra no storefront;
se os IDs estiverem vazios, a publicação desliga automaticamente aquele conector.

Fonte de verdade e projeção

Quando o modo está em database:

o banco passa a ser a fonte correta dos eventos;
o dashboard administrativo consulta o PostgreSQL;
os arquivos deixam de participar da leitura analítica.

Quando o modo está em hybrid:

a leitura do dashboard prefere o PostgreSQL;
os arquivos continuam sendo atualizados;
existe sincronização periódica dos arquivos recentes para o banco.

Limites atuais

o dashboard ainda agrega em memória a partir dos eventos brutos, mesmo quando eles estão no banco;
localizações dependem de headers de borda ou do endereço da compra;
o painel já é útil para operação real, mas ainda não é substituto de data warehouse ou BI;
a próxima evolução natural é separar projeções analíticas mais especializadas por janela e funil.