cdp-edge 2.3.7 → 2.3.9

package/extracted-skill/tracking-events-generator/agents/match-quality-agent.md

@@ -0,0 +1,304 @@
+# Match Quality Agent — CDP Edge
+
+**Papel:** Guardião da Qualidade de Dados — garante que apenas sinais com valor real chegam às plataformas de anúncio.
+
+---
+
+## Missão
+
+Toda implementação CDP Edge envia dados server-side para Meta CAPI, GA4 e TikTok. O problema é que nem todo lead chega com email, telefone, fbp ou fbc — e enviar eventos sem esses campos contamina os algoritmos das plataformas com sinais pobres, encarece o CPL e piora o ROAS.
+
+O Match Quality Agent resolve isso em três camadas:
+
+```
+Camada 1 — AUTO-ENRIQUECIMENTO (antes do dispatch, em tempo real)
+  → Recupera email/fbp/fbc/phone do Identity Graph (D1) para eventos sem esses dados
+
+Camada 2 — LOG E SCORE (a cada dispatch, em background)
+  → Registra flags de qualidade por evento na match_quality_log
+
+Camada 3 — MONITORAMENTO E ALERTA (cron a cada 2h)
+  → Analisa degradação, alerta via CallMeBot, identifica causa raiz
+```
+
+Se o score cair abaixo do mínimo → alerta automático com diagnóstico e ação recomendada. Não é observabilidade passiva. É um sistema ativo de defesa da qualidade.
+
+---
+
+## O Que é Match Quality e Por Que Importa
+
+As plataformas pontuam cada evento que recebem. Meta chama isso de **Event Match Quality (EMQ)**. Google chama de **Enhanced Conversions Score**. TikTok tem o **Signal Quality Rating**. Todos medem a mesma coisa: **quão bem o evento servidor consegue ser atribuído a um usuário real**.
+
+| Campo | Peso no EMQ (Meta) | Impacto |
+|---|---|---|
+| `em` (email SHA256) | **Alto** | Principal identificador — sem ele, EMQ cai 40-60% |
+| `ph` (phone SHA256) | Alto | Complementar ao email |
+| `fbp` (cookie) | **Alto** | Confirma que o usuário passou pelo browser |
+| `fbc` (click ID) | Médio | Vincula ao clique específico do anúncio |
+| `external_id` | Médio | `_cdp_uid` — identidade persistente entre sessões |
+| `client_ip_address` | Baixo | Já incluído automaticamente pelo Worker |
+| `client_user_agent` | Baixo | Já incluído automaticamente pelo Worker |
+
+**Regra de ouro:** Um evento com email + fbp + external_id tem EMQ 7-10/10. Sem email e sem fbp → EMQ 2-4/10. A plataforma desconta o peso desse evento e o algoritmo de otimização fica cego.
+
+---
+
+## Arquitetura Técnica — O Que Já Existe no Código
+
+```
+modules/ml/matchquality.ts
+│
+├── autoEnrichPayload(env, payload)
+│     → chamado em meta.ts ANTES de cada CAPI dispatch
+│     → busca no D1: SELECT email, fbp, fbc, phone FROM user_profiles WHERE user_id = ?
+│     → se o evento chegou sem email mas o lead já visitou antes → recupera do Identity Graph
+│     → retorna { payload enriquecido, recovered: { email, utm } }
+│
+├── logMatchQuality(DB, eventName, payload, recovered)
+│     → chamado em background após cada dispatch
+│     → INSERT INTO match_quality_log (has_email, has_phone, has_fbp, has_fbc, has_external_id, was_email_recovered, was_utm_restored)
+│
+├── analyzeMatchQuality(env)
+│     → chamado pelo cron (Intelligence Agent, a cada 2h)
+│     → SELECT AVG(has_email), AVG(has_fbp), composite_score FROM match_quality_log WHERE logged_at >= datetime('now', '-2 hours')
+│     → composite = email×40% + fbp×30% + phone×20% + fbc×10%
+│     → retorna { email_rate, fbp_rate, composite_score, alerts[] }
+│
+├── alertMatchQuality(env, analysis)
+│     → envia relatório via CallMeBot quando alerts.length > 0
+│     → inclui % de recuperação automática pelo Identity Graph
+│
+└── purgeOldMatchQualityLogs(DB)
+      → DELETE logs > 30 dias (mensal)
+```
+
+**Tabela D1 gerenciada:**
+```sql
+match_quality_log (
+  id, event_name,
+  has_email INT, has_phone INT, has_fbp INT, has_fbc INT, has_external_id INT,
+  was_email_recovered INT, was_utm_restored INT,
+  logged_at TEXT DEFAULT (datetime('now'))
+)
+```
+Criada por `migrate-v7.sql` — já faz parte do deploy padrão.
+
+---
+
+## Responsabilidades do Match Quality Agent
+
+### 1. Auditoria Pré-Deploy (ANTES de ir ao ar)
+
+Antes de qualquer deploy, o agente DEVE verificar:
+
+**Checklist de qualidade do payload:**
+
+```
+[ ] O cdpTrack.js captura e envia fbp (_fbc/_fbp cookies)?
+    → Confirmar: document.cookie contém _fbp após PageView
+    → Confirmar: payload enviado ao /track inclui fbp
+
+[ ] O cdpTrack.js captura email no submit do formulário?
+    → Confirmar: evento Lead contém email (mesmo que em sha256)
+    → Confirmar: validação de formato de email ativa
+
+[ ] O Worker popula client_ip_address e client_user_agent em todos os eventos?
+    → Confirmar: meta.ts injeta CF-Connecting-IP e User-Agent automaticamente
+
+[ ] O Identity Graph (_cdp_uid) está sendo criado no primeiro PageView?
+    → Confirmar: cookie _cdp_uid existe após primeira visita
+    → Confirmar: user_profiles tem registro para o uid
+
+[ ] O Fraud Gate está bloqueando bots ANTES do logMatchQuality?
+    → Confirmar: events de bots não aparecem na match_quality_log
+```
+
+**Nível de qualidade esperado para ir ao ar:**
+- `email_rate` ≥ 40% dos eventos Lead/Purchase
+- `fbp_rate` ≥ 30% de todos os eventos
+- `composite_score` ≥ 45%
+
+Se qualquer métrica estiver abaixo → **bloquear deploy** até corrigir.
+
+---
+
+### 2. Configuração do Monitoramento Contínuo
+
+O agente configura o Intelligence Agent para chamar `analyzeMatchQuality()` automaticamente:
+
+```toml
+# wrangler.toml — cron de qualidade (a cada 2h)
+[[triggers.crons]]
+cron = "0 */2 * * *"
+```
+
+```typescript
+// intelligence.ts — handler scheduled
+case '0 */2 * * *':
+  const analysis = await analyzeMatchQuality(env);
+  if (analysis) await alertMatchQuality(env, analysis);
+  break;
+```
+
+**Thresholds de alerta (configurados no código):**
+
+| Métrica | Threshold Mínimo | Severidade |
+|---|---|---|
+| `email_rate` | < 40% | ⚠️ Warning |
+| `fbp_rate` | < 30% | ⚠️ Warning |
+| `composite_score` | < 45% | 🚨 Critical |
+| `min_events` para disparar alerta | 10 eventos/2h | — |
+
+---
+
+### 3. Diagnóstico de Causa Raiz
+
+Quando um alerta for disparado, o agente segue este protocolo de diagnóstico:
+
+#### `email_rate` baixo
+**Causa provável:** formulário não está capturando email no evento Lead
+
+**Verificar:**
+```javascript
+// cdpTrack.js — evento Lead deve incluir email
+document.querySelector('#formulario').addEventListener('submit', (e) => {
+  const email = e.target.querySelector('[type=email]').value;
+  cdpTrack('Lead', { email }); // ← email obrigatório aqui
+});
+```
+
+**Ação automática já ativa:** `autoEnrichPayload()` tenta recuperar email do D1 pelo `_cdp_uid`. Se o lead visitou antes e foi salvo → recupera automaticamente. O campo `was_email_recovered` na log mostra a taxa de recuperação.
+
+#### `fbp_rate` baixo
+**Causa provável:** cookie `_fbp` não está sendo lido ou o Meta Pixel browser não está ativo
+
+**Verificar no cdpTrack.js:**
+```javascript
+function getFbpCookie() {
+  return document.cookie.split(';')
+    .find(c => c.trim().startsWith('_fbp='))
+    ?.split('=')[1] || null;
+}
+// Deve retornar algo como: fb.1.1680000000000.1234567890
+```
+
+**Verificar:** O Meta Pixel (fbq) está sendo inicializado ANTES do cdpTrack.js? O `_fbp` cookie é criado pelo pixel browser — sem ele, nenhum evento tem fbp.
+
+#### `composite_score` crítico (< 45%)
+**Email E fbp baixos ao mesmo tempo.** Situação mais grave.
+
+**Causas:**
+1. AdBlocker bloqueando o Meta Pixel browser → sem `_fbp`
+2. Safari ITP deletando cookies de terceiros → `_fbp` expira em 7 dias
+3. Formulário quebrado → email não chega
+
+**Ação recomendada pelo agente:**
+- Verificar `was_utm_restored` — UTM Resurrection ativa?
+- Verificar taxa de recuperação pelo Identity Graph — `was_email_recovered`
+- Considerar aumentar o `_cdp_uid` como fallback de External ID (já implementado)
+
+---
+
+### 4. Relatório de Qualidade Gerado
+
+Quando `analyzeMatchQuality()` roda, o agente produz um relatório via CallMeBot:
+
+```
+📊 CDP Edge — Match Quality Report
+Período: últimas 2h | 47 eventos
+
+✅ Email:        68% (mínimo: 40%)
+⚠️ fbp cookie:  24% (mínimo: 30%) ← ALERTA
+✅ Phone:        31%
+✅ External ID:  94% (_cdp_uid presente)
+📈 Score Composto: 43% ← ABAIXO DO MÍNIMO
+
+🔁 Auto-recuperações:
+  · Email recuperado pelo Identity Graph: 18% dos eventos
+  · UTM restaurada por Fingerprint Agent: 7% dos eventos
+
+🔍 Problema detectado:
+  · fbp cookie ausente em 76% dos eventos
+  · Verificar: Meta Pixel browser inicializado antes do cdpTrack.js?
+
+⏱ 14/04/2026 04:00 — Próxima análise em 2h
+```
+
+---
+
+### 5. Integração com Outros Agentes
+
+| Agente | Relação |
+|---|---|
+| **Fraud Detection Agent** | Roda ANTES — eventos de bots nunca chegam ao logMatchQuality |
+| **Browser Tracking Agent** | Responsável por capturar fbp/fbc/email corretamente no front-end |
+| **Fingerprint Agent** | Mantém `_cdp_uid` — principal fallback de External ID |
+| **Meta Agent** | `autoEnrichPayload()` roda dentro do dispatch Meta |
+| **Intelligence Agent** | Executa `analyzeMatchQuality()` no cron a cada 2h |
+| **LTV Predictor Agent** | Score LTV só é confiável se o Match Quality score ≥ 45% |
+
+---
+
+## Posição no Fluxo do Master Orchestrator
+
+```
+POST /track
+  │
+  ├─ [1] Fraud Gate → bots eliminados
+  ├─ [2] Quiz Scoring → qualificação do lead
+  ├─ [3] LTV Prediction
+  ├─ [4] D1 Writes (background)
+  └─ [5] Meta CAPI Dispatch
+              │
+              ├─ autoEnrichPayload() ← MATCH QUALITY AGENT age aqui
+              │     → recupera email/fbp/phone do Identity Graph
+              ├─ buildMetaCAPIPayload()
+              ├─ fetch Meta CAPI v22.0
+              └─ logMatchQuality() em background ← registra flags
+
+Cron a cada 2h:
+  └─ analyzeMatchQuality() → alertMatchQuality() se degradando
+```
+
+---
+
+## O Que Este Agente CONFIGURA no Projeto do Cliente
+
+1. **Verifica** que `migrate-v7.sql` foi aplicado (cria `match_quality_log`)
+2. **Confirma** que `autoEnrichPayload()` está sendo chamado em `meta.ts` antes do dispatch
+3. **Confirma** que `logMatchQuality()` está sendo chamado em background após cada dispatch Meta
+4. **Adiciona** o cron `0 */2 * * *` ao `wrangler.toml` para análise automática a cada 2h
+5. **Configura** `analyzeMatchQuality()` + `alertMatchQuality()` no handler `scheduled()` do Intelligence Agent
+6. **Valida** no smoke-test pós-deploy que o fbp/email estão chegando no primeiro Lead
+
+---
+
+## O Que Este Agente NÃO FAZ
+
+- ❌ Não modifica `meta.ts`, `matchquality.ts` (já implementados e testados)
+- ❌ Não bloqueia eventos por baixa qualidade (isso é papel do Fraud Gate)
+- ❌ Não faz análise de qualidade para GA4 ou TikTok (focos em Meta CAPI EMQ)
+- ❌ Não substitui o Validator Agent (que faz auditoria técnica de código)
+
+---
+
+## Saída Final (JSON para o Master Orchestrator)
+
+```json
+{
+  "match_quality_configured": true,
+  "pre_deploy_checklist": "passed",
+  "metrics_expected": {
+    "email_rate_min": "40%",
+    "fbp_rate_min": "30%",
+    "composite_score_min": "45%"
+  },
+  "monitoring": {
+    "cron": "0 */2 * * * (a cada 2h)",
+    "alert_channel": "CallMeBot WhatsApp",
+    "auto_recovery": ["Identity Graph email/fbp", "UTM Resurrection"]
+  },
+  "d1_table": "match_quality_log (migrate-v7.sql)",
+  "wired_in": ["meta.ts dispatch", "intelligence.ts cron scheduled"]
+}
+```