POP — Relatório de Operação de Agente IA pra Cliente

Status: v1 (vigente desde 2026-05-15) Área: Operacional / Prestação de contas Responsável: Junior (ou quem operar o cliente) Slash command relacionado: ainda não existe (candidato a /relatorio-agente) Validado em: Denise Ramos (1.186 mensagens, 112 leads, jan→mai 2026)

Quando executar

Sempre que precisar mostrar pra um cliente o valor que o agente de IA dele entregou num período. Casos típicos:

• Renovação de contrato chegando: cliente questiona se o agente vale o investimento
• Cliente sumiu nos resultados e precisa enxergar o que aconteceu nos bastidores
• Apresentação de prestação de contas mensal/trimestral
• Onboarding de cliente que acabou de assumir a operação (mostrar baseline)

Não vale pra: relatório técnico interno (use logs do server), relatório de tráfego (use /relatorio-trafego), Boletim de Entregas da agência (use docs/pops/clickup/boletim.md).

Resultado esperado

PDF brand-compliant da Gita, com:

• Logo Grupo Gita (verde escuro) no header
• ID de relatório único formato GTA-RPT-<CLI3>-<YYYYMMDD>-<RAND4> no header e footer de cada página
• Métricas duras: leads únicos, mensagens trocadas, conversas profundas, atuação fora do horário comercial, sinais de qualificação detectados
• Síntese qualitativa: dores, padrões de condução, objeções recorrentes, conversas exemplares — todas com citações textuais reais
• Linguagem cliente-final: sem corporativês, sem jargão técnico, sem em-dash
• Copiado pra ~/Entregas/<cliente>/relatorios-agente/ conforme POP de Entregas

Pré-requisitos

• Acesso ao Supabase onde o agente armazena conversas (varia por cliente — ver tabela abaixo)
• OPENAI_API_KEY configurada em algum .env acessível (atualmente em ~/Projetos/gita-agents/packages/engine/.env)
• Puppeteer + Chrome instalados (rodar npx puppeteer browsers install chrome uma vez)
• Dependências do server/ instaladas (@supabase/supabase-js, puppeteer)

Mapa de fontes de dados por cliente

Cliente	Stack	Supabase	Tabela	Credenciais
Denise	n8n antigo (Gemini)	chihuerkisjvmzxejxhs	Cliente_DENISE_mensagens	~/Projetos/gita-agents/packages/engine/.env
Janaina, Gita Agents	gita-agents (Claude)	cycuvtfxvdblplseyidk	tabela própria do engine novo	/gita/server/.env

Outros clientes que rodam estrutura n8n antiga devem seguir padrão Cliente_<NOME>_mensagens no mesmo Supabase da Denise.

Procedimento

1. Identifica a fonte

• Confirma qual stack o cliente roda (n8n antigo ou gita-agents engine novo)
• Confirma o nome exato da tabela no Supabase correspondente
• Confirma jids de teste interno (Junior, equipe Gita) que devem ser excluídos

Comando útil pra explorar uma tabela nova:

cd /Users/juniormaia/gita/server
env $(grep -E "^SUPABASE_(URL|SERVICE_KEY)=" /Users/juniormaia/Projetos/gita-agents/packages/engine/.env | xargs) \
  node -e "
    const { createClient } = require('@supabase/supabase-js');
    const sb = createClient(process.env.SUPABASE_URL, process.env.SUPABASE_SERVICE_KEY);
    sb.from('NOME_DA_TABELA').select('*', { count: 'exact' }).limit(3).then(r => {
      console.log('count:', r.count);
      console.log('cols:', r.data && Object.keys(r.data[0]));
      console.log('amostra:', JSON.stringify(r.data?.[0], null, 2).slice(0,1500));
    });
  "

2. Adapta o script (se for cliente novo)

Pra um cliente que não é a Denise, clonar server/scripts/relatorio-denise.js pra relatorio-<cliente>.js e ajustar:

