# Cacalutia Leads (nome provisório) · Planejamento v2.1

Documento de contexto para o Claude Code. Leia inteiro antes de qualquer ação.

## O que mudou da v1 para a v2

A v2 incorpora proteções operacionais e de conduta do agente: regra de afirmações verificadas por cliente, guarda de envio antes de cada mensagem, lista de não contato permanente, trava de propriedade da conversa entre agente e gerente, estados de funil e de conversa separados, taxonomia de intenções, teto de custo de IA com pausa, circuit breaker, jobs duráveis no banco, módulo de experimentos, níveis de ativação por cliente (simulação, ensaio, piloto, autonomia), critérios de aceite com evidência e um novo módulo interno: o copiloto de prospecção para a Cacalutia vender os próprios pacotes. A v2.1 adiciona a direção de design e interface (seção 16), com o arquivo referencia-visual.html como referência.

## 1. Visão

Serviço de geração de leads B2B com garantia de entrega, operado por uma plataforma própria. A Cacalutia investe a mídia (Meta Ads e Google Ads) com o próprio dinheiro, capta os leads, enriquece os dados, qualifica cada lead com agentes de IA via WhatsApp e entrega ao vendedor do cliente apenas os leads que cumprem critérios objetivos definidos em contrato.

O cliente compra um pacote mensal com quantidade mínima garantida de leads qualificados. A dor que resolvemos: o cliente não quer mais investir em tráfego sem saber se vai ter retorno.

Nicho inicial: indústrias de terceirização de cosméticos (private label). Futuro: automotivo e outros nichos B2B de ticket alto.

Operação humana: uma gerente de contas supervisiona os agentes de IA, assume conversas quando necessário e cuida da relação com os clientes. O sistema deve permitir que uma pessoa gerencie de 8 a 12 clientes.

Princípio de canal: a plataforma trabalha só com leads que levantaram a mão (anúncio, formulário, mensagem iniciada pelo lead). Não existe envio frio automatizado, nem automação de navegador em Instagram ou WhatsApp.

## 2. Modelo de negócio que o sistema precisa respeitar

A métrica central do negócio é o custo por lead qualificado (CPLQ) de cada cliente em cada ciclo. CPLQ = CPL bruto / taxa de qualificação. Toda a plataforma existe para manter o CPLQ abaixo do teto do pacote e mostrar isso em tempo real.

Teto de CPLQ para uma margem alvo:

```
disponivel = preco_pacote × (1 − imposto_faturamento − margem_alvo) − custos_fixos_cliente
teto_cplq = (disponivel / leads_garantidos − custo_ia_por_lead_bruto / taxa_qualificacao)
            / (1 + parcela_verba_meta × 0,1215)
```

Observações: a Meta cobra 12,15% de impostos sobre a mídia desde jan/2026 (o Ads Manager mostra o valor sem imposto, a fatura vem com imposto). O Google absorve. Como a Cacalutia compra a mídia, o valor total do pacote é faturamento da Cacalutia.

Pacotes iniciais (cosméticos, valores a validar com piloto):

| Pacote | Leads qualificados/ciclo | Preço | Preço por lead |
|---|---|---|---|
| Essencial | 30 | R$ 15.000 | R$ 500 |
| Crescimento | 50 | R$ 23.500 | R$ 470 |
| Escala | 80 | R$ 36.000 | R$ 450 (só após 60 dias de dados) |

Regras comerciais que viram regra de sistema: taxa de implantação; contrato mínimo de 3 meses; pagamento antecipado; garantia de entrega com prazo (saldo não entregue passa para o ciclo seguinte, sem reembolso); contestação em até 48h com motivos pré-definidos; leads B entregues como bônus e não contam na garantia.

## 3. Glossário e estados

Cada definição abaixo existe em UM único service. Nenhuma tela, relatório ou query pode reimplementar essas regras. Valores internos em inglês, interface em português.

### 3.1 Status do lead (funil)

| Valor interno | Na interface | Definição |
|---|---|---|
| `received` | Recebido | Lead bruto recebido por formulário, Lead Ads, Click-to-WhatsApp ou landing page |
| `duplicate` | Duplicado | Mesmo telefone, e-mail ou CNPJ do mesmo cliente dentro da janela configurada (padrão 90 dias) |
| `qualifying` | Em qualificação | Lead válido em conversa com o agente ou com a gerente |
| `qualified_a` | Qualificado | Cumpriu todos os critérios obrigatórios do ICP, pela regra determinística |
| `qualified_b` | Bônus | Cumpriu parte dos critérios. Entregue como bônus, não conta na garantia |
| `discarded` | Descartado | Não cumpriu critérios mínimos, contato inválido ou sem resposta após as tentativas |
| `delivered` | Entregue | Lead A enviado ao cliente, com data e hora registradas |
| `disputed` | Contestado | Cliente contestou em até 48h com motivo pré-definido. Gerente decide |
| `accepted` | Aceito | Entregue e não contestado em 48h, ou contestação negada. É o que conta na garantia |

Ciclo: período de apuração do pacote (mensal), com saldo transferível.

### 3.2 Estado da conversa (canal)

Campo separado do status do lead. Um lead pode estar `qualifying` com a conversa `paused`, por exemplo.

