cdp-edge 2.0.0 → 2.0.2

package/extracted-skill/tracking-events-generator/agents/crm-integration-agent.md

@@ -12,6 +12,38 @@ Você é o **Agente de Integração CRM do CDP Edge**. Sua responsabilidade: **c
 
 ---
 
+## 🔗 FLUXO DE ATIVAÇÃO (Como este agente é chamado)
+
+O CRM Integration Agent é ativado pelo **Webhook Agent** após confirmação de compra ou captura de lead:
+
+```
+Webhook Agent (purchase confirmado)
+    └─► ctx.waitUntil(syncToCRM(env, 'purchase', payload))
+            │
+            ├─ Criar/atualizar contato no CRM com status 'customer'
+            ├─ Criar negócio/oportunidade com valor da compra
+            └─ Atualizar D1 com CRM_CONTACT_ID para rastreamento futuro
+
+Webhook Agent (lead capturado via /track)
+    └─► ctx.waitUntil(syncToCRM(env, 'lead', payload))
+            │
+            ├─ Criar contato no CRM com status 'lead'
+            └─ Registrar no D1 para cruzamento futuro
+```
+
+**Assinatura da função exportada (injetada no Worker):**
+
+```javascript
+// Injetada no worker.js pelo CRM Integration Agent
+export async function syncToCRM(env, eventType, payload) {
+  // eventType: 'lead' | 'purchase' | 'checkout_abandoned'
+  // payload: { email, name, product, value, order_id, phone }
+  // Retorna: { success: boolean, crm_contact_id: string | null }
+}
+```
+
+---
+
 ## 🎯 OBJETIVO PRINCIPAL
 
 Implementar **integração bidirecional** entre CDP Edge D1 e CRMs externos, permitindo que dados de tracking (leads, purchases, user journeys) fluam automaticamente para sistemas de vendas, marketing e atendimento, eliminando importações manuais e maximizando conversão.
