Um evento rastreado

O sinal que prova "alguém usou"

A fatia 1 funciona. Antes de seguir, instala um rastreado, que marca o uso central do produto. O funil completo vem no Módulo 4 com PostHog/Plausible reais. Aqui você decide qual ação prova que alguém usou o produto, e escreve o código que sinaliza essa ação quando ela acontece.

Na L07 do Módulo 2, você listou 4 eventos do no docs/roadmap.md (landing_view, signup_started, wedge_consumed, weekly_return). Esta lição implementa um deles: o wedge_consumed. Os outros 3 viram chamadas no Módulo 4 quando o produto for público.

O trabalho central aqui é decidir qual evento medir; a instalação é a parte fácil. E aprender o reflexo de nunca colocar dado pessoal (CPF, email, nome) nas propriedades do evento: LGPD by design.

Por que só um evento agora

Você decidiu 4 eventos no roadmap. Implementar os 4 agora seria fácil, mas seria ruído. Três deles dependem de:

landing_view: você ter landing page pública (Módulo 4)
signup_started: você ter signup (talvez nem tenha na fatia 1)
weekly_return: você ter pelo menos 1 semana de uso real (impossível agora)

Só wedge_consumed é instalável agora com produto rodando local. Ele responde a pergunta-chave: quando o usuário fez a coisa central que o produto promete? No SaaS de recibos, é quando ele emite o primeiro recibo. Pra outro produto, é quando completa a ação que define o valor: o uso em si, e não o login ou o cadastro que vêm antes.

Passo 1 — Crie o helper `analytics`

Cole no Claude:

prompt · text

Cria um helper em `lib/analytics.ts` com:

1. Função `analytics.track(eventName: string, properties?: Record<string, unknown>): void`.
2. Implementação por enquanto: `console.log('[analytics]', eventName, properties)`. **Não instale PostHog/Plausible/Mixpanel ainda** — isso é do Módulo 4. Mantém como no-op deliberado.
3. Exporta como objeto `analytics` com método `track` (e métodos futuros placeholder: `identify`, `page` retornando `void` por enquanto).

Mostre o diff antes de criar. **Não adicione dependência ao package.json.**

A instrução "não instale PostHog" é deliberada: sem ela, o Claude pode propor instalar a lib agora. Você quer decisão de evento sem decisão de stack ainda.

Passo 2 — Chame `analytics.track` no ponto certo

Identifica onde o "wedge consumido" acontece. No exemplo do recibo, é quando a API route retorna 201 (sucesso de criação).

prompt · text

Adicione `analytics.track('', { /* props relevantes */ })` no ponto do código onde a ação central acontece com sucesso. Caso do exemplo: imediatamente antes de retornar 201 na API route da L04.

Propriedades a incluir (depende do recurso):
- ID do registro criado
- Quaisquer dados que ajudem segmentar depois (ex: tipo de cliente, valor agregado em centavos — **nunca dados pessoais**: CPF, nome, email são proibidos)

Mostre o diff antes de aplicar.

EVENTO[EVENTO]— nome do evento (snake_case). Ex: recibo_emitido, contrato_assinado, ordem_criada. Use o que marca uso central do seu produto.

Confirma que a chamada está exatamente onde a ação completa com sucesso. Antes desse ponto, ela registraria só uma "tentativa". Depois dele, você pode perder o sinal se algo quebrar no meio do caminho.

Passo 3 — Verifique no terminal

Roda a app local e submete o formulário (mesma forma da L05). Olha o terminal onde npm run dev está rodando, não o browser nem o DevTools. Como a chamada do analytics.track está num Route Handler, o console.log aparece no servidor. Você deve ver:

saída esperada

[analytics] recibo_emitido { recibo_id: 1, valor_centavos: 10000 }

Cada submit gera uma linha no terminal. Essa linha confirma que a chamada está disparando no ponto certo. No Módulo 4, o console.log vira chamada pro PostHog/Plausible com 1 linha de mudança.

Passo 4 — Documente a decisão

prompt · text

Crie ou atualize o arquivo `docs/analytics.md` com uma seção sobre o evento de wedge_consumed:

# Analytics

## Evento central: nome-do-evento

Quando dispara: descrição em 1 frase de qual ação do usuário.
Por que esse: 1-2 frases explicando por que esse evento marca uso real do produto, não vaidade.
Propriedades: lista das props enviadas e por quê.
O que NÃO mandamos: CPF, nome, email, qualquer PII (LGPD).
Integração real: vem no Módulo 4 (PostHog ou Plausible).

Eventos futuros (do roadmap M2/L07, ainda não implementados):
- landing_view (Módulo 4 — landing pública)
- signup_started (Módulo 4 — quando signup existir)
- weekly_return (Módulo 4 — quando dados de 1 semana existirem)

Mostre o diff antes de aplicar.

Passo 5 — Faça o commit

prompt · text

Faça commit dos 3 arquivos: helper analytics, chamada na route, e docs/analytics.md. Mensagem: `feat(analytics): track <evento> on <ação>` (ex: `feat(analytics): track recibo_emitido on create`).

Build Diary — o CEAP escolheu o que NÃO medir

O PROJECT.md do CEAP tem uma seção "Key Findings" listando 5 descobertas principais, coisas como "6 deputados com HHI extremo," "deputado com ticket médio 4x maior que a média," "empresa de saúde alugando carros." Cada uma tem um "Content angle" (a frase que viraria post/matéria).

Note o que não está nessa lista: contagem de page views, tempo médio no site, taxa de bounce, número de filtros aplicados. Métricas de "vaidade de dashboard" que qualquer ferramenta de analytics produziria automaticamente. O autor não rastreou porque não respondem à pergunta central do produto.

A pergunta central do CEAP é: quais transações merecem investigação? As 5 descobertas atendem essa pergunta. "Quantas pessoas viram o site" não atende.

A regra vale pro evento que você acabou de criar: o evento bom responde à pergunta central do seu produto. Se você só rastrear "alguém criou um recibo," tem contagem agregada. Mas a pergunta real é provavelmente "esse usuário voltou e usou de novo?", e isso requer evento de retorno (que vem no M4), não só de criação.

Por enquanto, com 1 evento, a versão mínima atende: você sabe que alguém atravessou o caminho central. Adicionar mais 3 eventos no M4 vai te dar a história completa.

Takeaways

Instale 1 evento agora em vez dos 4: só wedge_consumed é instalável com produto local. Os outros 3 dependem de contexto (landing, signup, semana de uso) que só existe no M4.
O ponto da chamada importa: depois do sucesso, antes do return. Antes seria tentativa; depois pode perder o sinal se algo quebrar entre os dois.
LGPD by design: nunca CPF/email/nome/telefone nas propriedades. Use IDs internos e agregados.
deliberado: console.log agora, PostHog/Plausible no M4. Não introduz dep nova ainda: decisão de stack é do M4.

Você terminou quando

Cinco coisas:

Helper analytics.track() existe como no-op (sem dependência nova)
Chamada em pelo menos 1 ponto do código onde o uso central acontece
Evento aparece no terminal quando você submete o formulário local
docs/analytics.md documentando a decisão
Tudo commitado

Auto-checagem: você consegue responder?