PROMPT-MESTRE — Sistema "Templo Digital": CRM + Worker WhatsApp para Mãe Karina de Iemanjá

t; Documento de especificação para construção autônoma. Destinatário: Katia (agente de execução, sessão Claude Code, VPS dedicada do projeto). Autor da estratégia: Max (estrategista). Sponsor: Aldo Bravo.

0. SEU PAPEL E POSTURA

Você é uma arquiteta de software sênior com mais de 30 anos de experiência em sistemas de mensageria em tempo real, CRMs de alto volume e plataformas de atendimento comercial. Você foi contratada por meio milhão de reais para entregar uma solução completa, robusta e definitiva — não um MVP, não um piloto, não uma prova de conceito, não uma gambiarra. Cada decisão de arquitetura é tomada com o rigor de quem vai operar isso em produção com 5 atendentes humanos + 1 agente de IA atendendo clientes reais que pagam de R$ 30 a R$ 3.600.

Trate este documento como o escopo contratual. Onde ele for explícito, siga à risca. Onde ele deixar liberdade (ex: detalhes de UI, libs auxiliares, organização de pastas), use seu julgamento de engenheira sênior e escolha o que for mais robusto e manutenível. Não reduza escopo por economia de esforço — a expectativa é de altíssimo nível técnico.

1. CONTEXTO DE NEGÓCIO (por que isso existe)

Cliente final: Mãe Karina de Iemanjá — especialista em trabalhos espirituais e relacionamento. Fatura ~R$ 60k/mês no run-rate atual.
Potencial comprovado (não especulativo): o histórico dela mostra picos de R$ 85k a R$ 121k/mês em 2025 (mar–ago/25). Houve um declínio (incêndio na casa, meses parada) com vale no fim de 2025, e ela está em recuperação (mai/26 ≈ R$ 64k, melhor mês de 2026). Ou seja: não é uma empresa de R$ 60k tentando virar R$ 120k do nada — é uma empresa de R$ 120k que caiu e está voltando. A meta de DUPLICAR o faturamento atual é recuperar o patamar que ela já provou atingir.
O gargalo: ela tem leads sobrando (lives no TikTok, +500 mensagens/dia) e não tem braço operacional para falar com todo mundo. Dinheiro escorre por entre os dedos. Hoje ela só não fatura mais porque não dá conta do volume.
A tese: esta ferramenta supre o gap operacional com folga. Com ela, uma equipe de 5 pessoas + IA consegue atender o volume inteiro, organizar o funil, fazer cadência e recompra. A meta é DUPLICAR o faturamento a partir desta estrutura (e o teto histórico mostra que dá folga para ir além).
Escada de produtos: Teste dos Caminhos R$ 29,90 (tripwire) → consulta/tarot R$ 150 → trabalhos R$ 477 → amarração 3 Marias R$ 3.600.
A voz da Karina importa: acolhedora mas firme, sem rodeio, regional. Vocabulário: energia/frequência, alinhar, trabalho com FUNDAMENTO, acompanhamento, mal-olhado, Axé. Posicionamento anti-guru ("não é promessa de 3 dias, é trabalho com fundamento"). Fechamentos: "Axé", "Tá chefe", "estou te esperando". (A copy/IA deve soar como ela — Max fornece o guia de voz completo.)

2. STACK E TOPOLOGIA

Runtime: Node.js (LTS). Banco: SQLite (WAL mode).
Worker de WhatsApp: whatsapp-web.js (Puppeteer). Você já recebeu um worker-exemplo do Aldo para modelar — tem autonomia total para modelá-lo; o foco deste documento é o CRM e o sistema integrado, não reescrever o worker do zero. O worker é uma camada de serviço que o CRM consome.
Frontend: aplicação web servida em https://crm.maekarinadeiemanja.com.br, protegida por autenticação (login obrigatório). Pode ser SPA (React/Vue/Svelte) ou SSR — escolha sua, desde que responsiva e fluida para uso intensivo diário pela equipe.
Backend: API (REST ou RPC) + camada de tempo real (WebSocket/SSE) para que novas mensagens apareçam ao vivo na tela dos atendentes sem refresh.
Hospedagem: VPS dedicada do projeto (servidor exclusivo, memória não é restrição — por isso Puppeteer é aceitável).
Processo: worker + API + frontend sob gerenciador de processo (PM2 ou equivalente), com restart automático.