| Valor interno | Na interface | Definição |
|---|---|---|
| `pending_first_contact` | Aguardando primeiro contato | Lead entrou, primeira mensagem ainda não saiu |
| `waiting_reply` | Aguardando resposta | Mensagem enviada, lead não respondeu |
| `window_open` | Janela aberta | Lead respondeu, janela de 24h (ou 72h CTWA) ativa |
| `window_closed` | Janela fechada | Só template aprovado pode ser enviado |
| `paused` | Pausada | Pausa manual, por circuit breaker ou por orçamento |
| `do_not_contact` | Não contatar | Opt-out. Estado terminal |
| `completed` | Concluída | Conversa encerrada (entregue, descartado ou sem resposta final) |

### 3.3 Propriedade da conversa

Campo `owner` com valores `agent`, `human` ou `none`. Só o dono envia. A troca de dono é uma transação atômica gravada em `audit_log`.

Quando a gerente clica em assumir, `owner` vira `human` e o agente fica bloqueado de enviar naquela conversa, inclusive follow-ups já agendados (cancelados na mesma transação). Ao devolver, `owner` volta para `agent` e o agente recebe um resumo do que a gerente conversou antes de continuar.

## 4. Reaproveitamento do Cacalutia One

Decisão: este é um app separado (pasta própria, banco próprio, processo PM2 próprio), não um módulo dentro do One. Motivos: produto diferente, receita crítica (lead perdido vira prejuízo por causa da garantia), dados pessoais sob LGPD e risco de uma mudança quebrar o One.

Reaproveitar do One (copiando e adaptando os services, ou extraindo para pacote compartilhado, a definir após auditoria):

| Componente do One | Uso no novo projeto |
|---|---|
| OAuth e sync Meta Ads | Gastos, campanhas, conjuntos e anúncios por cliente |
| OAuth e sync Google Ads | Gastos, campanhas, palavras-chave por cliente |
| GA4 | Funil das landing pages |
| Auth, roles, middleware | Papéis: admin (Bruno), gerente de contas, cliente, vendedor do cliente |
| Padrão multi-tenant por client_id | Mesmo padrão |
| Estrutura routes/ services/ | Mesmo padrão |
| Proteção de sync contra duplicação | Mesmo padrão |
| Deploy PM2 e fluxo STATUS.md / AUDITORIA.md | Mesmo padrão |

Stack: manter a do One (Node.js + Express + React + MySQL + PM2) para maximizar reaproveitamento. Convenção de idioma: interface 100% em português (menus, botões, alertas, erros, datas, números); código, banco, status internos, logs, testes e documentação técnica em inglês; manual da gerente em português.

Antes de escrever código, o Claude Code deve auditar o One e gerar REAPROVEITAMENTO.md listando arquivo por arquivo o que pode ser reaproveitado, o que precisa adaptar e o que não serve.

## 5. Regras de afirmação e de contato

### 5.1 Afirmações verificadas por cliente

Cada cliente tem uma lista de afirmações na tabela `client_claims`, com status `verified` ou `pending`. Afirmação verificada precisa de evidência (documento, link oficial ou aprovação registrada do cliente) e de quem aprovou.

Exemplos para uma fábrica de cosméticos: registro na Anvisa, certificação ISO, pedido mínimo por produto, prazo médio de desenvolvimento, categorias que fabrica, se desenvolve fórmula exclusiva, região atendida.

O agente só pode afirmar o que está `verified`, sem paráfrase que mude o sentido. Tudo `pending` fica bloqueado até ser comprovado. O agente nunca inventa ou negocia preço, desconto, prazo, condição de pagamento, garantia de resultado ou superlativo ("melhor", "maior", "mais barato"). Pergunta sobre isso vira handoff para o vendedor ou para a gerente.

Nunca fingir ser humano quando perguntado diretamente, nunca fingir ser cliente e nunca usar informação falsa para conseguir resposta.

### 5.2 Guarda de envio

Toda mensagem que sai pela plataforma, do agente ou da gerente, passa por um único service de envio. Antes de enviar, ele verifica nesta ordem:

1. O lead não está em `do_not_contact`.
2. Quem está enviando é o `owner` atual da conversa.
3. Cliente, conversa e agente não estão pausados (manual, circuit breaker ou orçamento).
4. A janela do WhatsApp permite mensagem livre, ou a mensagem é um template aprovado.
5. Não houve envio idêntico para o mesmo lead nos últimos minutos (trava de duplicidade).
6. Para mensagens do agente: validação de afirmações aprovada (seção 5.4).
7. O nível de ativação do cliente permite envio real (em `dry_run`, a mensagem é gravada como sugestão e não sai).

Qualquer item falhou: não envia, grava o motivo e manda para a fila de exceções. Nunca existe caminho alternativo para contornar um bloqueio.

### 5.3 Lista de não contato

Detectada a intenção `opt_out`, numa única transação: o telefone e o e-mail entram em `do_not_contact`, a conversa vai para o estado `do_not_contact`, todos os follow-ups agendados são cancelados e sai uma única mensagem de confirmação ("tudo bem, não vamos mais te enviar mensagens"). Depois disso, nenhuma mensagem proativa, de nenhum cliente da Cacalutia, por nenhum canal.

Exceção controlada: se a mesma pessoa, depois, preencher um novo formulário ou mandar mensagem por conta própria, isso gera um novo registro de consentimento, mas o lead vai direto para a fila da gerente e o agente não aborda sem liberação humana.

### 5.4 Validação de afirmações

Duas camadas antes de cada mensagem do agente sair. Primeira: regras determinísticas que bloqueiam valores em reais, prazos numéricos, termos de garantia e superlativos não verificados. Segunda: o modelo rápido classifica cada frase afirmativa, associando a uma `client_claims` verificada ou marcando como não suportada. Mensagem reprovada é regenerada uma vez com o motivo; reprovou de novo, vai para a fila da gerente. Toda reprovação fica registrada.

