cdp-edge 1.27.0 → 1.28.0

package/server-edge-tracker/modules/nurture.ts

@@ -0,0 +1,257 @@
+/**
+ * CDP Edge — Nurture Engine (Fase 7)
+ *
+ * Sequências de follow-up automáticas baseadas na qualificação do quiz:
+ *   comprador  → contato imediato (já tratado pelo hot lead)
+ *   interessado → D+1, D+3, D+7 (WhatsApp ou email)
+ *   curioso     → D+2, D+5 (conteúdo/isca)
+ *   perdido     → exclusão do remarketing (cohort_label = excluded)
+ *
+ * Arquitetura:
+ *   1. scheduleNurture()  — chamado no QuizComplete, insere sequência no D1
+ *   2. runNurtureQueue()  — chamado pelo Intelligence Agent (cron diário)
+ *                          envia as mensagens com send_at <= now()
+ */
+
+import { Env, TrackPayload } from '../types.js';
+
+// ── Tipos ─────────────────────────────────────────────────────────────────────
+
+export type NurtureQualification = 'comprador' | 'interessado' | 'curioso' | 'perdido';
+
+export interface NurtureStep {
+  delay_days: number;
+  channel:    'whatsapp' | 'email';
+  message:    string;     // suporta {{name}}, {{quiz_name}}, {{qualification}}
+  subject?:   string;     // apenas email
+}
+
+export interface NurtureResult {
+  scheduled: number;
+  skipped:   string | null;
+}
+
+export interface NurtureRunResult {
+  processed: number;
+  sent:      number;
+  failed:    number;
+  excluded:  number;
+}
+
+// ── Sequências por qualificação ───────────────────────────────────────────────
+// Mensagens genéricas — o cliente personaliza via automation_rules no D1.
+// O Nurture Engine usa estas como fallback quando não há regra cadastrada.
+
+const NURTURE_SEQUENCES: Record<NurtureQualification, NurtureStep[]> = {
+  comprador: [
+    // comprador já dispara hot lead imediato no /track — sem sequência adicional aqui
+  ],
+  interessado: [
+    {
+      delay_days: 1,
+      channel:    'whatsapp',
+      message:    'Olá {{name}}! Vi que você completou nosso diagnóstico e ficou entre os mais qualificados. Posso te enviar mais detalhes sobre como podemos ajudar?',
+    },
+    {
+      delay_days: 3,
+      channel:    'whatsapp',
+      message:    'Oi {{name}}, tudo bem? Separei um conteúdo exclusivo baseado nas suas respostas no quiz "{{quiz_name}}". Posso compartilhar?',
+    },
+    {
+      delay_days: 7,
+      channel:    'whatsapp',
+      message:    '{{name}}, última oportunidade esta semana! Muitos que fizeram o mesmo diagnóstico que você já estão obtendo resultados. Que tal conversarmos 15 minutos?',
+    },
+  ],
+  curioso: [
+    {
+      delay_days: 2,
+      channel:    'whatsapp',
+      message:    'Olá {{name}}! Você completou nosso diagnóstico. Preparei um material gratuito baseado no seu perfil. Posso enviar?',
+    },
+    {
+      delay_days: 5,
+      channel:    'whatsapp',
+      message:    'Oi {{name}}! Vi que você está pesquisando sobre o assunto. Tenho uma aula gratuita que pode te ajudar muito. Interesse?',
+    },
+  ],
+  perdido: [
+    // perdido não recebe mensagens — apenas é excluído do remarketing
+  ],
+};
+
+// ── scheduleNurture — agenda sequência após QuizComplete ─────────────────────
+
+export async function scheduleNurture(
+  env: Env,
+  payload: TrackPayload,
+  qualification: NurtureQualification,
+): Promise<NurtureResult> {
+  if (!env.DB) return { scheduled: 0, skipped: 'DB não disponível' };
+
+  // perdido → só atualiza cohort_label para excluir do remarketing
+  if (qualification === 'perdido') {
+    if (payload.userId) {
+      try {
+        await env.DB.prepare(`
+          UPDATE user_profiles
+          SET cohort_label = 'excluded', updated_at = datetime('now')
+          WHERE user_id = ?
+        `).bind(payload.userId).run();
+      } catch { /* não-crítico */ }
+    }
+    return { scheduled: 0, skipped: 'perdido — excluído do remarketing' };
+  }
+
+  // comprador → contato imediato já gerenciado pelo hot lead em index.ts
+  if (qualification === 'comprador') {
+    return { scheduled: 0, skipped: 'comprador — contato imediato via hot lead' };
+  }
+
+  const steps = NURTURE_SEQUENCES[qualification];
+  if (!steps || steps.length === 0) {
+    return { scheduled: 0, skipped: `sem sequência para ${qualification}` };
+  }
+
+  // Verifica se já tem sequência ativa para este usuário (evita duplicar)
+  if (payload.userId) {
+    try {
+      const existing = await env.DB.prepare(`
+        SELECT id FROM nurture_sequences
+        WHERE user_id = ? AND status = 'pending'
+        LIMIT 1
+      `).bind(payload.userId).first();
+      if (existing) return { scheduled: 0, skipped: 'sequência já existe para este usuário' };
+    } catch { /* continua */ }
+  }
+
+  let scheduled = 0;
+  for (const step of steps) {
+    try {
+      const sendAt = new Date();
+      sendAt.setDate(sendAt.getDate() + step.delay_days);
+
+      await env.DB.prepare(`
+        INSERT INTO nurture_sequences (
+          user_id, qualification, delay_days, channel,
+          message, subject, send_at, status,
+          quiz_name, phone, email, first_name, created_at
+        ) VALUES (?,?,?,?,?,?,?,?,?,?,?,?,datetime('now'))
+      `).bind(
+        payload.userId                         || null,
+        qualification,
+        step.delay_days,
+        step.channel,
+        step.message,
+        step.subject                           || null,
+        sendAt.toISOString().slice(0, 19).replace('T', ' '),
+        'pending',
+        String((payload as any).quiz_name      || ''),
+        payload.phone                          || null,
+        payload.email                          || null,
+        payload.firstName                      || null,
+      ).run();
+
+      scheduled++;
+    } catch (err: any) {
+      console.error('[Nurture] scheduleNurture insert error:', err?.message || String(err));
+    }
+  }
+
+  return { scheduled, skipped: null };
+}
+
+// ── runNurtureQueue — processa mensagens pendentes (chamado pelo cron) ────────
+
+export async function runNurtureQueue(env: Env): Promise<NurtureRunResult> {
+  if (!env.DB) return { processed: 0, sent: 0, failed: 0, excluded: 0 };
+
+  const result: NurtureRunResult = { processed: 0, sent: 0, failed: 0, excluded: 0 };
+
+  try {
+    // Busca até 50 mensagens pendentes com send_at <= agora
+    const pending = await env.DB.prepare(`
+      SELECT * FROM nurture_sequences
+      WHERE status = 'pending'
+        AND send_at <= datetime('now')
+      ORDER BY send_at ASC
+      LIMIT 50
+    `).all();
+
+    const rows = (pending.results || []) as any[];
+    if (rows.length === 0) return result;
+
+    for (const row of rows) {
+      result.processed++;
+
+      // Interpola variáveis na mensagem
+      const vars: Record<string, string> = {
+        name:          String(row.first_name || 'você'),
+        quiz_name:     String(row.quiz_name  || 'diagnóstico'),
+        qualification: String(row.qualification || ''),
+      };
+      const message = String(row.message || '').replace(/\{\{(\w+)\}\}/g, (_, k) => vars[k] ?? '');
+      const subject = row.subject ? String(row.subject).replace(/\{\{(\w+)\}\}/g, (_, k) => vars[k] ?? '') : null;
+
+      let success = false;
+
+      try {
+        if (row.channel === 'whatsapp' && row.phone && env.WHATSAPP_ACCESS_TOKEN && env.WHATSAPP_PHONE_NUMBER_ID) {
+          const digits = String(row.phone).replace(/\D/g, '');
+          const e164   = digits.startsWith('55') ? `+${digits}` : `+55${digits}`;
+
+          const res = await fetch(
+            `https://graph.facebook.com/v22.0/${env.WHATSAPP_PHONE_NUMBER_ID}/messages`,
+            {
+              method:  'POST',
+              headers: { 'Authorization': `Bearer ${env.WHATSAPP_ACCESS_TOKEN}`, 'Content-Type': 'application/json' },
+              body:    JSON.stringify({
+                messaging_product: 'whatsapp',
+                recipient_type:    'individual',
+                to:                e164,
+                type:              'text',
+                text:              { body: message },
+              }),
+            }
+          );
+          success = res.ok;
+
+        } else if (row.channel === 'email' && row.email && env.RESEND_API_KEY) {
+          const res = await fetch('https://api.resend.com/emails', {
+            method:  'POST',
+            headers: { 'Authorization': `Bearer ${env.RESEND_API_KEY}`, 'Content-Type': 'application/json' },
+            body:    JSON.stringify({
+              from:    env.RESEND_FROM_EMAIL || 'noreply@cdp-edge.app',
+              to:      [row.email],
+              subject: subject || `Olá, ${vars.name}!`,
+              html:    `<p>${message.replace(/\n/g, '<br>')}</p>`,
+            }),
+          });
+          success = res.ok;
+        }
+      } catch (err: any) {
+        console.error(`[Nurture] dispatch error (row ${row.id}):`, err?.message || String(err));
+      }
+
+      // Atualiza status no D1
+      const newStatus = success ? 'sent' : 'failed';
+      const sentAt    = success ? `datetime('now')` : 'NULL';
+      try {
+        await env.DB.prepare(`
+          UPDATE nurture_sequences
+          SET status = ?, sent_at = ${success ? "datetime('now')" : 'NULL'},
+              updated_at = datetime('now')
+          WHERE id = ?
+        `).bind(newStatus, row.id).run();
+      } catch { /* não-crítico */ }
+
+      if (success) result.sent++;
+      else          result.failed++;
+    }
+
+  } catch (err: any) {
+    console.error('[Nurture] runNurtureQueue error:', err?.message || String(err));
+  }
+
+  return result;
+}