Arquitetura de camadas


[ WhatsApp do número dedicado da Karina ]
            │ (multi-device)
   ┌────────▼─────────┐
   │  WORKER (wweb.js) │  ── escuta TODOS os eventos, persiste tudo, expõe API de envio
   └────────┬─────────┘
            │ eventos + fila
   ┌────────▼─────────┐
   │   BACKEND/API     │  ── regras de negócio, auth, CRM, IA, escalation, métricas
   └────┬─────────┬────┘
        │ WS/SSE  │ REST
   ┌────▼────┐ ┌──▼──────────┐
   │ FRONT   │ │ SQLite (WAL)│
   │ (CRM)   │ └─────────────┘
   └─────────┘

3. REQUISITO-ÂNCORA: PERSISTÊNCIA TOTAL (inegociável)

TODA mensagem que passa pelo número é salva no SQLite — sem exceção:

Inbound (cliente → Karina): texto, áudio, imagem, vídeo, documento, sticker, localização, contato.
Outbound pelo sistema (atendente/IA enviando pelo CRM).
Outbound pelo APP (quando a Karina ou alguém responde direto pelo WhatsApp no celular, fora do CRM). No whatsapp-web.js isso é capturado pelo evento message_create (dispara para mensagens próprias enviadas por qualquer device). Trate isso como requisito de primeira classe — o CRM é o centro da verdade e não pode ter buracos só porque alguém respondeu pelo celular.

Implicações técnicas obrigatórias:

Distinguir direction (in/out) e sent_via (system | app | ai) em cada mensagem.
Idempotência: o multi-device pode emitir o mesmo message_id mais de uma vez — use INSERT OR IGNORE com message_id UNIQUE e só emita evento de tempo real para mensagens efetivamente novas.
Mídia baixada e persistida em disco (não só a referência), com caminho no banco.

4. MÓDULOS (escopo completo)

4.1 Worker + ingestão

Conexão via QR (página de pareamento protegida). Sessão persistida (LocalAuth) — NUNCA fazer logout no shutdown (logout invalida a sessão e força novo QR). No shutdown, só fechar o cliente.
Reconexão automática com backoff. Replay/healthcheck: ao reconectar, garantir que nada que chegou durante a queda se perdeu.
Normalização de timestamp (whatsapp-web.js entrega epoch em segundos — converter para ISO consistente; nunca gravar timestamp cru sem validar).
Detecção e unwrap de todos os tipos: texto, ephemeral, viewOnce, áudio/ptt, imagem, vídeo, documento, sticker, reaction, location, contact, poll. Nada deve cair como "unknown" silencioso — logar o que não souber tratar.
Download de mídia inbound e outbound, salvando em /media com nome seguro.

4.2 Inbox unificado (a interface de trabalho da equipe)

Este é o coração operacional — a equipe vive aqui o dia todo. Estilo "WhatsApp Web profissional + CRM":

Lista de conversas à esquerda (ordenada por última mensagem, com badge de não-lidas, prévia, foto/nome do contato).
Painel de conversa ao centro: histórico completo com bolhas in/out, player de áudio inline, visualização de imagem/vídeo inline, download de documento, exibição de transcrição abaixo de cada áudio.
Composer de envio: texto, anexar imagem, gravar/anexar áudio, enviar. Indicador de "enviando" (passou pela fila).
Painel de contexto à direita: dados do lead (CRM), estágio do funil, produtos de interesse, valor/LTV, notas internas, histórico de compras, quem está atendendo.
Tempo real: mensagem nova entra na tela ao vivo (WS/SSE), com som/notificação opcional.
Marcar como lido/não-lido, fixar conversa, arquivar.

4.3 Pipeline CRM (Kanban)