## 6. Módulos

### 6.1 Captação

Fontes: Meta Lead Ads (webhook leadgen), Click-to-WhatsApp (webhook do WhatsApp Cloud API), landing pages próprias com formulário (capturando UTM, gclid, fbclid e consentimento LGPD com texto e data registrados) e formulários de lead do Google Ads (webhook).

Regra crítica: todo evento de entrada é gravado cru na tabela `inbound_events` ANTES de qualquer processamento. O webhook verifica assinatura, responde rápido e o processamento acontece em job durável (seção 8). A captação nunca para: pausa de agente, orçamento estourado ou circuit breaker só mudam para onde o lead vai (fila humana), nunca impedem o lead de ser gravado.

### 6.2 Enriquecimento

Consulta de CNPJ (situação cadastral, data de abertura, CNAE, capital social, porte, cidade e UF) via API pública ou paga, a definir entre BrasilAPI, ReceitaWS, CNPJá ou similar. Validação de telefone e e-mail. Deduplicação. Captura de site e Instagram quando o lead informar. Cada consulta externa grava custo em `cost_ledger`.

### 6.3 Agente de qualificação (IA)

Canal: WhatsApp Cloud API. Modelo: API da Anthropic, com nomes exatos dos modelos fixados no `.env` (`ANTHROPIC_MODEL` para conversa e decisão, `ANTHROPIC_MODEL_FAST` para classificação e extração). Sem alias flutuante, para a qualidade do agente não mudar sozinha.

Cada cliente tem um roteiro versionado: perguntas obrigatórias e opcionais, ordem, respostas válidas, tom de voz, nome do assistente e as afirmações verificadas da seção 5.1. Primeira mensagem ao lead em até 1 minuto após a entrada.

Contexto de cada chamada: dados do formulário e do enriquecimento, histórico completo da conversa, etapa atual, roteiro vigente, afirmações verificadas e variante de experimento atribuída.

Divisão de responsabilidades: a IA conversa, interpreta e extrai as respostas em JSON estruturado. A decisão de qualificação é regra determinística em código, versionada, aplicada sobre esse JSON. A IA nunca decide sozinha se o lead conta na garantia.

Intenções classificadas a cada mensagem do lead:

| Valor interno | Significado | Ação padrão |
|---|---|---|
| `interested` | Demonstra interesse | Seguir roteiro |
| `asked_info` | Pediu informação | Responder só com afirmação verificada, senão handoff |
| `asked_pricing` | Pediu preço ou condição | Explicar que o consultor passa valores; seguir qualificação |
| `wants_salesperson` | Quer falar com vendedor já | Acelerar perguntas obrigatórias e entregar |
| `not_decision_maker` | Não é quem decide | Perguntar quem decide e se pode apresentar |
| `will_forward` | Vai repassar a alguém | Registrar e agendar follow-up |
| `objection` | Objeção | Tratar com afirmação verificada ou handoff |
| `out_of_scope` | Busca algo que o cliente não faz | Descartar com cordialidade |
| `not_interested` | Sem interesse | Encerrar sem insistir |
| `opt_out` | Pediu para parar | Fluxo da seção 5.3, imediato |
| `ambiguous` | Não deu para entender | Uma pergunta de esclarecimento, depois handoff |
| `needs_human` | Irritação, reclamação, tema sensível, pediu humano | Handoff imediato |

Ações possíveis do agente: responder, perguntar, apresentar informação verificada, tratar objeção, agendar follow-up, entregar lead, encerrar, escalar para humano. O agente emite ações estruturadas; o sistema valida cada uma antes de executar.

Follow-ups automáticos com templates aprovados quando o lead para de responder (quantidade, intervalo e janela de horário configuráveis por cliente, padrão 08:00 às 20:00 no fuso America/Sao_Paulo). Mensagens agrupadas: uma mensagem completa em vez de várias curtas, já que a partir de out/2026 a Meta cobra mensagens de serviço acima de 1.000 por número por mês. Conversas vindas de Click-to-WhatsApp têm janela gratuita de 72h.

O agente é focado exclusivamente no atendimento comercial do cliente (as regras do WhatsApp Business não permitem assistentes de IA de uso geral).

Exemplo de roteiro para terceirização de cosméticos:

| Pergunta | Uso no score |
|---|---|
| Que tipo de produto quer fabricar (capilar, skincare, maquiagem, perfumaria, corporal) | Aderência ao portfólio da fábrica |
| Já tem marca e CNPJ ou vai abrir | Obrigatório: tem ou vai abrir em até X meses |
| Onde pretende vender (loja própria, e-commerce, salões, revenda, marketplace) | Informativo |
| Faixa de investimento para o primeiro lote | Obrigatório: acima do mínimo do cliente |
| Prazo para lançar | Obrigatório: dentro do prazo aceito |
| Fórmula exclusiva ou catálogo da fábrica | Informativo |
| Quantidade estimada por produto | Comparar com pedido mínimo da fábrica |
| Cidade e UF | Filtro de região, se houver |

### 6.4 Central da gerente de contas

Inbox em tempo real com todas as conversas, filtros por cliente, status do lead, estado da conversa e dono. Botões de assumir e devolver (seção 3.3). Pausar agente por lead, por cliente ou geral (botão de pausa geral sempre visível). Fila de exceções com prioridade: handoffs, bloqueios da guarda de envio, reprovações de afirmação, leads com opt-out que voltaram, falhas de integração. Em nível `dry_run`, a gerente vê as mensagens sugeridas pelo agente e envia, edita ou descarta.