package/server-edge-tracker/modules/utils.ts

@@ -106,6 +106,8 @@ export const VALID_EVENT_NAMES = new Set([
   'video_start','video_25','video_50','video_75','video_complete',
   // Imóveis — intenção de visita física, financiamento e favoritar
   'FindLocation','CustomizeProduct','AddToWishlist',
+  // Quiz Funnel (Fase 6)
+  'QuizStart','QuizAnswer','QuizComplete',
 ]);
 
 // ── Taxonomia de funil (funnel_stage → profundidade semântica) ────────────────

package/server-edge-tracker/schema-quiz.sql

@@ -0,0 +1,52 @@
+-- CDP Edge — Schema Quiz Sessions (Fase 6 v2)
+-- Análise Dimensional Automática por Workers AI
+-- Executar: wrangler d1 execute cdp-edge-db --file=schema-quiz.sql --remote
+
+CREATE TABLE IF NOT EXISTS quiz_sessions (
+  id                 INTEGER PRIMARY KEY AUTOINCREMENT,
+  user_id            TEXT,                   -- _cdp_uid (FK lógica → user_profiles)
+  quiz_name          TEXT,                   -- nome do quiz (ex: "Diagnóstico Imóvel")
+  answers_json       TEXT    NOT NULL,       -- JSON: [{question, answer, step}]
+  qualification      TEXT    NOT NULL,       -- comprador | interessado | curioso | perdido
+  intent_score       REAL    NOT NULL,       -- 0.0–1.0 (propagado ao pipeline CDP)
+  weighted_score     REAL    NOT NULL,       -- score ponderado bruto Σ(score×weight)/Σ(weight)
+  confidence         REAL    NOT NULL DEFAULT 0.7,
+  reason             TEXT,                   -- frase explicativa em português (audit)
+  dominant_dimension TEXT,                   -- dimensão com maior impacto: budget|urgency|etc.
+  dimensions_json    TEXT,                   -- JSON: [{step, dimension, score, weight, signal}]
+  source             TEXT    DEFAULT 'ai',   -- ai | heuristic
+  created_at         TEXT    NOT NULL DEFAULT (datetime('now'))
+);
+
+CREATE INDEX IF NOT EXISTS idx_quiz_user_id       ON quiz_sessions(user_id);
+CREATE INDEX IF NOT EXISTS idx_quiz_qualification ON quiz_sessions(qualification);
+CREATE INDEX IF NOT EXISTS idx_quiz_created_at    ON quiz_sessions(created_at);
+CREATE INDEX IF NOT EXISTS idx_quiz_dominant_dim  ON quiz_sessions(dominant_dimension);
+
+-- VIEW: distribuição de qualificações por quiz + score médio
+CREATE VIEW IF NOT EXISTS v_quiz_qualification_summary AS
+SELECT
+  quiz_name,
+  qualification,
+  COUNT(*)                                          AS total,
+  ROUND(AVG(intent_score)   * 100, 1)              AS avg_intent_pct,
+  ROUND(AVG(weighted_score) * 100, 1)              AS avg_weighted_pct,
+  ROUND(AVG(confidence)     * 100, 1)              AS avg_confidence_pct,
+  COUNT(CASE WHEN source = 'ai' THEN 1 END)        AS ai_scored,
+  COUNT(CASE WHEN source = 'heuristic' THEN 1 END) AS heuristic_scored
+FROM quiz_sessions
+GROUP BY quiz_name, qualification
+ORDER BY quiz_name, avg_intent_pct DESC;
+
+-- VIEW: qual dimensão mais penaliza/beneficia cada quiz
+CREATE VIEW IF NOT EXISTS v_quiz_dimension_impact AS
+SELECT
+  quiz_name,
+  dominant_dimension,
+  COUNT(*)                             AS total_sessions,
+  ROUND(AVG(weighted_score) * 100, 1) AS avg_weighted_pct,
+  qualification
+FROM quiz_sessions
+WHERE dominant_dimension IS NOT NULL
+GROUP BY quiz_name, dominant_dimension, qualification
+ORDER BY quiz_name, total_sessions DESC;