Estágios fixos definidos pelo Aldo: Primeiro Contato → Relacionamento → Negociação → Ganho / Perda.
Visão Kanban (arrastar card entre colunas) E visão lista. Card = lead com nome, telefone, último contato, valor potencial, responsável.
Mover de estágio gera evento/log (auditoria do funil) e timestamp por estágio (para medir tempo em cada fase).
"Ganho" vincula a um ou mais produtos vendidos (valor registrado → alimenta LTV e métricas). "Perda" pede motivo (dropdown + texto).

4.4 Contatos / Leads

Cada contato do WhatsApp vira um lead. Campos: nome (do WhatsApp + editável), telefone, origem (TikTok live / linktree / Teste dos Caminhos / indicação / outro — extensível), data 1º contato, estágio atual, responsável, produtos de interesse, valor histórico (LTV), nº de compras (recompra), data última compra, tags (livres), notas internas (timeline de anotações da equipe).
Histórico de compras do lead (lista de produtos + valor + data).
Detecção de recompra e cálculo automático de LTV.

4.5 Catálogo de produtos

CRUD de produtos (nome, descrição, preço, ativo/inativo). Seed inicial: Teste dos Caminhos R$ 29,90, Consulta/Tarot R$ 150, Trabalho R$ 477, Amarração 3 Marias R$ 3.600 (valores editáveis).
Produtos vinculáveis a leads (interesse) e a vendas (ganho).

4.6 Multi-usuário (5 atendentes + 1 IA) + claiming

Autenticação por usuário (não login único compartilhado). Papéis: admin (Karina/Aldo — vê tudo, configura), atendente (opera conversas), ia (usuário lógico para mensagens enviadas pela IA).
Visibilidade compartilhada: todos veem todas as conversas. MAS claiming de conversa: um atendente "assume" um lead; a UI mostra claramente quem está cuidando de quem, para evitar duas pessoas atendendo o mesmo cliente. Conversa assumida fica sinalizada; outro atendente vê "em atendimento por Fulana" antes de responder.
Log de quem enviou cada mensagem (atribuição por usuário).
Liberação/transferência de conversa entre atendentes.

4.7 Fila de envio (anti-encavalamento + anti-ban)

Toda saída passa por uma fila (uma mensagem por vez, intervalo aleatório entre envios — jitter, ex: 3-10s configurável). Com 5 pessoas + IA enviando, isso evita rajada que derruba/bana o número.
Prioridade (resposta de atendente humano > disparo automático).
Estados: pending → sending → sent → delivered/read (atualizar status via eventos de ACK do worker).
Retry com backoff em falha de envio. Mensagem nunca "some": fica registrada com status de erro se falhar.
Endpoint de envio interno é da Katia (extensível) — por ora só envio individual; arquitetar para suportar cadência/lote no futuro sem refatorar.

4.8 Mídia two-way completa

Áudio: receber (baixar, salvar, exibir player inline) e enviar (gravar no navegador ou anexar arquivo → enviar como voice note PTT).
Imagem/vídeo: receber e enviar, com preview/lightbox inline.
Documento: receber e enviar, com download.
Tudo persistido em disco + referência no banco.

4.9 Transcrição de áudio (Groq Whisper)

Todo áudio inbound é transcrito automaticamente via Groq Whisper (whisper-large-v3, language=pt) e a transcrição é salva no banco e exibida abaixo do player. (Chave de API: a Cláudia tem e está autorizada a ceder — solicite via bridge.)
Falha de transcrição não bloqueia a mensagem: salva o áudio, marca transcrição como pendente, tenta de novo.
Idealmente, transcrever também áudios outbound da própria Karina (para o histórico ficar legível).

4.10 Camada de IA (atendimento automático) — desativada por padrão

A IA pode atender clientes automaticamente na voz da Karina (Max fornece o guia de voz + diretrizes de copy). Mas:

- Vem DESATIVADA por padrão. Tudo pronto para o Aldo só inserir uma chave de API e ligar um switch.

- Switch geral (liga/desliga a IA no sistema todo) + switch por contato (pode ligar para todos e desligar em um cliente específico, ou vice-versa). A granularidade por contato é obrigatória.

- Quando ligada para um contato, a IA lê o histórico da conversa + contexto do lead (estágio, produtos) e responde na voz da Karina, respeitando o posicionamento (anti-promessa furada, trabalho com fundamento).

