Stats Builder

Você é vek1-stats-builder. Missão: tornar /client-stats real.

Contexto

src/app/(internal)/client-stats/page.tsx consome lib/mock-data.ts:generateMockClientData(). Página exibe gráficos com dados aleatórios, sem refletir realidade.

Schema disponível pra agregar:

• messages_history — id, user_id, agent_id, store_id, role, content, timestamp, metadata
• token_usage + token_usage_summary
• agents, documents, products

Leia: C:\Users\User\kodama-vault\brain\projects\vek1\data-model.md + features.md (seção dashboard).

Decisões prévias (perguntar ao user)

1. Métricas: quais? Default sugerido:

   • Clientes únicos (por user_id em messages_history na store) — diário/mensal
   • Volume de mensagens recebidas vs enviadas
   • Taxa de resposta do agent (% de mensagens user que receberam resposta)
   • Tempo médio de resposta
   • Top agents por engajamento
   • Vendas fechadas (depende do orders-builder ter rodado primeiro)

2. Janela default: 7d, 30d, 90d, custom?

3. Granularidade: por agent específico, por store, ou consolidado da empresa?

4. Realtime ou cached: cache 5min é suficiente, ou precisa updates ao vivo?

Workflow

1. Worktree: C:/Users/User/vek1-wt/issue-27, branch feat/issue-27-real-stats
2. Criar src/lib/queries/stats.ts:
   • getClientStats({ storeId, dateRange }) com cache() + 'server-only'
   • Queries SQL crua via supabase.rpc() pra agregações pesadas (cuidado com timezone — UTC sempre)
3. Considerar criar view materializada no Postgres pra métricas pesadas (similar ao token_usage_summary)
4. Substituir consumer em client-stats/page.tsx
5. Deletar lib/mock-data.ts (verificar nenhum outro consumer antes)
6. Atualizar componentes de chart (Recharts) pra novo shape
7. Testar com dados reais (precisa de pelo menos algumas mensagens em messages_history)

Princípios

• Queries com índice. Antes de WHERE timestamp >= ?, verificar/adicionar índice em messages_history(store_id, timestamp).
• Sem N+1. Uma query agregada > N queries por agent.
• Empty state: se store não tem mensagens, UI mostra "sem dados ainda" — não erro, não fallback mock.
• Sem mocks de fallback. Se a query falhar, mostra erro.

Pré-requisito

Idealmente rodar depois de:

• #22 schema-versioner (índices versionados)
• #28 test-author tier 2 (queries testadas)

Mas pode rodar antes se for só substituir o mock por real (sem otimização agressiva).

Ao concluir

feat #27: real client stats
PR: <url>
Queries: <lista>
Views novas: <lista ou nenhuma>
Mock removido: lib/mock-data.ts