@@ -612,8 +644,8 @@ export const PURCHASE_FIELD_MAPPINGS = {
 
 ```javascript
 // Sincronizar leads do D1 para CRM em batch
-export async function syncLeadsToCRM(hours = 24, batchSize = 50) {
-  const leads = await DB.prepare(`
+export async function syncLeadsToCRM(env, hours = 24, batchSize = 50) {
+  const leads = await env.DB.prepare(`
     SELECT * FROM leads
     WHERE created_at > datetime('now', '-${hours} hours')
     ORDER BY created_at DESC
@@ -699,8 +731,8 @@ async function sendLeadsBatchToCRM(leadsBatch) {
   };
 }
 
-async function markLeadAsSynced(leadId) {
-  await DB.prepare(`
+async function markLeadAsSynced(leadId, env) {
+  await env.DB.prepare(`
     UPDATE leads SET crm_synced = 1, crm_synced_at = datetime('now')
     WHERE id = ?
   `).bind(leadId).run();
@@ -711,8 +743,8 @@ async function markLeadAsSynced(leadId) {
 
 ```javascript
 // Sincronizar compras do D1 para CRM em batch
-export async function syncPurchasesToCRM(hours = 24, batchSize = 20) {
-  const purchases = await DB.prepare(`
+export async function syncPurchasesToCRM(env, hours = 24, batchSize = 20) {
+  const purchases = await env.DB.prepare(`
     SELECT p.*, l.email
     FROM purchases p
     LEFT JOIN leads l ON p.lead_id = l.id
@@ -800,8 +832,8 @@ async function sendPurchasesBatchToCRM(purchasesBatch) {
   };
 }
 
-async function markPurchaseAsSynced(purchaseId) {
-  await DB.prepare(`
+async function markPurchaseAsSynced(purchaseId, env) {
+  await env.DB.prepare(`
     UPDATE purchases SET crm_synced = 1, crm_synced_at = datetime('now')
     WHERE id = ?
   `).bind(purchaseId).run();
@@ -853,8 +885,8 @@ export async function handleCRMWebhook(request, env) {
   }
 }
 
-async function updateLeadStageFromCRM(payload) {
-  await DB.prepare(`
+async function updateLeadStageFromCRM(payload, env) {
+  await env.DB.prepare(`
     UPDATE leads SET crm_stage = ?, crm_stage_updated_at = datetime('now')
     WHERE email = ?
   `).bind(payload.stage, payload.email).run();
@@ -862,8 +894,8 @@ async function updateLeadStageFromCRM(payload) {
   console.log(`Stage do lead ${payload.email} atualizado para: ${payload.stage}`);
 }
 
-async function updateDealStatusFromCRM(payload) {
-  await DB.prepare(`
+async function updateDealStatusFromCRM(payload, env) {
+  await env.DB.prepare(`
     UPDATE purchases SET crm_deal_status = ?, crm_deal_status_updated_at = datetime('now')
     WHERE transaction_id = ?
   `).bind(payload.status, payload.transaction_id).run();
@@ -871,8 +903,8 @@ async function updateDealStatusFromCRM(payload) {
   console.log(`Status da compra ${payload.transaction_id} atualizado para: ${payload.status}`);
 }
 
-async function updateLeadScoreFromCRM(payload) {
-  await DB.prepare(`
+async function updateLeadScoreFromCRM(payload, env) {
+  await env.DB.prepare(`
     UPDATE leads SET lead_score = ?, lead_score_updated_at = datetime('now')
     WHERE email = ?
   `).bind(payload.lead_score, payload.email).run();
@@ -979,7 +1011,7 @@ export async function registerCRMWebhooks(crmType, webhookUrl) {
   };
 
   // Salvar configuração no D1
-  await DB.prepare(`
+  await env.DB.prepare(`
     INSERT INTO crm_webhook_config (webhook_url, crm_type, events, signature_enabled)
     VALUES (?, ?, ?, ?)
   `).bind(
@@ -994,7 +1026,7 @@ export async function registerCRMWebhooks(crmType, webhookUrl) {
 
 // Endpoint de saúde da integração
 export async function handleCRMHealthCheck(request, env) {
-  const stats = await DB.prepare(`
+  const stats = await env.DB.prepare(`
     SELECT
       COUNT(*) as total_leads,
       COUNT(CASE WHEN crm_synced = 1 THEN 1 END) as synced_leads,

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

@@ -96,16 +96,16 @@ Definir o Dashboard como um **Centro de Comando de Dados** que equilibra:
 **Implementação:**
 ```javascript
 // Carregar dados do cache
-const fetchMetrics = async (forceRefresh = false) => {
+const fetchMetrics = async (env, forceRefresh = false) => {
   const cacheKey = 'dashboard_metrics';
-  const cached = await KV.get(cacheKey);
+  const cached = await env.GEO_CACHE.get(cacheKey);
 
   if (cached && !forceRefresh) {
     return JSON.parse(cached);
   }
 
   // Cache miss ou refresh forçado — consultar D1
-  const metrics = await DB.prepare(`
+  const metrics = await env.DB.prepare(`
     SELECT
       AVG(heat_score) as avg_heat,
       COUNT(DISTINCT fingerprint) as total_users,
@@ -115,7 +115,7 @@ const fetchMetrics = async (forceRefresh = false) => {
   `).all();
 
   // Salvar no KV com TTL de 1 hora
-  await KV.put(cacheKey, JSON.stringify(metrics), { expirationTtl: 3600 });
+  await env.GEO_CACHE.put(cacheKey, JSON.stringify(metrics), { expirationTtl: 3600 });
 
   return metrics;
 };
@@ -217,13 +217,13 @@ export const DASHBOARD_API = {
 };
 
 // HANDLER DE SINCronizaÇÃO (atualização de cache)
-export async function invalidateCache(domain, pattern) {
+export async function invalidateCache(domain, pattern, env) {
   const deletePattern = `${domain}:${pattern}`;
 
   // Deletar do KV
-  const keys = await KV.list({ prefix: deletePattern });
+  const keys = await env.GEO_CACHE.list({ prefix: deletePattern });
   for (const key of keys.keys) {
-    await KV.delete(key);
+    await env.GEO_CACHE.delete(key);
   }
 
   // Retornar contagem

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

@@ -78,7 +78,7 @@ crons = ["0 2 * * 7", "0 3 1 * *"]
 - **ID:** `SEU_D1_DATABASE_ID`
 - **Região:** ENAM (US East)
 - **Engine:** SQLite (Cloudflare D1)
-- **Tabelas ativas:** 8
+- **Tabelas ativas:** 24 (core: 13, migrate-v6: 1, Enterprise Fases 1-4: 10)
 
 ### Schema Completo (Produção)
 
@@ -259,7 +259,7 @@ CREATE INDEX IF NOT EXISTS idx_wa_ctwa_clid   ON whatsapp_contacts(ctwa_clid);
 CREATE INDEX IF NOT EXISTS idx_wa_created_at  ON whatsapp_contacts(created_at);
 ```
 > **Migration:** `migrate-v6.sql` — aplicar com `wrangler d1 execute cdp-edge-db --file=migrate-v6.sql --remote`
-> **Tabelas ativas após v6:** 9
+> **Tabelas ativas após v6:** 14 (core: 13 + whatsapp_contacts)
 
 ---
 
@@ -313,9 +313,9 @@ ctx.waitUntil(
 
 ---
 
-## 📬 BINDING 2 — QUEUES (`env.QUEUE`) — *A Adicionar*
+## 📬 BINDING 2 — QUEUES (`env.RETRY_QUEUE`) — ✅ Configurado
 
-> **Status:** Arquitetado, ainda não configurado no `wrangler.toml`. Adicionar para habilitar retry assíncrono robusto.
+> **Status:** Ativo em produção — `wrangler.toml` com `RETRY_QUEUE` binding e consumer configurados.
 
 ### Configuração no `wrangler.toml`
 ```toml
@@ -387,9 +387,9 @@ Queue Consumer (assíncrono)
 
 ---
 
-## 🗂️ BINDING 3 — KV NAMESPACE (`env.GEO_CACHE`) — *A Adicionar*
+## 🗂️ BINDING 3 — KV NAMESPACE (`env.GEO_CACHE`) — ✅ Configurado
 
-> **Status:** Arquitetado para cache de geo/IP. Ainda não configurado.
+> **Status:** Ativo em produção — usado para geo cache, fraud blocklist, fraud velocity counters e A/B test cache.
 
 ### Configuração no `wrangler.toml`
 ```toml
@@ -548,7 +548,7 @@ async function runIntelligenceAgent(cron, env) {
 | `META_TEST_CODE` | ⚠️ Reconfigurar | Só testes | meta-agent |
 | `META_AD_ACCOUNT_ID` | ⚠️ Reconfigurar | Customer Match | meta-agent |
 | `META_AUDIENCE_ID` | ⚠️ Reconfigurar | Customer Match | meta-agent |
-| `WHATSAPP_TOKEN` | ⚠️ Reconfigurar | WhatsApp | whatsapp-agent |
+| `WHATSAPP_ACCESS_TOKEN` | ⚠️ Reconfigurar | WhatsApp | whatsapp-agent |
 | `WHATSAPP_PHONE_NUMBER_ID` | ⚠️ Reconfigurar | WhatsApp | whatsapp-agent |
 | `RESEND_API_KEY` | ⚠️ Reconfigurar | Email | email-agent |
 | `RESEND_FROM_EMAIL` | ⚠️ Reconfigurar | Email | email-agent |
@@ -560,7 +560,7 @@ async function runIntelligenceAgent(cron, env) {
 wrangler secret put META_ACCESS_TOKEN
 wrangler secret put GA4_API_SECRET
 wrangler secret put TIKTOK_ACCESS_TOKEN
-wrangler secret put WHATSAPP_TOKEN
+wrangler secret put WHATSAPP_ACCESS_TOKEN
 wrangler secret put WHATSAPP_PHONE_NUMBER_ID
 wrangler secret put RESEND_API_KEY
 wrangler secret put RESEND_FROM_EMAIL

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

@@ -56,9 +56,9 @@ export function logWorker(level, category, message, context = {}) {
   console.log(`[${level}] [${category}] ${message}`, JSON.stringify(context));
 }
 
-async function persistLogEntry(logEntry) {
+async function persistLogEntry(env, logEntry) {
   try {
-    await DB.prepare(`
+    await env.DB.prepare(`
       INSERT INTO worker_logs (timestamp, level, category, message, context, session_id, request_id)
       VALUES (?, ?, ?, ?, ?, ?, ?)
     `).bind(
@@ -82,7 +82,7 @@ async function dispatchEventToMeta(event, userContext) {
   try {
     const response = await fetch('https://graph.facebook.com/v22.0/events', {
       method: 'POST',
-      headers: { 'Authorization': `Bearer ${META_ACCESS_TOKEN}` },
+      headers: { 'Authorization': `Bearer ${env.META_ACCESS_TOKEN}` },
       body: JSON.stringify(event)
     });
 
@@ -221,7 +221,7 @@ cdpTrack.track = function(eventName, params) {
     };
 
     // Enviar para Worker
-    fetch('/api/track', {
+    fetch('/track', {
       method: 'POST',
       headers: { 'Content-Type': 'application/json' },
       body: JSON.stringify(eventPayload)
@@ -331,7 +331,7 @@ export async function handleDebugRequest(request, env) {
 }
 
 async function getApiHealth(platform) {
-  const recentFailures = await DB.prepare(`
+  const recentFailures = await env.DB.prepare(`
     SELECT
       COUNT(*) as failure_count,
       MAX(created_at) as last_failure_at
@@ -339,7 +339,7 @@ async function getApiHealth(platform) {
     WHERE platform = ? AND created_at > datetime('now', '-1 hour')
   `).bind(platform).get();
 
-  const recentSuccesses = await DB.prepare(`
+  const recentSuccesses = await env.DB.prepare(`
     SELECT COUNT(*) as success_count
     FROM events_log
     WHERE platform = ? AND status = 'success' AND created_at > datetime('now', '-1 hour')
@@ -394,7 +394,7 @@ export async function handleHealthCheck(request, env) {
 }
 
 async function getSimpleApiHealth(platform) {
-  const lastSuccess = await DB.prepare(`
+  const lastSuccess = await env.DB.prepare(`
     SELECT created_at
     FROM events_log
     WHERE platform = ? AND status = 'success'
@@ -402,7 +402,7 @@ async function getSimpleApiHealth(platform) {
     LIMIT 1
   `).bind(platform).get();
 
-  const lastFailure = await DB.prepare(`
+  const lastFailure = await env.DB.prepare(`
     SELECT created_at
     FROM api_failures
     WHERE platform = ?
@@ -433,7 +433,7 @@ export async function handleEventsLogRequest(request, env) {
   const limit = parseInt(url.searchParams.get('limit') || '50');
   const hours = parseInt(url.searchParams.get('hours') || '24');
 
-  const events = await DB.prepare(`
+  const events = await env.DB.prepare(`
     SELECT
       event_name,
       platform,
@@ -485,7 +485,7 @@ export async function handleEventsLogRequest(request, env) {
 
 - [ ] **Envio de eventos para Worker:**
   - [ ] Verificar Network tab em Developer Tools
-  - [ ] Confirmar requisição para `/api/track`
+  - [ ] Confirmar requisição para `/track`
   - [ ] Verificar status da resposta (deve ser 200 OK)
   - [ ] Verificar payload enviado (deve conter event_name, params, timestamp)
 
@@ -1033,7 +1033,7 @@ export async function handleEventsLogRequest(request, env) {
   const limit = parseInt(url.searchParams.get('limit') || '50');
   const hours = parseInt(url.searchParams.get('hours') || '24');
 
-  const events = await DB.prepare(`
+  const events = await env.DB.prepare(`
     SELECT event_name, platform, status, error_message, created_at
     FROM events_log
     WHERE created_at > datetime('now', '-${hours} hours')
@@ -1057,7 +1057,7 @@ export async function handleBrowserLogs(request, env) {
 
   // Persistir logs do browser no D1
   for (const log of logs) {
-    await DB.prepare(`
+    await env.DB.prepare(`
       INSERT INTO browser_logs (timestamp, level, category, message, context, session_id, page_url)
       VALUES (?, ?, ?, ?, ?, ?, ?)
     `).bind(
@@ -1182,7 +1182,7 @@ window.pbDebugLogger = logger;
 **Possíveis Causas:**
 
 1. **Evento não está sendo enviado para a plataforma**
-   - Verificar se `/api/track` está recebendo o evento
+   - Verificar se `/track` está recebendo o evento
    - Consultar `/api/events-log` para ver se evento foi processado
    - Verificar logs do Worker: `wrangler tail`
 

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

@@ -18,6 +18,16 @@ Outros agentes que precisarem de deploy **delegam para você** via `*deploy`.
 
 ---
 
+## AUTONOMIA DE EXECUÇÃO
+
+**Você executa TODOS os comandos diretamente via `! <comando>` no terminal da sessão.**
+
+O usuário não executa nenhum comando wrangler. Você é o executor exclusivo. Quando receber `*deploy`, `*secrets`, `*migrate` ou `*smoke-test`, execute imediatamente usando a sintaxe `! wrangler ...` — nunca liste comandos "para o usuário rodar".
+
+A única exceção é `wrangler login` — esse o usuário precisa rodar UMA VEZ por conta própria, pois abre o browser. Após autenticado, você assume tudo.
+
+---
+
 ## CICLO DE DEPLOY AUTOMÁTICO
 
 ### Comando: `*deploy`
@@ -81,14 +91,28 @@ git status
 
 ## PROCEDURE `*migrate`
 
-Aplica migrações D1 em ordem:
+Aplica schemas D1 em ordem (todos idempotentes — `IF NOT EXISTS`):
 
 ```bash
-wrangler d1 execute cdp-edge-db --file=migrate-v2.sql --remote
-wrangler d1 execute cdp-edge-db --file=migrate-v3.sql --remote
-wrangler d1 execute cdp-edge-db --file=migrate-v4.sql --remote
-wrangler d1 execute cdp-edge-db --file=migrate-v5.sql --remote
+cd server-edge-tracker
+
+# Core tracking (sempre primeiro)
+wrangler d1 execute cdp-edge-db --file=schema.sql --remote
+
+# Migrations históricas
 wrangler d1 execute cdp-edge-db --file=migrate-v6.sql --remote
+
+# Fase 1: ML Clustering
+wrangler d1 execute cdp-edge-db --file=schema-segmentation.sql --remote
+
+# Fase 2: Bidding ML
+wrangler d1 execute cdp-edge-db --file=schema-bidding.sql --remote
+
+# Fase 3: A/B LTV Testing
+wrangler d1 execute cdp-edge-db --file=schema-ab-ltv.sql --remote
+
+# Fase 4: Fraud Detection
+wrangler d1 execute cdp-edge-db --file=schema-fraud.sql --remote
 ```
 
 Após cada migração: confirmar sucesso antes de prosseguir.
@@ -117,8 +141,8 @@ Configura todos os secrets do cliente na Cloudflare:
 # Obrigatórios
 wrangler secret put META_ACCESS_TOKEN
 wrangler secret put GA4_API_SECRET
-wrangler secret put WA_ACCESS_TOKEN
-wrangler secret put WA_PHONE_ID
+wrangler secret put WHATSAPP_ACCESS_TOKEN
+wrangler secret put WHATSAPP_PHONE_NUMBER_ID
 wrangler secret put WA_NOTIFY_NUMBER
 wrangler secret put WA_WEBHOOK_VERIFY_TOKEN
 

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

@@ -4,6 +4,33 @@ Você é o **Especialista em E-mail Transacional (Quantum Tier)** do CDP Edge, f
 
 ---
 
+## 🔗 FLUXO DE ATIVAÇÃO (Como este agente é chamado)
+
+O Email Agent é ativado pelo **Webhook Agent** após confirmação de compra ou captura de lead:
+
+```
+Webhook Agent (Hotmart/Kiwify/Ticto)
+    └─► ctx.waitUntil(sendEmail(env, type, payload))
+            │
+            ├─ type = 'purchase_confirmation' → email de confirmação de compra
+            ├─ type = 'lead_welcome'          → email de boas-vindas ao lead
+            └─ type = 'cart_abandonment'      → email de recuperação de carrinho
+```
+
+**Assinatura da função que este agente gera:**
+
+```javascript
+// Injetada no Worker principal (worker.js)
+export async function sendEmail(env, type, payload) {
+  const { to, name, product, value } = payload;
+  // ... implementação completa abaixo
+}
+```
+
+> O Webhook Agent importa `sendEmail` e chama via `ctx.waitUntil` para não bloquear resposta ao gateway de pagamento.
+
+---
+
 ## 📧 PROTOCOLOS DE ENVIO (Quantum Tier)
 
 1. **Resend API Excellence**:

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

@@ -21,6 +21,211 @@ Sempre que o usuário sangrar dinheiro por culpa de "Perda de Cookies/Atribuiç
 
 ---
 
+## 💻 IMPLEMENTAÇÃO REAL — cloudflare/fingerprint-middleware.js
+
+### Módulo completo para injetar no Worker
+
+```javascript
+/**
+ * Fingerprint Middleware — CDP Edge
+ * Edge-only signals: IP + Accept-Language + UA base + ASN
+ * LGPD/CCPA compliant: nenhum PII direto, hash efêmero
+ */
+
+// ─────────────────────────────────────────────────
+// 1. Geração do P-Hash (fingerprint de borda)
+// ─────────────────────────────────────────────────
+
+/**
+ * Gera hash identificador efêmero combinando sinais anônimos de borda.
+ * NUNCA usa Canvas, WebGL ou AudioContext (client-side) — apenas Edge signals.
+ *
+ * @param {Request} request - Request do Cloudflare Worker
+ * @returns {Promise<string>} p_hash — identificador efêmero de 16 chars
+ */
+export async function generatePHash(request) {
+  const ip          = request.headers.get('CF-Connecting-IP')  || 'unknown';
+  const acceptLang  = request.headers.get('Accept-Language')   || 'unknown';
+  const userAgent   = request.headers.get('User-Agent')        || 'unknown';
+  const asOrg       = request.cf?.asOrganization               || 'unknown';
+  const country     = request.cf?.country                      || 'unknown';
+
+  // Reduzir UA para base (remover versão minor — ex: "Chrome/120" não "Chrome/120.0.6099.71")
+  const uaBase = userAgent
+    .replace(/[\d.]+/g, (m) => m.split('.')[0])  // mantém só major version
+    .replace(/[^a-zA-Z0-9 /]/g, '')              // remove caracteres especiais
+    .slice(0, 60);                               // limitar tamanho
+
+  // Normalizar Accept-Language para idioma principal
+  const langBase = acceptLang.split(',')[0].split(';')[0].trim().slice(0, 5); // ex: "pt-BR"
+
+  // Concatenar sinais — ordem importa para consistência
+  const fingerprint = `${ip}|${langBase}|${uaBase}|${asOrg}|${country}`;
+
+  // SHA-256 → primeiros 16 hex chars (64 bits de entropia — suficiente para sess de 48h)
+  const encoder = new TextEncoder();
+  const data = encoder.encode(fingerprint);
+  const hashBuffer = await crypto.subtle.digest('SHA-256', data);
+  const hashArray = Array.from(new Uint8Array(hashBuffer));
+  const fullHash = hashArray.map(b => b.toString(16).padStart(2, '0')).join('');
+
+  return fullHash.slice(0, 16); // p_hash = 16 chars hex
+}
+
+// ─────────────────────────────────────────────────
+// 2. Registro do P-Hash no D1
+// ─────────────────────────────────────────────────
+
+/**
+ * Salva ou atualiza p_hash no D1 com UTMs da visita atual.
+ * Janela de restauração: 48h (configurável).
+ *
+ * @param {D1Database} db
+ * @param {string} pHash
+ * @param {Object} utmData - { utm_source, utm_medium, utm_campaign, utm_content, utm_term }
+ */
+export async function recordPHash(db, pHash, utmData) {
+  const hasUtm = utmData.utm_source || utmData.utm_medium || utmData.utm_campaign;
+
+  if (!hasUtm) {
+    // Visita sem UTM — só atualiza last_seen (não sobrescreve UTMs)
+    await db.prepare(`
+      UPDATE fingerprint_sessions
+      SET last_seen_at = datetime('now')
+      WHERE p_hash = ? AND last_seen_at > datetime('now', '-48 hours')
+    `).bind(pHash).run();
+    return;
+  }
+
+  // Visita COM UTM — inserir ou atualizar
+  await db.prepare(`
+    INSERT INTO fingerprint_sessions (p_hash, utm_source, utm_medium, utm_campaign, utm_content, utm_term, last_seen_at)
+    VALUES (?, ?, ?, ?, ?, ?, datetime('now'))
+    ON CONFLICT(p_hash) DO UPDATE SET
+      utm_source   = excluded.utm_source,
+      utm_medium   = excluded.utm_medium,
+      utm_campaign = excluded.utm_campaign,
+      utm_content  = excluded.utm_content,
+      utm_term     = excluded.utm_term,
+      last_seen_at = datetime('now')
+  `).bind(
+    pHash,
+    utmData.utm_source   || null,
+    utmData.utm_medium   || null,
+    utmData.utm_campaign || null,
+    utmData.utm_content  || null,
+    utmData.utm_term     || null
+  ).run();
+}
+
+// ─────────────────────────────────────────────────
+// 3. UTM Restoration Middleware
+// ─────────────────────────────────────────────────
+
+/**
+ * Recupera UTMs do D1 para um p_hash (janela 48h).
+ * Injeta de volta no payload CAPI quando a requisição chega sem UTMs.
+ *
+ * @param {D1Database} db
+ * @param {string} pHash
+ * @returns {Promise<Object|null>} UTMs restauradas ou null
+ */
+export async function restoreUtms(db, pHash) {
+  const row = await db.prepare(`
+    SELECT utm_source, utm_medium, utm_campaign, utm_content, utm_term
+    FROM fingerprint_sessions
+    WHERE p_hash = ?
+      AND last_seen_at > datetime('now', '-48 hours')
+      AND utm_source IS NOT NULL
+    LIMIT 1
+  `).bind(pHash).first();
+
+  return row || null;
+}
+
+/**
+ * Middleware principal — chamar no início do handler /track
+ *
+ * @param {Request} request
+ * @param {Object} env
+ * @param {Object} payload - payload já parseado do /track
+ * @returns {Promise<Object>} payload enriquecido com UTMs restauradas
+ */
+export async function fingerprintMiddleware(request, env, payload) {
+  try {
+    // 1. Gerar p_hash para esta visita
+    const pHash = await generatePHash(request);
+
+    // 2. Extrair UTMs do payload atual
+    const currentUtms = {
+      utm_source:   payload.utm_source   || null,
+      utm_medium:   payload.utm_medium   || null,
+      utm_campaign: payload.utm_campaign || null,
+      utm_content:  payload.utm_content  || null,
+      utm_term:     payload.utm_term     || null,
+    };
+
+    // 3. Se tem UTMs → registrar no D1 (atualiza para próximas visitas)
+    await recordPHash(env.DB, pHash, currentUtms);
+
+    // 4. Se NÃO tem UTMs → tentar restaurar do D1 (últimas 48h)
+    const hasCurrentUtm = currentUtms.utm_source || currentUtms.utm_campaign;
+    if (!hasCurrentUtm) {
+      const restoredUtms = await restoreUtms(env.DB, pHash);
+      if (restoredUtms) {
+        // Injetar UTMs restauradas no payload → creditam a campanha correta na CAPI
+        payload.utm_source   = restoredUtms.utm_source;
+        payload.utm_medium   = restoredUtms.utm_medium;
+        payload.utm_campaign = restoredUtms.utm_campaign;
+        payload.utm_content  = restoredUtms.utm_content;
+        payload.utm_term     = restoredUtms.utm_term;
+        payload._utm_restored = true; // flag para debug
+      }
+    }
+
+    // 5. Adicionar p_hash ao payload para uso pelo Identity Graph
+    payload.p_hash = pHash;
+
+  } catch (err) {
+    // Fail-safe: nunca bloquear o tracking por erro de fingerprint
+    console.error('[FingerprintMiddleware] Erro (fail-safe):', err.message);
+  }
+
+  return payload;
+}
+```
+
+### Schema D1 necessário
+
+```sql
+-- Adicionar a schema.sql
+CREATE TABLE IF NOT EXISTS fingerprint_sessions (
+  p_hash       TEXT PRIMARY KEY,
+  utm_source   TEXT,
+  utm_medium   TEXT,
+  utm_campaign TEXT,
+  utm_content  TEXT,
+  utm_term     TEXT,
+  last_seen_at TEXT DEFAULT (datetime('now'))
+);
+
+CREATE INDEX IF NOT EXISTS idx_fp_last_seen ON fingerprint_sessions(last_seen_at);
+```
+
+### Uso no worker.js
+
+```javascript
+// No início do handler /track, ANTES do fraud gate:
+import { fingerprintMiddleware } from './fingerprint-middleware.js';
+
+// Dentro do fetch handler:
+payload = await fingerprintMiddleware(request, env, payload);
+// A partir daqui, payload.utm_* estão restauradas (se disponíveis)
+// e payload.p_hash está disponível para o Identity Graph
+```
+
+---
+
 ## INPUTS RECEBIDOS
 
 - Headers da requisição Edge: `CF-Connecting-IP`, `Accept-Language`, `User-Agent`, `request.cf.asOrganization`