package/server-edge-tracker/schema-sales-engine.sql

@@ -0,0 +1,113 @@
+-- CDP Edge — Schema Sales Engine (Fase 7)
+-- ROAS Feedback Loop + Nurture Engine + Lookalike Dinâmico
+-- Executar: wrangler d1 execute cdp-edge-db --file=schema-sales-engine.sql --remote
+
+-- ── ROAS Reports — histórico de performance por campanha ──────────────────────
+CREATE TABLE IF NOT EXISTS roas_reports (
+  id                 INTEGER PRIMARY KEY AUTOINCREMENT,
+  utm_source         TEXT    NOT NULL,
+  utm_campaign       TEXT    NOT NULL,
+  utm_content        TEXT    NOT NULL DEFAULT 'unknown', -- origem: quiz_*, video_*, landing_*, ctwa_*
+  period_days        INTEGER NOT NULL DEFAULT 30,
+  total_leads        INTEGER NOT NULL DEFAULT 0,
+  confirmed_buyers   INTEGER NOT NULL DEFAULT 0,
+  conversion_rate    REAL    NOT NULL DEFAULT 0,     -- 0.0–1.0
+  total_revenue      REAL    NOT NULL DEFAULT 0,     -- BRL
+  revenue_per_lead   REAL    NOT NULL DEFAULT 0,
+  ltv_accuracy       REAL    NOT NULL DEFAULT 0,     -- % leads High LTV que realmente compraram
+  top_qualification  TEXT,                           -- qualificação quiz dominante
+  bid_recommendation TEXT    NOT NULL DEFAULT 'maintain', -- increase|maintain|decrease|pause
+  created_at         TEXT    NOT NULL DEFAULT (datetime('now'))
+);
+
+-- Migração para instâncias existentes (idempotente via IF NOT EXISTS não funciona em ALTER TABLE —
+-- execute manualmente se a tabela já existir):
+-- ALTER TABLE roas_reports ADD COLUMN utm_content TEXT NOT NULL DEFAULT 'unknown';
+
+CREATE INDEX IF NOT EXISTS idx_roas_source_campaign ON roas_reports(utm_source, utm_campaign);
+CREATE INDEX IF NOT EXISTS idx_roas_content         ON roas_reports(utm_content);
+CREATE INDEX IF NOT EXISTS idx_roas_created_at      ON roas_reports(created_at);
+CREATE INDEX IF NOT EXISTS idx_roas_bid_rec         ON roas_reports(bid_recommendation);
+
+-- VIEW: últimos relatórios por campanha com evolução
+CREATE VIEW IF NOT EXISTS v_roas_latest AS
+SELECT
+  utm_source,
+  utm_campaign,
+  conversion_rate,
+  total_revenue,
+  revenue_per_lead,
+  ltv_accuracy,
+  top_qualification,
+  bid_recommendation,
+  created_at
+FROM roas_reports r1
+WHERE created_at = (
+  SELECT MAX(r2.created_at)
+  FROM roas_reports r2
+  WHERE r2.utm_source = r1.utm_source
+    AND r2.utm_campaign = r1.utm_campaign
+)
+ORDER BY total_revenue DESC;
+
+-- ── Nurture Sequences — filas de mensagens por qualificação ──────────────────
+CREATE TABLE IF NOT EXISTS nurture_sequences (
+  id             INTEGER PRIMARY KEY AUTOINCREMENT,
+  user_id        TEXT,                     -- _cdp_uid
+  qualification  TEXT    NOT NULL,         -- interessado | curioso
+  delay_days     INTEGER NOT NULL,         -- D+N após o quiz
+  channel        TEXT    NOT NULL,         -- whatsapp | email
+  message        TEXT    NOT NULL,         -- mensagem interpolada
+  subject        TEXT,                     -- assunto (email only)
+  send_at        TEXT    NOT NULL,         -- datetime de envio agendado
+  status         TEXT    NOT NULL DEFAULT 'pending',  -- pending | sent | failed | cancelled
+  sent_at        TEXT,                     -- quando foi realmente enviado
+  quiz_name      TEXT,                     -- nome do quiz (para interpolação)
+  phone          TEXT,                     -- telefone do lead
+  email          TEXT,                     -- email do lead
+  first_name     TEXT,                     -- nome (para personalização)
+  created_at     TEXT    NOT NULL DEFAULT (datetime('now')),
+  updated_at     TEXT    NOT NULL DEFAULT (datetime('now'))
+);
+
+CREATE INDEX IF NOT EXISTS idx_nurture_user_id   ON nurture_sequences(user_id);
+CREATE INDEX IF NOT EXISTS idx_nurture_status    ON nurture_sequences(status);
+CREATE INDEX IF NOT EXISTS idx_nurture_send_at   ON nurture_sequences(send_at);
+CREATE INDEX IF NOT EXISTS idx_nurture_qual      ON nurture_sequences(qualification);
+
+-- VIEW: fila de envio pendente
+CREATE VIEW IF NOT EXISTS v_nurture_pending AS
+SELECT
+  id, user_id, qualification, delay_days, channel,
+  message, send_at, phone, email, first_name, quiz_name
+FROM nurture_sequences
+WHERE status = 'pending'
+  AND send_at <= datetime('now')
+ORDER BY send_at ASC;
+
+-- VIEW: taxa de envio por qualificação
+CREATE VIEW IF NOT EXISTS v_nurture_stats AS
+SELECT
+  qualification,
+  channel,
+  COUNT(*)                                       AS total,
+  COUNT(CASE WHEN status = 'sent'    THEN 1 END) AS sent,
+  COUNT(CASE WHEN status = 'failed'  THEN 1 END) AS failed,
+  COUNT(CASE WHEN status = 'pending' THEN 1 END) AS pending,
+  ROUND(COUNT(CASE WHEN status = 'sent' THEN 1 END) * 100.0 / COUNT(*), 1) AS delivery_rate_pct
+FROM nurture_sequences
+GROUP BY qualification, channel;
+
+-- ── Lookalike Seeds — histórico de audiences enviadas ao Meta ─────────────────
+CREATE TABLE IF NOT EXISTS lookalike_seeds (
+  id              INTEGER PRIMARY KEY AUTOINCREMENT,
+  audience_id     TEXT    NOT NULL,    -- META_AUDIENCE_ID
+  seed_type       TEXT    NOT NULL,    -- 'buyer_confirmed' | 'high_intent' | 'quiz_comprador'
+  profiles_sent   INTEGER NOT NULL DEFAULT 0,
+  profiles_received INTEGER,           -- confirmado pela API Meta
+  period_days     INTEGER NOT NULL DEFAULT 30,
+  created_at      TEXT    NOT NULL DEFAULT (datetime('now'))
+);
+
+CREATE INDEX IF NOT EXISTS idx_lookalike_seed_type  ON lookalike_seeds(seed_type);
+CREATE INDEX IF NOT EXISTS idx_lookalike_created_at ON lookalike_seeds(created_at);