Editor de roteiros, critérios de ICP e afirmações com versionamento e aprovação. Auditoria por amostragem com nota de qualidade da conversa. Métricas dos agentes: tempo até primeira resposta, taxa de resposta, taxa de qualificação, abandono, handoffs, opt-outs, reprovações de afirmação. Log de decisões da IA legível (intenção detectada, ação escolhida, motivo).

Toda ação da gerente e do agente vai para `audit_log`.

### 6.5 Entrega ao cliente

Cada lead A é entregue com resumo gerado pela IA, respostas do roteiro e dados enriquecidos. Canais: WhatsApp do vendedor do cliente, e-mail, portal do cliente e, na fase 3, CRMs (RD Station, Pipedrive, HubSpot, Kommo). A data e hora da entrega é a fonte da verdade para a garantia e para a janela de contestação.

### 6.6 Portal do cliente

Contador de leads aceitos vs garantidos no ciclo, com saldo. Lista de leads com detalhes. Contestação em até 48h escolhendo motivo pré-definido (contato inválido, duplicado, fora do ICP com evidência). Feedback do vendedor por lead: contatado, reunião, proposta, fechou, valor do pedido. Cadastro das afirmações da fábrica com envio de evidência, que a Cacalutia aprova antes de virarem `verified`.

### 6.7 Cockpit financeiro e de garantia (interno, só admin)

Por cliente e por ciclo: receita, mídia Meta com imposto de 12,15%, mídia Google, IA (de `ai_calls`), WhatsApp, enriquecimento, rateios fixos, lucro e margem em tempo real. CPLQ real vs teto. Pacing: projeção de atingimento da garantia até o fim do ciclo, com alerta quando estiver abaixo do ritmo necessário. Custo de IA por lead bruto, por lead qualificado e por venda. Simulador de pacotes usando a fórmula da seção 2.

Todos esses números saem de `cost_ledger`, `ai_calls` e dos status do glossário, calculados em um único service.

### 6.8 Conversões offline

Enviar de volta para as plataformas os eventos de lead qualificado e de venda: Meta via Conversions API (otimização por leads de conversão) e Google Ads via importação de conversões offline ou conversões otimizadas para leads. Objetivo: as campanhas passarem a otimizar por qualidade, não por volume de formulário. Principal alavanca para baixar o CPLQ.

### 6.9 Experimentos

Tabelas `experiments`, `experiment_variants` e `experiment_assignments`. Variáveis testáveis: mensagem de abertura, ordem das perguntas opcionais, tom, cadência e horário de follow-up, formato do resumo entregue ao vendedor. Criativos e landing pages também podem ser registrados como experimento para medir qualidade, não só CPL.

Regras: uma variável por vez; distribuição controlada com grupo de controle; tamanho mínimo de amostra registrado antes de começar; proibido declarar vencedor antes da amostra; aumento gradual da variante campeã; uma fatia pequena sempre testando hipótese nova; todo experimento comparável e reversível.

Prioridade de métrica por cliente, da mais forte para a mais fraca: venda fechada (e valor) → proposta → reunião → lead aceito → lead qualificado → resposta ao agente.

Limites da autonomia: a IA pode ajustar sozinha a redação dentro do roteiro aprovado, variantes de mensagem e horários de follow-up dentro da janela permitida. Exigem aprovação humana e nova versão: critérios de ICP, regra de score, perguntas obrigatórias, afirmações, limites operacionais, orçamento e qualquer coisa que afete a contagem da garantia.

### 6.10 Copiloto de prospecção (uso interno da Cacalutia)

Objetivo: ajudar Bruno e a gerente a vender pacotes para fábricas de cosméticos. Poucos alvos, B2B, ticket alto. O sistema pesquisa e escreve; um humano revisa e envia.

Descoberta: importação de lista (CSV), cadastro manual e busca por CNAE 2063-1/00 (fabricação de cosméticos, perfumaria e higiene pessoal) e UF, via fornecedor de dados de CNPJ que permita essa busca (a definir). Enriquecimento: dados do CNPJ e leitura do site público da empresa. Campo manual para sinais que o operador verifica por conta própria, como se a fábrica já anuncia (Biblioteca de Anúncios da Meta) e perfil do Instagram.

Pontuação do prospect: porte, tempo de empresa, se atende private label, presença digital, se já investe em anúncios, região.

Abordagem: a IA gera uma abertura curta e personalizada com base no site e nos dados reais, respeitando as afirmações verificadas da própria Cacalutia (resultados de pilotos só entram depois de comprovados). O operador revisa, copia e envia manualmente pelo canal que escolher. O sistema oferece botões de copiar texto e abrir o link, mas nunca envia, nunca automatiza navegador e nunca coleta dados de redes sociais automaticamente.

Pipeline próprio: `prospect` (Prospect) → `contacted` (Abordado) → `replied` (Respondeu) → `meeting` (Reunião) → `proposal` (Proposta) → `won` (Cliente) ou `lost` (Perdido). Ao marcar `won`, o sistema cria o registro em `clients` e o rascunho do `contract`. Follow-ups são tarefas com lembrete para o operador, não envios automáticos. A mesma lista `do_not_contact` vale aqui. Dados pessoais mínimos: nome e cargo do contato comercial, nada além do necessário.

## 7. Fluxo principal