Constante	O que muda
TABLE	Nome da tabela no Supabase
CLIENTE	Nome formal usado no relatório (ex: "Dra. Denise Ramos")
AGENTE	Nome do agente como aparece no chat (ex: "Aline (Atendente IA, Grupo Gita)")
JIDS_EXCLUIR	Set de números a excluir (testes internos)
sinaisQualificacao	Heurísticas regex específicas do roteiro do agente (etapas do funil)
prompt da sintetizar()	Contexto do produto/persona/oferta do cliente
gerarReportId()	Sigla do cliente nos 3 caracteres (DEN, JAN, GIT...)

Se o engine novo (gita-agents) tiver schema diferente de mensagens, ajustar também extrairTexto() e o cálculo de role (user/model/tool).

3. Gera o markdown

cd /Users/juniormaia/gita/server

# Tudo (default)
node scripts/relatorio-denise.js

# Últimos 30 dias
node scripts/relatorio-denise.js --dias=30

# Desde data específica
node scripts/relatorio-denise.js --desde=2026-04-01

Saída: outputs/relatorios-clientes/<slug>-<YYYY-MM-DD>.md com Report ID já embutido.

4. Revisa o markdown ANTES do PDF

Checks obrigatórios:

# Em-dashes (banido em material de cliente)
grep "—" outputs/relatorios-clientes/<arquivo>.md && echo "ACHOU em-dash, corrigir antes do PDF"

# Vazamento de jids de teste (procurar nomes/menções internas)
grep -iE "junior|teste|debug|tay\b" outputs/relatorios-clientes/<arquivo>.md

# Citações vazias ou esquisitas
grep -E '""|"[^"]{1,3}"' outputs/relatorios-clientes/<arquivo>.md

Se algo escapou: editar o .md direto (é texto), ou ajustar JIDS_EXCLUIR/regex e rodar de novo. Nunca enviar PDF com em-dash ou nome de teste pro cliente.

5. Gera o PDF

cd /Users/juniormaia/gita/server
node scripts/relatorio-md-to-pdf.js outputs/relatorios-clientes/<arquivo>.md

Saída: PDF no mesmo path, mesmo nome com .pdf. Logo SVG e Report ID já vêm aplicados.

6. Move pra Entregas

Conforme POP de Entregas a Clientes:

mkdir -p ~/Entregas/<cliente>/relatorios-agente
cp outputs/relatorios-clientes/<arquivo>.pdf \
   ~/Entregas/<cliente>/relatorios-agente/relatorio-agente-<nome>-v<N>-<YYYY-MM-DD>.pdf

# Opcional: leva o .md também pra editar futuras versões sem rodar tudo de novo
cp outputs/relatorios-clientes/<arquivo>.md \
   ~/Entregas/<cliente>/relatorios-agente/relatorio-agente-<nome>-v<N>-<YYYY-MM-DD>.md

7. Envia pro cliente

WhatsApp, e-mail ou Drive — a critério. Mensagem-padrão sugerida:

"Oi [Nome], tudo bem? Segue o relatório de operação do seu agente, com os números do período e o que ele entregou. Qualquer dúvida sobre os dados, me chama por aqui. Ah, e me avisa quando der uma lida pra eu saber que chegou. Abraço."