package/templates/quiz-funnel.md

@@ -1,15 +1,15 @@
 # Modelo: Quiz Funnel (Cloudflare Native)
 
-Este modelo é destinado a funis de quiz, onde o usuário responde a uma série de perguntas antes de ser redirecionado para a oferta final. O rastreamento foca na progressão do usuário e na captura de dados intermediários.
+Este modelo é destinado a funis de quiz, onde o usuário responde a uma série de perguntas antes de ser redirecionado para a oferta final. O rastreamento foca na progressão do usuário e na **qualificação automática de intenção via Workers AI**.
 
 ---
 
 ## 🏗️ ARQUITETURA TÉCNICA (Quantum Tier)
 
-O rastreamento segue a lógica de micro-eventos:
+O rastreamento segue a lógica de micro-eventos + scoring automático:
 1. **Página**: Dispara um evento a cada resposta dada no quiz via `cdpTrack.track()`.
-2. **Servidor (Worker)**: Recebe e armazena o progresso no banco D1.
-3. **Database (D1)**: Mantém o histórico de respostas vinculado ao `track_user_id`.
+2. **Servidor (Worker)**: Ao receber `QuizComplete`, envia as respostas ao **Quiz Scoring Engine** (Granite 4.0 Micro) que classifica o respondente.
+3. **Pipeline CDP**: A qualificação (`comprador | interessado | curioso | perdido`) é injetada como `intentionLevel` e flui automaticamente para LTV Prediction, Meta Signal Score, D1 e CAPI dispatch.
 
 ---
 