```
Anúncio (Meta / Google / CTWA)
  -> webhook (assinatura verificada) ou landing page
  -> inbound_events (payload cru gravado)
  -> job durável
  -> normalização + deduplicação + checagem do_not_contact
  -> enriquecimento (CNPJ, telefone, e-mail)
  -> atribuição de variante de experimento
  -> agente gera mensagem
  -> guarda de envio (seção 5.2) -> [bloqueado: fila de exceções]
  -> WhatsApp: template inicial ou resposta ao CTWA
  -> lead responde -> classificação de intenção
       -> opt_out: fluxo 5.3
       -> needs_human: owner = human, fila da gerente
       -> demais: agente coleta respostas (JSON estruturado)
  -> regra determinística de score
       -> A: entrega ao cliente
       -> B: entrega como bônus
       -> descartado
       -> exceção: fila da gerente
  -> janela de contestação 48h
  -> aceito (conta na garantia)
  -> feedback do vendedor
  -> conversão offline para Meta e Google
  -> resultado alimenta experimentos
```

## 8. Proteções operacionais

### 8.1 Jobs duráveis

Tabela `jobs` no MySQL (sem Redis, a menos que já exista no servidor): tipo, payload, status (`pending`, `running`, `done`, `failed`, `dead`), tentativas, próxima execução, bloqueio com expiração. Worker em processo PM2 separado do servidor web. Retry com limite e backoff; esgotou, vai para `dead` e aparece na fila de exceções. Idempotência por chave única em webhooks, jobs e envios. Após reinício, jobs `running` com bloqueio expirado voltam para `pending` sem duplicar efeito.

### 8.2 Orçamento de IA

Toda chamada grava em `ai_calls`: cliente, lead, modelo, tokens de entrada e saída, custo estimado em reais, finalidade e duração. Antes de cada chamada, o worker confere o teto mensal global (`AI_MONTHLY_BUDGET_BRL`) e o teto do cliente (definido no contrato). Atingiu: pausa o agente naquele escopo, novos leads e conversas vão para a fila da gerente e dispara alerta. A captação continua.

### 8.3 Circuit breaker

Gatilhos avaliados por cliente e globalmente, com limiares configuráveis no painel:

1. Taxa de opt-out acima do limite nas últimas 24h.
2. Queda na classificação de qualidade do número de WhatsApp ou redução do limite de mensagens (webhook de qualidade do número).
3. Aumento de bloqueios ou denúncias.
4. Taxa de erro anormal em webhooks, na API do WhatsApp ou na API da Anthropic (inclusive JSON inválido).
5. Campanha gastando sem nenhum webhook de lead recebido há X horas.
6. Envio duplicado detectado.
7. Validação de afirmações reprovando acima do limite (sinal de roteiro ou modelo com problema).
8. Divergência de dados (exemplo: lead contado como entregue sem registro em `deliveries`).

Disparou: pausa o agente no escopo afetado, leads seguem para a fila humana, alerta no painel e por WhatsApp ou e-mail para Bruno e para a gerente. Retomada só manual, com registro de quem retomou e por quê.

## 9. Modelo de dados inicial (proposta, revisar após auditoria)

```
clients              empresa cliente, nicho, status, activation_level
                     (simulation | dry_run | pilot | autonomous)
contracts            client_id, pacote, preço, leads_garantidos, taxa_implantacao,
                     início, fim, margem_alvo, ai_budget_brl
cycles               contract_id, período, garantidos, saldo_anterior, aceitos, status
icp_criteria         client_id, versão, critérios (JSON), aprovado_por, vigente_desde
agent_scripts        client_id, versão, perguntas, tom, aprovado_por, vigente_desde
client_claims        client_id, texto, status (verified | pending), evidência,
                     aprovado_por, aprovado_em
ad_accounts          client_id, plataforma, account_id (reuso do One)
campaigns            reuso do One
inbound_events       fonte, idempotency_key, payload_cru, recebido_em,
                     processado_em, erro
leads                client_id, fonte, campanha, utm, gclid, fbclid, nome, telefone,
                     email, cnpj, status, score, consentimento_texto, consentimento_em
do_not_contact       telefone, email, origem (lead_id ou prospect_id), motivo, criado_em
lead_enrichment      lead_id, fonte, dados (JSON), consultado_em
conversations        lead_id, canal, número, state, owner, owner_desde,
                     janela_expira_em, paused_reason
messages             conversation_id, direção, autor (agent | human | lead), conteúdo,
                     status (sent | suggested | blocked), motivo_bloqueio,
                     categoria_whatsapp, idempotency_key, enviado_em
intent_classifications message_id, intent, confiança, ação_escolhida, motivo
qualification_answers lead_id, pergunta, resposta_bruta, valor_extraído, confiança
claim_checks         message_id, aprovado, frases_reprovadas (JSON)
lead_scores          lead_id, icp_versão, resultado, detalhes (JSON)
handoffs             lead_id, motivo, aberto_em, resolvido_em, resolvido_por
deliveries           lead_id, canal, entregue_em, ciclo_id
disputes             lead_id, motivo, aberto_em, decisão, decidido_por
sales_feedback       lead_id, etapa, valor, atualizado_em
offline_conversions  lead_id, plataforma, evento, enviado_em, resposta
experiments          client_id, variável, hipótese, amostra_mínima, status, vencedora
experiment_variants  experiment_id, nome, conteúdo (JSON), peso
experiment_assignments lead_id, variant_id, atribuído_em
ai_calls             client_id, lead_id, modelo, tokens_in, tokens_out, custo_brl,
                     finalidade, duração_ms, criado_em
cost_ledger          client_id, ciclo_id, tipo (mídia, imposto_meta, ia, whatsapp,
                     enriquecimento, fixo), valor, referência, data
jobs                 tipo, payload, status, tentativas, próxima_execução,
                     locked_until, idempotency_key, último_erro
breaker_events       escopo (global | client_id), gatilho, valor_medido, limiar,
                     disparado_em, retomado_em, retomado_por, motivo_retomada
prospects            razão_social, cnpj, site, uf, score, status, sinais (JSON)
prospect_contacts    prospect_id, nome, cargo, canal_comercial
prospect_activities  prospect_id, tipo, mensagem_sugerida, mensagem_enviada,
                     feito_por, feito_em, próximo_lembrete
audit_log            ator, ação, entidade, antes, depois, data
```