Se for renovação ou follow-up de venda, anexa no CRM (ClickUp #Comercial ou Chatwoot).

Arquitetura dos scripts

relatorio-denise.js (5 etapas)

1. Carregamento: paginação manual no Supabase (1000 por chamada), filtra JIDS_EXCLUIR
2. Métricas determinísticas: agrupa por lead, calcula profundidade/distribuição/sinais de qualificação por regex
3. Amostragem: 12 conversas — 6 profundas (10+ trocas) + 4 médias (4-9) + 2 curtas (1-3)
4. Síntese qualitativa: gpt-4o via fetch direto, temperatura 0.3, max_tokens 4000, prompt com regras anti-alucinação rígidas
5. Montagem do markdown: template com Report ID, tabelas de métricas e blocos da síntese inseridos

relatorio-md-to-pdf.js

• Parser markdown próprio (sem dependência externa): headings, listas, checklists, tabelas, blockquotes, hr
• Extrai Report ID via regex do markdown (**ID do relatório:** XXX)
• Header: logo SVG da Gita lido de data/brand/assets/logos/Grupo Gita Verde Escuro.svg + Report ID
• Cores brand: terracota #803F2E, verde profundo #364636, areia #E2D0B0
• Puppeteer com printBackground: true, A4, margens 18mm/16mm
• Footer com Grupo Gita · <reportId> esquerda + paginação direita

ID de relatório

Formato: GTA-RPT-<CLI3>-<YYYYMMDD>-<RAND4>

Componente	Significado
GTA	Grupo Gita
RPT	Relatório
<CLI3>	Sigla do cliente (3 letras maiúsculas) — DEN, JAN, GIT, KAD, etc.
<YYYYMMDD>	Data de emissão (data local)
<RAND4>	Random base36, 4 chars, garante unicidade entre relatórios do mesmo dia

Exemplos: GTA-RPT-DEN-20260515-KXP4, GTA-RPT-JAN-20260601-A2BX

Esse ID é o que o cliente cita se precisar referenciar o relatório no futuro. Mantém em log pra rastreabilidade.

Boas práticas

• Custos: ~10K tokens de input + 1K de output em gpt-4o por relatório. Ordem de centavos. Não preciso pré-aprovar.
• Cadência: mensal ou trimestral é o sweet spot. Semanal vira ruído.
• Versão v<N>: incrementa só quando o cliente recebe nova versão. Reentrega sem mudança de conteúdo mantém v<N> e atualiza data.
• Não inventar: prompt já é defensivo, mas se você editar o .md à mão, mantenha a regra. Citações sempre com [LEAD] ou [ALINE] na fonte original.
• Não promete resultado: nunca cite conversão de venda sem dado real (não temos integração com Kiwify ainda). Sinais de qualificação (envio de checkout, antes/depois) são proxy aceitável.
• Privacidade: jamais expor números de telefone (jids) no PDF. Já está controlado no template, mas conferir se algum jid vazou em citações.

Troubleshooting

Sintoma	Causa provável	Solução
Could not find Chrome no Puppeteer	Chrome do Puppeteer não instalado	npx puppeteer browsers install chrome
Cannot find module '@supabase/supabase-js'	CWD errado, fora de server/	cd /Users/juniormaia/gita/server antes de rodar
ANTHROPIC_API_KEY ausente	Tentou Claude local	Use gpt-4o (padrão) ou rota do server prod
Tabela Cliente_X_mensagens não encontrada	.env aponta pro Supabase errado	Conferir mapa de fontes acima, usar .env do engine antigo pra clientes n8n
Em-dash no PDF	Modelo escapou da regra	Editar .md à mão (sed -i '' 's/—/, /g') e reconverter; reportar caso de fuga no prompt
Relatório vazio	Filtro de data zerou tudo, ou JIDS_EXCLUIR zerou tudo	Conferir --dias/--desde; testar sem o filtro de excluir

Próximas evoluções

• Slash command /relatorio-agente que pergunta cliente + período e roda tudo
• Quando engine novo (gita-agents) tiver mais clientes em produção, generalizar o script: 1 só com --cliente=<slug> lendo configs de data/products/<cliente>/relatorio-config.json
• Integrar dado de Kiwify (quando houver webhook) pra incluir conversões reais, não só "envio de checkout"
• Gráficos no PDF (distribuição por dia, heatmap horário) via Chart.js ou Vega-Lite renderizado no Puppeteer

Histórico

Data	Versão	Mudança	Autor
2026-05-15	v1	POP criado, validado em Denise (1.186 msgs, 112 leads)	Junior + Gi