@@ -19,50 +19,114 @@ O rastreamento segue a lógica de micro-eventos:
 |---|---|---|
 | **QuizStart** | Início do quiz | `quiz_name`, `source` |
 | **QuizAnswer** | Resposta a uma pergunta | `question`, `answer`, `step` |
-| **QuizComplete** | Finalização do quiz | `result`, `completion_time` |
+| **QuizComplete** | Finalização + qualificação AI | `quiz_name`, `quiz_answers[]`, `result` |
+
+---
+
+## 🤖 QUALIFICAÇÃO AUTOMÁTICA (Quiz Scoring Engine — Fase 6)
+
+Ao receber `QuizComplete` com `quiz_answers`, o Worker classifica automaticamente:
+
+| Qualificação | Significado | intent_score |
+|---|---|---|
+| **comprador** | Pronto para comprar agora | 0.80–1.00 |
+| **interessado** | Interesse real, avaliando | 0.50–0.79 |
+| **curioso** | Pesquisando, sem urgência | 0.20–0.49 |
+| **perdido** | Fora do público, sem fit | 0.00–0.19 |
+
+O `intent_score` resultante:
+- Alimenta o **LTV Prediction** (comprador → LTV High automaticamente)
+- Compõe o **Meta Signal Score** (pesos dinâmicos por funil)
+- Persiste em `leads.intention_level` e `quiz_sessions` no D1
+- É enviado como `custom_data` para Meta CAPI, GA4 e TikTok
 
 ---
 
 ## 🛠️ PASSO 1: CONFIGURAÇÃO DO SITE
 
 ### 1.1 Rastreamento de Respostas