## 10. Regras de arquitetura (nunca violar)

1. Uma única definição de cada status e estado, em um único service.
2. Custos, lucro, margem e CPLQ calculados em um único service, a partir de `cost_ledger` e `ai_calls`.
3. Nenhum lead pode se perder: gravar cru primeiro, processar em job durável, com retry, dead-letter e alerta. A captação nunca é pausada.
4. Toda mensagem passa pelo mesmo service de envio e pela guarda da seção 5.2. Não existe envio por fora dele.
5. Só o `owner` da conversa envia. Troca de dono é atômica.
6. `do_not_contact` é checado antes de qualquer envio, em qualquer módulo, inclusive no copiloto de prospecção.
7. O agente só afirma o que está em `client_claims` com status `verified`.
8. A IA coleta e interpreta; a decisão de qualificação é regra determinística versionada.
9. Mudança de roteiro, ICP ou afirmações cria nova versão; leads antigos mantêm a versão com que foram avaliados.
10. Toda query filtra por client_id. Regra de negócio só em services/, nunca em routes/.
11. Toda ação de agente e de humano vai para `audit_log`.
12. Dados pessoais: consentimento registrado, acesso por papel, tokens de clientes criptografados no banco, política de retenção definida.
13. Segredos só no `.env` do servidor. Nunca em arquivos .md, commits, logs ou prints. Logs estruturados sem token.
14. Nenhum bloqueio (API, janela, orçamento, breaker) é contornado por caminho alternativo. Bloqueou, registra e escala.
15. Código escrito não é sucesso. Testar de verdade e mostrar evidência antes de reportar algo como pronto ou corrigido.

## 11. Integrações, permissões e .env

| Integração | Uso | Observação |
|---|---|---|
| Meta Graph API | Lead Ads, gastos, Conversions API | Novas permissões (leads_retrieval, pages_manage_metadata, ads_read ou ads_management, business_management) exigem nova App Review |
| WhatsApp Cloud API | Agente de qualificação | whatsapp_business_messaging e whatsapp_business_management. Definir se o número fica na WABA do cliente (Embedded Signup) ou da Cacalutia. Assinar webhook de qualidade do número |
| Google Ads API | Gastos, webhook de formulário, conversões offline | Verificar nível de acesso do developer token atual |
| API da Anthropic | Agente, validação de afirmações, resumo do lead, copiloto | Modelos fixados no `.env`; toda chamada em `ai_calls` |
| API de CNPJ | Enriquecimento e busca por CNAE no copiloto | Escolher fornecedor após teste de cobertura e custo |
| CRMs | Entrega (fase 3) | RD Station, Pipedrive, HubSpot, Kommo |

Gerar `.env.example` com, no mínimo: `DATABASE_URL`, `APP_URL`, `ENCRYPTION_KEY`, `ANTHROPIC_API_KEY`, `ANTHROPIC_MODEL`, `ANTHROPIC_MODEL_FAST`, `AI_MONTHLY_BUDGET_BRL`, `META_APP_ID`, `META_APP_SECRET`, `META_WEBHOOK_VERIFY_TOKEN`, `WHATSAPP_SYSTEM_USER_TOKEN`, `GOOGLE_OAUTH_CLIENT_ID`, `GOOGLE_OAUTH_CLIENT_SECRET`, `GOOGLE_ADS_DEVELOPER_TOKEN`, `CNPJ_API_KEY`, `OPERATING_TIMEZONE`, `ALERT_EMAIL`, `ALERT_WHATSAPP_NUMBER`. Tokens de cada cliente ficam criptografados no banco, não no `.env`. Validar variáveis obrigatórias na inicialização.

## 12. Infraestrutura

A VPS atual é compartilhada (8GB de RAM, WooCommerce com 50 mil SKUs, site com malware em quarentena, MySQL 5.7). Este projeto guarda dados pessoais e é crítico para a receita. Avaliar com o Bruno: servidor separado ou, no mínimo, conta isolada. Preferir MySQL 8 para o banco novo se o ambiente permitir. Backup diário automático do banco com procedimento de restauração testado e documentado. Monitoramento do worker, dos webhooks e da fila `dead`. Um comando único documentado para subir servidor web e worker.

## 13. Testes e níveis de ativação

Testes automatizados obrigatórios: deduplicação de lead; transições de status e de estado da conversa; troca de dono e bloqueio de envio do agente quando `owner = human`; guarda de envio (cada um dos 7 itens); opt-out cancelando follow-ups e bloqueando todos os módulos; validação de afirmações reprovando preço, prazo e afirmação `pending`; idempotência de webhook e de envio; recuperação de jobs após reinício; expiração de janela do WhatsApp; corte por orçamento; cada gatilho do circuit breaker; atribuição de experimento; cálculo de CPLQ e margem.