- Toda mensagem da IA é salva com sent_via=ai e passa pela mesma fila de envio.

- Configurável: provider/modelo, prompt-base do sistema (a persona da Karina), temperatura, limite de tokens.

4.11 Escalation (IA → humano)

Cadastro de vendedores humanos (nome + número/usuário) elegíveis a receber escalation.
A IA dispara escalation quando julgar necessário (gatilhos: cliente quer fechar/pagar, pergunta fora do escopo, sinal de irritação, pedido explícito de falar com humano, valor alto em jogo, ou confiança baixa da própria IA). Ao escalar: marca a conversa, notifica um atendente humano (na UI e/ou por mensagem ao número do vendedor), e a IA se cala naquela conversa até liberação.
Atendente assume (claiming), resolve, e pode devolver para a IA se quiser.
Tudo logado (quando, por quê, quem assumiu).

4.12 Busca e filtros extensos

Busca global: por nome, telefone, e conteúdo de mensagem (full-text nas conversas, incluindo transcrições).
Filtros combináveis "de tudo que se possa imaginar": por estágio do funil, responsável, origem da lead, produto de interesse, faixa de LTV, com/sem compra, recompra (sim/não), período (data 1º contato / última msg / última compra), status (não-lido, em atendimento, escalado, IA ativa), tags.
Salvar filtros como "visões" reutilizáveis.

4.13 Métricas / Dashboard

Funil: nº de leads por estágio, taxa de conversão entre estágios, tempo médio em cada estágio.
Comercial: faturamento no período, ticket médio, LTV médio, taxa de recompra, vendas por produto, vendas por atendente.
Faturamento incremental vs baseline (baseline = run-rate atual de recuperação, ~R$ 60k/mês; deixe configurável em metrics_config.baseline_faturamento). O dashboard mostra o quanto subiu sobre o baseline — é como o resultado da estrutura é provado. Exiba também a série histórica mensal para contexto (o teto de ~R$ 121k serve de referência de potencial).
Operacional: volume de mensagens (in/out) por dia, tempo médio de primeira resposta, conversas sem resposta há X tempo (alerta), carga por atendente, % atendido por IA vs humano.
Tudo com recorte por período.

4.14 Cadência / follow-up

Permitir marcar follow-ups (lembrete de retomar um lead em data X) e listar os follow-ups do dia por atendente.
Estrutura para cadências automatizadas futuras (sequência de mensagens na voz da Karina disparada por estágio/tempo) — deixar o esqueleto pronto, ativável depois. (A copy das cadências vem do Max.)

5. SCHEMA DE DADOS (SQLite — referência, refine conforme necessário)

contacts (id, wa_id, phone, name, push_name, photo_path, origin, first_contact_at, created_at)
leads (id, contact_id, stage, owner_user_id, potential_value, ltv, purchase_count, last_purchase_at, lost_reason, created_at, updated_at)
lead_tags (lead_id, tag)
lead_notes (id, lead_id, user_id, body, created_at)
lead_stage_history (id, lead_id, from_stage, to_stage, user_id, changed_at)
products (id, name, description, price, active)
lead_products (lead_id, product_id, kind: interest|sold, value, sold_at)
messages (id, message_id UNIQUE, contact_id, direction, sent_via, type, body, media_path, transcript, ack_status, author_user_id, timestamp, created_at)
send_queue (id, contact_id, payload, type, status, priority, attempts, error, scheduled_at, sent_at)
users (id, name, email, password_hash, role, active)
conversation_assignments (contact_id, user_id, assigned_at, status)
ai_settings (scope: global|contact, contact_id NULL para global, enabled, model, system_prompt, temperature)
escalations (id, contact_id, reason, triggered_by, assigned_user_id, status, created_at, resolved_at)
sales_vendors (id, name, phone, active)
followups (id, lead_id, user_id, due_at, note, done)
metrics_config (key, value) — ex: baseline_faturamento
audit_log (id, user_id, action, entity, entity_id, detail, created_at)

6. GUARDRAILS TÉCNICOS (aprendidos em produção — não repita esses erros)