-Integre este código na lógica de clique do seu quiz.
+Acumule as respostas do quiz em um array local.
 
 ```javascript
-// Exemplo de captura de resposta
+const quizAnswers = [];
+
 function onResponder(pergunta, resposta, etapa) {
+  // Armazena localmente para enviar no QuizComplete
+  quizAnswers.push({ question: pergunta, answer: resposta, step: etapa });
+
+  // Dispara micro-evento por resposta (opcional, para análise granular)
   cdpTrack.track('QuizAnswer', {
     question: pergunta,
     answer: resposta,
     step: etapa,
-    event_id: cdpTrack.generateId()
+    event_id: cdpTrack.generateId(),
   });
 }
 ```
 
-### 1.2 Finalização do Quiz
-Disparar ao chegar no resultado final ou na página de captura pós-quiz.
+### 1.2 Finalização do Quiz — com qualificação AI automática
+Envie todas as respostas no `QuizComplete`. O Worker qualifica automaticamente.
 
 ```javascript
 cdpTrack.track('QuizComplete', {
-  result: 'Perfil_A',
-  event_id: cdpTrack.generateId()
+  quiz_name: 'Diagnóstico de Perfil',   // nome para o dashboard
+  quiz_answers: quizAnswers,             // array com todas as respostas
+  result: 'Perfil_A',                   // resultado exibido ao usuário (opcional)
+  event_id: cdpTrack.generateId(),
 });
 ```
 