Simulador de conversas com personas, rodado a cada nova versão de roteiro antes de ativar: lead qualificado ideal, curioso sem investimento, pede preço logo de cara, não é o decisor, vai repassar, irritado, pede para parar, fora do escopo, responde em áudio ou de forma confusa. A versão só pode ser ativada se passar em todas.

Níveis de ativação por cliente (campo `activation_level`):

1. `simulation`: webhooks e WhatsApp simulados, personas, nenhum lead real.
2. `dry_run`: leads reais entram e são gravados, o agente gera as mensagens, mas nada sai automaticamente. A gerente envia, edita ou descarta cada sugestão pela central.
3. `pilot`: agente envia sozinho com teto diário de conversas novas, só após autorização explícita registrada (quem autorizou e quando).
4. `autonomous`: operação normal, sempre dentro dos limites, orçamento e breakers.

Subir de nível é ação manual registrada. Qualquer breaker pode rebaixar o cliente para `dry_run` automaticamente.

## 14. Roadmap e critérios de aceite

Fase 0, validação (sem código): levantar histórico de CPL, taxa de qualificação e fechamento das fábricas já atendidas; definir ICP padrão de cosméticos; fechar 1 ou 2 clientes piloto (venda manual).

Fase 1, MVP: captação por Meta Lead Ads, landing page e Click-to-WhatsApp; jobs duráveis; agente de WhatsApp com roteiro por cliente, intenções e afirmações verificadas; guarda de envio; lista de não contato; trava de dono; central da gerente com inbox, assumir, pausa geral e fila de exceções; níveis `simulation`, `dry_run` e `pilot`; orçamento de IA e circuit breaker básico (opt-out, erros, qualidade do número, lead parado); entrega por WhatsApp ao vendedor; contador de garantia; cockpit com mídia, custos e CPLQ.

A Fase 1 só está concluída quando demonstrar, com evidência:

1. Lead de teste do Meta Lead Ads chega, é gravado cru e aparece no painel em menos de 1 minuto.
2. O mesmo lead enviado duas vezes gera um único registro.
3. O agente passa em todas as personas do simulador.
4. A guarda de envio bloqueia uma mensagem com preço e uma com afirmação `pending`, e ambas aparecem na fila de exceções.
5. Opt-out bloqueia envios em todos os módulos e cancela follow-ups agendados.
6. Com a gerente como dona, o agente não consegue enviar naquela conversa.
7. Reiniciar o servidor com jobs em andamento não perde nem duplica mensagens ou leads.
8. Estourar o orçamento de teste ou disparar um breaker manda leads novos para a fila humana, sem perder captação.
9. Em `dry_run`, nenhuma mensagem sai sem ação da gerente.
10. Lead qualificado é entregue ao vendedor com data e hora registradas e entra no contador da garantia após 48h.
11. O cockpit mostra CPLQ, custo de IA por lead e margem do cliente.
12. Interface 100% em português; código, banco e status em inglês.
13. Lint, testes e build aprovados.

Fase 2: enriquecimento por CNPJ; score configurável por versão; portal do cliente com contestação, feedback de venda e cadastro de afirmações; conversões offline para Meta e Google; pacing com alertas; Google Ads como fonte de lead; módulo de experimentos; circuit breaker completo; copiloto de prospecção (pode ser antecipado, porque é independente e ajuda a vender os primeiros pacotes).

Fase 3: integrações com CRMs; editor de roteiros sem código; novos nichos (automotivo); relatórios automáticos de ROI para o cliente.

## 15. Decisões em aberto

A auditoria e o plano podem começar sem essas respostas. Antes de aprovar código da Fase 1, as decisões 1, 3 e 7 precisam estar fechadas, porque mudam o modelo de dados, a configuração do WhatsApp e o deploy.

1. Captação na marca do cliente ou portal com marca própria da Cacalutia distribuindo leads por aderência.
2. Limite de clientes por nicho e região para não competir no mesmo leilão.
3. Número de WhatsApp: na WABA do cliente ou da Cacalutia.
4. Contas de anúncio: uma por cliente na BM da Cacalutia, ou na BM do cliente com pagamento da Cacalutia. Ter BM reserva e mais de um admin.
5. Regime tributário e forma de faturamento (contador).
6. Cláusula de garantia e contrato de tratamento de dados com o cliente (advogado).
7. Servidor dedicado ou VPS atual.
8. Fornecedor de dados de CNPJ com busca por CNAE para o copiloto.
9. Limiares iniciais do circuit breaker e teto diário do nível `pilot`.

## 16. Design e interface

Direção: evolução do visual do Cacalutia One, mais futurista, com dados como protagonistas e sensação de sala de controle ao vivo. Mesma família visual do One, para a marca Cacalutia ser reconhecida nos dois sistemas, com mais gráficos e gradientes tecnológicos.

Referência: o arquivo `referencia-visual.html` mostra a tela de visão geral. É direção visual, não especificação pixel a pixel. Antes de começar, ler os tokens reais do frontend do One (configuração do Tailwind, variáveis CSS, fontes, componentes de gráfico) e partir deles, porque o visual do One pode ter evoluído desde a especificação original. Usar a skill frontend-design instalada.

### 16.1 Base herdada do One