Nunca logout() no shutdown. Só fechar o cliente. Logout = QR novo, sessão perdida.
Persista TODAS as mensagens, inclusive as enviadas pelo app (message_create). Sem buracos.
Idempotência por message_id UNIQUE + INSERT OR IGNORE; só emita evento ao vivo se a linha é nova (multi-device duplica).
Normalize timestamps antes de gravar; nunca grave valor cru que possa virar Invalid Date.
Nunca use try/catch silencioso em path crítico de persistência — se um INSERT falha, logue alto e visível. (Um catch mudo já fez sumir todas as mensagens de um contato num sistema parecido.)
Fila de envio com jitter é obrigatória — proteção anti-ban com 5+1 remetentes.
Reconexão automática + healthcheck no worker; sessão sobrevive a restart do PM2.
Backup periódico do SQLite (WAL) — cron diário, retenção configurável.
Dados sensíveis (LGPD): o conteúdo é íntimo (vida amorosa, espiritualidade, saúde emocional). Auth forte, senhas com hash (bcrypt/argon2), HTTPS obrigatório, sem logar conteúdo de mensagem em log de aplicação, acesso só autenticado.
Mídia em disco com nomes saneados (sem path traversal).

7. SEGURANÇA E ACESSO

crm.maekarinadeiemanja.com.br atrás de HTTPS (Let's Encrypt). Login obrigatório (sessão/JWT). Sem rota pública além de login e healthcheck.
Página de QR de pareamento protegida (só admin).
Rate limiting no login. Senhas hasheadas. Variáveis sensíveis (chave Groq, chave IA) em .env fora do repositório.
Papéis e permissões aplicados no backend (não só esconder no front).

8. CRITÉRIOS DE ACEITE (a solução está pronta quando…)

Conecta o número via QR e mantém sessão estável através de restarts.
Toda mensagem (in, out-sistema, out-app) aparece no CRM em tempo real e persiste no SQLite — verificável.
Áudio e imagem funcionam nos dois sentidos com player/preview inline; áudios inbound transcritos.
5 usuários logam, veem tudo, assumem conversas sem colisão (claiming visível).
Kanban com os 4 estágios, mover card registra histórico, "ganho" registra produto/valor e atualiza LTV.
Fila de envio serializa saídas com jitter; status de ACK reflete na UI.
Switch de IA (geral + por contato) presente e funcional — com a IA desligada por padrão; ao inserir chave e ligar, a IA atende na voz da Karina e respeita escalation.
Escalation funcional (IA marca, notifica humano, se cala; humano assume).
Busca por conteúdo + filtros combináveis operando.
Dashboard com funil, LTV, recompra, incremental vs baseline, tempo de resposta.
Backup do banco rodando. HTTPS + auth aplicados.

9. ENTREGÁVEIS

Sistema rodando em https://crm.maekarinadeiemanja.com.br sob PM2.
Worker WhatsApp integrado (modelado a partir do exemplo do Aldo).
Banco SQLite com o schema acima.
README de operação: como subir, conectar o número, criar usuários, configurar a chave da IA e ligar os switches, onde ficam os backups.
.env.example documentando todas as variáveis (sem segredos).

10. COORDENAÇÃO

Stack do worker: modele a partir do exemplo (whatsapp-web.js) que o Aldo te passou — autonomia sua. Foco do esforço é o CRM/sistema integrado.
Guia de voz da Karina + diretrizes de copy da IA e das cadências: o Max entrega (para o system_prompt da IA e para os templates de follow-up). Não invente o tom — use o material do Max.
Chave Groq Whisper: solicite à Cláudia via bridge.
Baseline de faturamento, número da Karina, fluxo de origem das leads: o Aldo traz após alinhar com a Karina. Deixe esses pontos configuráveis para plugar sem refatorar.
Construa o motor + estrutura já; os dados sensíveis (número, baseline) plugam no final.

Nada toca a cliente (Karina) sem o Aldo no circuito. A validação de copy/IA passa por ele.

Construa como a especialista de meio milhão que você é. Sem se conter.

Documento gerado por Max · estrategista · projeto Karina