cdp-edge 2.3.8 → 2.5.1

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