+### 1.3 Resposta do Worker
+O endpoint `/track` retorna a qualificação para uso imediato no front:
+
+```json
+{
+  "ok": true,
+  "userProfile": {
+    "score": 87,
+    "user_id": "uuid-xxx"
+  },
+  "quiz_qualification": "comprador",
+  "quiz_confidence": 0.91,
+  "quiz_signals": ["quero comprar", "tenho budget", "agora"],
+  "intent_score": 0.92,
+  "intent_bucket": "high"
+}
+```
+
+Use esses campos para personalizar o redirecionamento pós-quiz no front-end.
+
 ---
 
 ## ⚡ PASSO 2: SERVIDOR (CLOUDFLARE WORKER)
 
-O Worker realiza:
-- **Agregação**: O `user_id` permite que todas as respostas sejam vinculadas a um único perfil no banco D1.
-- **Enriquecimento**: Se o usuário deixar o e-mail no final, todas as respostas anteriores são associadas ao e-mail para a CAPI.
-- **API Dispatch**: Envio de eventos customizados para Meta e TikTok para otimização de público.
+O Worker realiza automaticamente na ordem:
+
+1. **Quiz Scoring Engine**: Granite 4.0 Micro classifica as respostas → `qualification` + `intent_score`
+2. **LTV Prediction**: usa `intentionLevel = 'comprador'` → LTV High → valor previsto em BRL
+3. **Meta Signal Score**: `intent_score` compõe o score composto (intent × ltv × distância)
+4. **D1 Writes**: `quiz_sessions` + `leads.intention_level` + `user_profiles.cohort_label`
+5. **CAPI Dispatch**: Meta/GA4/TikTok recebem evento com `custom_data.intention = 'comprador'`
+
+---
+
+## 🔀 FALLBACK HEURÍSTICO
+
+Se Workers AI estiver indisponível (timeout, cold start), o sistema usa correspondência de palavras-chave:
+
+- `comprador`: "quero", "comprar", "agora", "tenho interesse", "quanto custa"
+- `interessado`: "talvez", "pensando", "em breve", "estou avaliando"
+- `curioso`: "só olhando", "pesquisando", "curiosidade"
+- `perdido`: "não entendi", "errei aqui", "não é para mim"
+
+O campo `quiz_source` indica `"ai"` ou `"heuristic"` para auditoria.
 
 ---
 
 ## ✅ VALIDAÇÃO TÉCNICA
 
-- **Persistência**: Verifique no banco D1 se a jornada do usuário está sendo gravada passo a passo.
-- **Deduplicação**: O `event_id` único por resposta evita contagens duplicadas.
-- **Match Quality**: A vinculação tardia do e-mail com as respostas iniciais aumenta a precisão da atribuição.
+- **Persistência**: `quiz_sessions` no D1 — jornada completa por `user_id`
+- **Deduplicação**: `event_id` único por evento evita contagens duplicadas
+- **Enriquecimento retroativo**: e-mail preenchido pós-quiz associa todas as respostas ao perfil
+- **Match Quality**: `comprador` com e-mail → score máximo na CAPI Meta
+- **VIEW de dashboard**: `v_quiz_qualification_summary` — distribuição de qualificações por quiz