Tema escuro como padrão, com opção clara. Fundo `#0D0F12`; superfícies `#13161B` e `#1A1E25`; bordas `rgba(255,255,255,0.07)`; azul elétrico `#4F8EF7`; violeta `#7B5CF0`. DM Sans para interface e DM Mono só para números e métricas (com `tabular-nums`). Sidebar fixa à esquerda, topbar com cliente selecionado, ciclo e indicador ao vivo. Stack React + Tailwind + Recharts, igual ao One.

### 16.2 O que evolui

Cores novas com papel definido: ciano `#22D3EE` representa IA em ação (agentes, conversas ao vivo, processamento); lima `#CCFF00`, a cor do logo, fica reservada para o elemento mais importante de cada tela, que na visão geral é o anel da garantia; semânticas sucesso `#34D399`, atenção `#FBBF24` e perigo `#F87171`.

Gradientes sempre com função:

| Gradiente | Cores | Onde usar |
|---|---|---|
| Fluxo | `#4F8EF7` para `#7B5CF0` | Barras do funil, indicador do menu ativo, linha fina no topo dos cards principais, barras de progresso |
| Sinal | `#22D3EE` para `#4F8EF7` | Tudo que é IA: status do agente, progresso da qualificação, carregamentos |
| Garantia | `#CCFF00` para `#22D3EE` | Anel da garantia, etapa "aceitos" do funil e margem projetada |
| Preenchimento | cor da série de 35% de opacidade até 0 | Área abaixo das linhas dos gráficos |
| Ambiente | brilhos radiais azul e violeta com 10% a 16% de opacidade | Topo da página e tela de login |

Onde não usar gradiente: área de mensagens da central de conversas, tabelas, formulários e textos longos. A gerente passa o dia na central; lá o visual é calmo e com contraste alto, e a cor aparece só em status.

### 16.3 Dois modos de densidade

Modo cockpit (visão geral, cockpit financeiro, experimentos, portal do cliente): gráficos grandes, gradientes, sequência de entrada animada. Modo operação (central de conversas, leads, roteiros e afirmações): denso, calmo, foco em leitura e ação rápida, com atalhos de teclado para assumir, devolver e pausar.

### 16.4 Gráficos por tela

| Tela | Gráficos e componentes |
|---|---|
| Visão geral | Anel da garantia com faltantes e projeção; funil do ciclo; custo por lead qualificado com linha de teto tracejada; leads recebidos e qualificados por dia (área); feed dos agentes ao vivo; projeção de custos e margem (barra empilhada); carteira de clientes com progresso e status |
| Cockpit financeiro | Composição de custos por cliente (barras empilhadas); margem por cliente com linha da margem alvo; CPLQ de cada cliente contra o teto (dispersão); receita e custo por ciclo (colunas); pacing de todos os clientes |
| Central de conversas | Contadores da fila de exceções; tempo até primeira resposta (minigráfico); handoffs do dia |
| Agentes e roteiros | Intenções detectadas (barras); taxa de qualificação por versão de roteiro; opt-out e reprovações de afirmação ao longo do tempo |
| Experimentos | Variantes lado a lado com amostra atingida e intervalo de confiança |
| Portal do cliente | Anel da garantia; leads aceitos por dia; funil até a venda com o feedback do vendedor; retorno estimado |
| Prospecção | Pipeline em kanban; distribuição de prospects por score |

### 16.5 Movimento e qualidade

Uma única sequência de entrada por tela (o anel da garantia desenha, as barras e linhas crescem). Ponto pulsando em ciano para ao vivo e para novo lead chegando. Transições quando o usuário age (abrir conversa, assumir, pausar). Nada de animação em todo hover. Respeitar `prefers-reduced-motion`.

Contraste AA em todos os textos; cor nunca carrega significado sozinha (sempre texto ou ícone junto); foco de teclado visível; responsivo até tablet; valores no padrão brasileiro (R$ 1.900, 33%); textos da interface em frase normal, sem caixa alta.

Criar primeiro o design system (tokens, componentes de card, tag, tabela e wrappers de gráfico do Recharts com os gradientes) e só depois as telas, para todas ficarem consistentes.

## 17. Mensagem inicial para o Claude Code

```
Leia o arquivo PLANEJAMENTO-CACALUTIA-LEADS.md nesta pasta (versão 2.1). Ele contém
a visão, o modelo de negócio, as definições, as regras de conduta do agente, a
arquitetura e a direção de design de um projeto novo. Abra também o arquivo
referencia-visual.html, que é a referência visual da tela de visão geral.

Depois de ler, escreva um CLAUDE.md consolidando esse contexto para sessões
futuras, com destaque para as regras de arquitetura da seção 10.

Em seguida, audite o código do Cacalutia One em /home/ccltglobal1/one.cacalutia.com
(somente leitura, não altere nada lá) e gere o arquivo REAPROVEITAMENTO.md dizendo,
arquivo por arquivo, o que pode ser reaproveitado, o que precisa ser adaptado e o
que não serve. Foque nas integrações Meta Ads, Google Ads, GA4, autenticação, roles,
multi-tenant e no frontend (tokens de design, componentes e gráficos).

Não escreva código ainda. Me apresente, explicando como para um leigo:
1. O que dá para reaproveitar do One e quanto trabalho isso economiza
2. Se você concorda com o app separado ou vê motivo para ser módulo do One
3. Como implementar jobs duráveis, guarda de envio e trava de dono neste servidor
4. Quais pontos do modelo de dados você mudaria
5. Como vai montar o design system da seção 16 aproveitando o frontend do One
6. O plano de construção da Fase 1 em etapas pequenas e testáveis, cada uma
   ligada aos critérios de aceite da seção 14
```