cdp-edge 1.2.2 → 1.4.0

package/extracted-skill/tracking-events-generator/knowledge-base.md

@@ -2892,3 +2892,175 @@ async function sha256(data) {
 4.  **SDK Site**: Inserir `cdpTrack.js` e `tracking.config.js` no site.
 5.  **Event Mapping**: Configurar gatilhos de clique e formulário no site.
 6.  **Webhooks**: Configurar o endpoint de webhook na plataforma de vendas (Ticto/Hotmart).
+
+---
+
+## 🤖 8. MELHORIA CONTÍNUA AUTOMÁTICA (FASE 5)
+
+A Fase 5 fecha o ciclo de dados: cada evento coletado alimenta modelos e alertas que, automaticamente, melhoram a qualidade de atribuição na próxima semana — sem intervenção manual.
+
+---
+
+### 8.1 O Ciclo de Melhoria Contínua
+
+```
+Evento /track
+    │
+    ├─ match_quality_log (has_email, has_fbp, has_phone, has_fbc, was_email_recovered)
+    │       │
+    │       └─ Cron semanal analisa janela de 2h
+    │               → email_rate < 40%  → alerta CallMeBot
+    │               → fbp_rate < 30%    → alerta CallMeBot
+    │               → composite_score < 45% → alerta CallMeBot
+    │
+    ├─ user_profiles (Identity Graph)
+    │       │
+    │       └─ Auto-Enrich: antes de cada dispatch Meta CAPI,
+    │               Worker consulta user_profiles por userId
+    │               → recupera email/fbp/fbc/phone ausentes
+    │               → evento vai para Meta COM email → EMQ sobe
+    │
+    ├─ leads × purchases (D1)
+    │       │
+    │       └─ Cron semanal treina regressão logística
+    │               → pesos gravados em ltv_model_weights (is_active=1)
+    │               → cached em KV → próximo /track usa modelo treinado
+    │               → fallback heurístico se modelo não disponível
+    │
+    └─ user_profiles (alta intenção) → Customer Match Export semanal
+            → GET /export/customer-match → CSV para Google Ads
+            → Meta Custom Audience auto-atualizada
+```
+
+---
+
+### 8.2 Match Quality — Monitoramento Automático
+
+Cada dispatch para a Meta CAPI registra na tabela `match_quality_log`:
+
+| Campo | O que indica |
+|---|---|
+| `has_email` | Evento foi com email (principal fator de EMQ) |
+| `has_phone` | Evento foi com telefone |
+| `has_fbp` | Cookie _fbp presente (atribuição via pixel) |
+| `has_fbc` | Cookie _fbc presente (atribuição via clique em anúncio) |
+| `was_email_recovered` | Email recuperado via Identity Graph (Auto-Enrich) |
+
+**Thresholds de alerta (cron semanal):**
+
+| Métrica | Threshold de alerta | Impacto |
+|---|---|---|
+| `email_rate` | < 40% | Atribuição fraca — muitos eventos sem email |
+| `fbp_rate` | < 30% | Pixel sem rastrear adequadamente |
+| `composite_score` | < 45% | EMQ geral degradado |
+
+A view `v_match_quality_24h` agrega os dados prontos para consulta instantânea:
+
+```sql
+SELECT * FROM v_match_quality_24h;
+-- Retorna: event_count, email_rate, phone_rate, fbp_rate, fbc_rate, composite_score
+```
+
+---
+
+### 8.3 Identity Graph — Auto-Enrich Antes do Dispatch
+
+Antes de cada dispatch para a Meta CAPI, o Worker consulta `user_profiles` usando o `userId` do evento. Se o evento chegou sem email ou sem fbp, mas o perfil do usuário tem esses dados de uma sessão anterior, eles são injetados automaticamente no payload.
+
+**Resultado prático:**
+- Lead preencheu formulário na semana passada (email registrado no perfil)
+- Hoje clicou em anúncio e disparou `ViewContent` sem email
+- Worker recupera o email do perfil → evento vai para Meta COM email
+- Meta recebe o sinal com Advanced Matching completo → melhor atribuição
+- `was_email_recovered = 1` fica registrado em `match_quality_log`
+
+Esse processo é transparente: o browser não precisa enviar nada a mais.
+
+---
+
+### 8.4 LTV Real — Modelo Treinado em Dados Reais
+
+**Como funciona:**
+
+1. Cron semanal executa no Worker
+2. Busca leads com `purchase = true/false` dos últimos 90 dias no D1
+3. Treina regressão logística com as features disponíveis (ltv_score, behavior_score, engagement_score, utm_source, state)
+4. Grava os pesos em `ltv_model_weights` com `is_active = 1`
+5. Cacheia os pesos em KV para acesso em ~0ms
+
+**Uso em runtime (cada `/track`):**
+- Worker verifica se há pesos ativos no KV
+- Se sim: usa o modelo treinado para prever LTV
+- Se não: fallback para heurística baseada em regras
+- Score 0-100 → classificação High/Medium/Low → valor estimado em BRL
+
+**Tabela `ltv_model_weights`:**
+
+| Campo | Descrição |
+|---|---|
+| `trained_at` | Timestamp do treinamento |
+| `is_active` | Apenas 1 registro ativo por vez |
+| `accuracy` | Acurácia do modelo no conjunto de teste (0-1) |
+| `weights_json` | Pesos serializados da regressão logística |
+
+---
+
+### 8.5 A/B LTV — Auto-Winner
+
+Quando um experimento A/B de prompt LTV tem uma variação com acurácia ≥5pp acima do controle:
+
+1. O Worker declara o vencedor automaticamente via `POST /api/ltv/ab-test/winner`
+2. O prompt vencedor é ativado para todos os novos eventos
+3. Um alerta WhatsApp é enviado informando qual variação ganhou e a diferença de acurácia
+
+Isso elimina a necessidade de revisão manual de experimentos.
+
+---
+
+### 8.6 Customer Match — Sync Semanal
+
+O cron semanal também exporta os perfis com `intention_level = 'high'` via `GET /export/customer-match`.
+
+- Formato CSV compatível com Google Customer Match
+- Emails e telefones hashados (SHA-256) conforme exigido pelo Google
+- Pode ser automatizado para upload direto via Google Ads API
+
+---
+
+### 8.7 Como Cada Tabela Alimenta o Desempenho
+
+| Tabela | Alimenta | Resultado |
+|---|---|---|
+| `match_quality_log` | Alerta de degradação de EMQ | Fix proativo antes do CPA subir |
+| `user_profiles` | Auto-Enrich no dispatch | Mais eventos com email → EMQ sobe |
+| `ltv_model_weights` | Score LTV real no /track | Bids mais inteligentes via bid_recommendations |
+| `ml_segments` + `bid_recommendations` | Bid por segmento × plataforma | ROAS por cluster |
+| `fraud_signals` | Tráfego limpo | Melhor atribuição Meta/Google |
+| `ltv_ab_assignments` | Experimentos de prompt | Prompt com maior acurácia vence automaticamente |
+
+---
+
+### 8.8 Endpoints para Consultar os Dados
+
+| Endpoint | O que retorna |
+|---|---|
+| `GET /api/fraud/stats` | Dashboard de fraude nas últimas 24h |
+| `GET /api/segmentation/list` | Segmentos ML ativos com métricas |
+| `GET /api/bidding/status` | Recomendações de bid por segmento × plataforma |
+| `GET /api/ltv/ab-test/results` | Acurácia por variação + vencedor recomendado |
+| `GET /export/customer-match` | Export de leads high-intent para Google Ads |
+
+---
+
+### 8.9 Sequência Completa de Migrations D1 (incluindo Fase 5)
+
+```bash
+wrangler d1 execute cdp-edge-db --file=schema.sql --remote
+wrangler d1 execute cdp-edge-db --file=migrate-v6.sql --remote
+wrangler d1 execute cdp-edge-db --file=schema-segmentation.sql --remote
+wrangler d1 execute cdp-edge-db --file=schema-bidding.sql --remote
+wrangler d1 execute cdp-edge-db --file=schema-ab-ltv.sql --remote
+wrangler d1 execute cdp-edge-db --file=schema-fraud.sql --remote
+wrangler d1 execute cdp-edge-db --file=schema-indexes.sql --remote   # Índices compostos de performance
+wrangler d1 execute cdp-edge-db --file=migrate-v7.sql --remote       # Fase 5: ltv_model_weights + match_quality_log
+```