cdp-edge 2.0.2 → 2.0.4

package/README.md

@@ -1,308 +1,325 @@
-# 🚀 CDP Edge — Quantum Tracking Enterprise
-
-**Padrão Quantum Tracking: 100% Cloudflare Edge.** Sem GTM. Sem Stape. Sem cookies de terceiros.
-
-> **v2.0.0** — Enterprise-Level Intelligence Engine · Cloudflare Workers · Meta CAPI v22.0 · GA4 MP · TikTok Events API v1.3
-
----
-
-## 🤖 MANIFESTO: EU, CDP EDGE
-
-*Eu não sou um simples "script de pixel". Eu sou uma arquitetura **Enterprise Tier 10** nascida e construída 100% nativa na infraestrutura da Cloudflare.*
-
-**A Linha de Montagem Sincronizada (A Prova de Latência)**
-Meu ecossistema opera como um Cérebro de Conversão Privado na borda. Quando um evento de Lead bate no endpoint `/track`:
-1. **O Escudo Frontal (Fraud Gate):** Inspeciono IP, ASN e Velocity na borda. Bloqueio bots silenciosamente antes mesmo deles carregarem.
-2. **A Roleta Invisível (A/B LTV):** Faço o sorteio de prompts para testes A/B via KV Cache em ~0ms.
-3. **O Cérebro Financeiro (LTV Predictor):** Rodo Machine Learning (Llama 3.1) para qualificar a intenção e gerar o LTV Preditivo.
-4. **Envio para as Plataformas:** O Facebook/Google/LinkedIn recebem um payload limpo (sem bot) recheado com valor financeiro de intenção extrema.
-5. **Máquina Autônoma (Background):** Meu banco SQLite (D1) retroalimenta os processos de Clustering (Fase 1) e Bidding (Fase 2) de forma autônoma pelas costas do usuário (`ctx.waitUntil`).
-
-**Minha Vantagem Absoluta (A "Killer Feature")**
-- **A Extinção da Latência:** Destruo concorrentes como GTM/Stape mitigando a latência do servidor (+150ms) para as antenas da Cloudflare Brasileira (~5ms). Custando absurdamente menos (Tier Free ou $5/mês na infraestrutura).
-- **Cookies Indestrutíveis:** Meus *First-Party Cookies Seguros* originam diretamente da nuvem, imunes hoje às varreduras massivas de 24 horas usadas por AdBlockers e Safari (Apple ITP).
-- **Filas Inquebráveis (Fail-Safe + Queues):** Se a AI Cloudflare cair ocasionalmente, eu recuo pro LTV $0. Se a Meta CAPI espirrar 500 downtime, o sistema guarda religiosamente os seus eventos caros em *Cloudflare Queues* e faz o retry sucessivo. Sou incansável na garantia de Event Match Quality (EMQ).
-
----
-
-## 📋 CHANGELOG v2.0.0 (9 de Abril de 2026)
-
-### 🆕 Sprint Enterprise — Fases 1 a 4
-
-#### ✅ Fase 1 — ML Clustering (Segmentação Dinâmica)
-- **`POST /api/segmentation/cluster`** — K-means / DBSCAN / Hierarchical via Workers AI
-- **`GET  /api/segmentation/list`** — Segmentos ativos com métricas
-- **`GET  /api/segmentation/outliers`** — Detecção de outliers comportamentais
-- **`PUT  /api/segmentation/update`** — Atualização de metadados de segmento
-- Schema D1: `ml_segments`, `ml_segment_members` + VIEWs otimizadas
-- Agente: `ml-clustering-agent.md`
-
-#### ✅ Fase 2 — Bidding Recommendations (Otimização de Bids ML)
-- **`POST /api/bidding/recommend`** — Bid otimizado por segmento × plataforma (Meta/Google/TikTok), calculado com fórmula `LTV × ROI target / CPA base`
-- **`GET  /api/bidding/history`** — Histórico completo de recomendações
-- **`GET  /api/bidding/status`** — Snapshot atual das recomendações ativas por vertical
-- Schema D1: `bid_recommendations` + VIEW `v_active_bid_recommendations`
-- Agente: `bidding-agent.md`
-
-#### ✅ Fase 3 — A/B Testing de Prompts LTV
-- **`POST /api/ltv/ab-test/create`** — Cria experimento com múltiplas variações de system prompt
-- **`GET  /api/ltv/ab-test/list`** — Lista experimentos com status e progresso
-- **`GET  /api/ltv/ab-test/results`** — Accuracy score por variação + recomendação automática de winner
-- **`POST /api/ltv/ab-test/winner`** — Declara vencedor e retorna o prompt ganador
-- Integração automática: cada evento Lead sorteia a variação ativa e registra o assignment via KV cache
-- Schema D1: `ltv_ab_tests`, `ltv_ab_variations`, `ltv_ab_assignments` + VIEW `v_ab_test_performance`
-- Agente: `ab-ltv-agent.md`
-
-#### ✅ Fase 4 — Fraud Detection Engine
-- **Fraud Gate automático em `/track`** — roda ANTES de qualquer processamento (heurístico puro, ~2ms)
-- Silent drop (retorna 200 falso) — bots não detectam a defesa
-- **`GET  /api/fraud/stats`** — Dashboard de fraude (últimas 24h)
-- **`GET  /api/fraud/alerts`** — Log de sinais detectados com filtros
-- **`GET  /api/fraud/blocklist`** — IPs/fingerprints atualmente bloqueados
-- **`POST /api/fraud/blocklist/add`** — Bloquear IP ou fingerprint (via KV, efeito imediato)
-- **`DELETE /api/fraud/blocklist/remove`** — Remover do blocklist
-- Sinais detectados: bot_score, datacenter IP, velocity attack, email descartável, headless UA, sem Accept-Language
-- Schema D1: `fraud_signals`, `fraud_alerts` + VIEW `v_fraud_dashboard`
-- Agente: `fraud-detection-agent.md`
-
-### 🔧 Fix: `wrangler.toml` atualizado
-- Todos os placeholders (`SEU_D1_DATABASE_ID`, `SEU_KV_NAMESPACE_ID`) substituídos pelos IDs reais da conta Cloudflare
-- D1: `7867d38f-5fa8-4c17-b465-386211422c09`
-- KV: `821b6c1ccb4b475985439b801c1fdbe0`
-
----
-
-## 🏗️ ARQUITETURA QUANTUM ENTERPRISE (CLOUDFLARE NATIVE)
-
-```mermaid
-graph TD
-    User((Usuário)) -->|Interação| SDK[cdpTrack SDK + Behavior Engine]
-    SDK -->|Edge Fetch 1ª via KV blocklist| FraudGate{🛡️ Fraud Gate}
-    FraudGate -->|score ≥ 80: Silent Drop 200| Void[/dev/null]
-    FraudGate -->|score < 80: Permitido| Worker[Cloudflare Worker Agent]
-    Worker -->|Identity Graph + _cdp_uid| D1[(D1 SQL — 21 tabelas)]
-    Worker -->|LTV + A/B Prompt| AI[Workers AI Llama 3.1 8B]
-    Worker -->|Segmento ML| Cluster[ML Clustering Engine]
-    Cluster -->|Bid otimizado| Bidding[Bidding Recommendations]
-    Worker -->|Background| Queue[Cloudflare Queues]
-    Queue -->|Server Dispatch| Meta[Meta CAPI v22.0]
-    Queue -->|Server Dispatch| Google[GA4 / Google Ads]
-    Queue -->|Server Dispatch| TikTok[TikTok API v1.3]
-    D1 -->|Reports| Dash[Dashboard Agent]
-```
-
----
-
-## 🧠 CATÁLOGO DE AGENTES ESPECIALISTAS
-
-O sistema é composto por **43+ agentes** coordenados pelo **Master Orchestrator**:
-
-### 🧠 Núcleo de Inteligência
-| Agente | Função |
-|---|---|
-| **Master Orchestrator** | Coordenação central — guia todo o setup do projeto |
-| **Page Analyzer** | Mapeamento automático de CTAs, Forms e nicho do site |
-| **Validator Agent** | Auditoria de código, segurança e conformidade de APIs |
-| **Memory Agent** | Contexto e checkpoints da sessão por projeto |
-| **Intelligence Agent** | Monitoramento de versões de API (Meta v22.0+, etc) |
-
-### 🚀 Plataformas de Anúncio
-| Agente | Especialidade |
-|---|---|
-| **Meta Agent** | Facebook Pixel + CAPI v22.0 + WhatsApp CTWA |
-| **Google Agent** | GA4 + Google Ads Enhanced Conversions |
-| **TikTok Agent** | TikTok Pixel + Events API v1.3 |
-| **LinkedIn Agent** | Insight Tag + Conversions API v2 |
-| **Pinterest Agent** | Tag + Conversions API v5 |
-| **Reddit Agent** | Pixel + Conversions API v2.0 |
-| **Spotify Agent** | Pixel + Conversions API v1 |
-| **Bing Agent** | UET Tag + Enhanced Conversions |
-
-### 🤖 Enterprise Intelligence (Fase 1–4)
-| Agente | Endpoint Principal | Impacto |
-|---|---|---|
-| **ML Clustering Agent** | `POST /api/segmentation/cluster` | Segmentação K-means/DBSCAN/Hierarchical |
-| **Bidding Agent** | `POST /api/bidding/recommend` | -20% CPA via bid por segmento de LTV |
-| **A/B LTV Agent** | `POST /api/ltv/ab-test/create` | +25% precisão LTV via test de prompts |
-| **Fraud Detection Agent** | Auto em `/track` | Bloqueia click fraud, bots, velocity attacks |
-
-### 🛡️ Módulos Enterprise
-| Agente | Função |
-|---|---|
-| **Attribution Agent** | Atribuição Multi-Touch de alta fidelidade |
-| **Security Agent** | Rate Limiting, AES-256 e Bot Defense |
-| **Compliance Agent** | LGPD e GDPR (Consent Mode v2) |
-| **Performance Agent** | Otimização de caches e queries D1 |
-
----
-
-## 📊 BANCO DE DADOS D1 — 21 Tabelas
-
-```
-CORE TRACKING           ML & INTELLIGENCE        ENTERPRISE SECURITY
-─────────────────        ─────────────────────    ─────────────────────
-leads                   ml_segments               fraud_signals
-events                  ml_segment_members        fraud_alerts
-sessions                bid_recommendations       ltv_ab_tests
-webhook_events          ltv_ab_tests              ltv_ab_variations
-api_failures            ltv_ab_variations         ltv_ab_assignments
-
-VIEWS
-─────────────────────────────────────────────────
-v_active_segments          → Segmentos ML ativos com contagem de membros
-v_active_bid_recs          → Bids ativos por plataforma/vertical
-v_ab_test_performance      → Accuracy por variação de prompt
-v_fraud_dashboard          → Dashboard fraude 24h
-```
-
----
-
-## 🔄 FLUXO ENTERPRISE COMPLETO
-
-```
-POST /track (evento Lead)
-  │
-  ├─ [1] 🛡️ Fraud Gate (KV blocklist + velocity + heurísticas) ~2ms
-  │         ├─ score < 40  → processa normalmente
-  │         ├─ score 40-79 → processa + loga suspeito (background)
-  │         └─ score ≥ 80  → silent drop 200 + loga (background)
-  │
-  ├─ [2] 🔮 A/B LTV Testing — sorteia variação ativa (KV cache ~0ms)
-  │         └─ passa customSystemPrompt para predictLtv()
-  │
-  ├─ [3] 🧮 LTV Prediction — Workers AI Llama 3.1 8B
-  │         └─ Score 0-100 → class High/Medium/Low → valor em BRL
-  │
-  ├─ [4] 💾 D1 Writes (background via ctx.waitUntil)
-  │         ├─ upsertLtvProfile() → tabela leads
-  │         ├─ recordAbAssignment() → ltv_ab_assignments
-  │         └─ resolveDeviceGraph() → cross-device linking
-  │
-  └─ [5] 📡 CAPI dispatch (Meta + GA4 + TikTok em paralelo)
-            └─ com LTV injetado no value field
-```
-
----
-
-## 💻 INSTALAÇÃO E USO
-
-> ⚠️ **Importante:** Escolha o método de instalação abaixo que melhor se adequa ao seu cenário de implantação.
-
-### OPÇÃO 1 — Instalação Rápida e Confiável (Recomendada via Git Clone)
-
-A forma mais pura, inquebrável e à prova de bugs para iniciar a base de um novo cliente. Basta criar uma pasta "vazia" para o seu cliente, abrir o terminal dentro dela e rodar:
-
-```bash
-git clone https://github.com/ricardosoli777/CDP-Edge-Premium.git .
-```
-*(O ponto no final garante que os arquivos desçam diretamente dentro da pasta atual).*
-
-### OPÇÃO 2 — Instalação via CLI Corporativo (Avançado)
-
-Se preferir usar a linha de comando instalando o nosso CLI Privado do GitHub em todo o computador:
-
-```bash
-npm install -g git+https://github.com/ricardosoli777/CDP-Edge-Premium.git
-cdp-edge install . --name "Nome do Projeto"
-```
-
-### Passo 3 — Ativar no Claude Code
-
-```bash
-claude .
-```
-Dentro do Claude Code:
-```
-/cdp
-```
-
----
-
-## 🚀 DEPLOY COMPLETO (referência)
-
-```bash
-cd server-edge-tracker
-
-# 1. Schemas D1 (todos em sequência)
-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  # Fase 1
-wrangler d1 execute cdp-edge-db --file=schema-bidding.sql --remote        # Fase 2
-wrangler d1 execute cdp-edge-db --file=schema-ab-ltv.sql --remote         # Fase 3
-wrangler d1 execute cdp-edge-db --file=schema-fraud.sql --remote           # Fase 4
-
-# 2. Secrets
-wrangler secret put META_ACCESS_TOKEN
-wrangler secret put GA4_API_SECRET
-wrangler secret put TIKTOK_ACCESS_TOKEN
-
-# 3. Deploy
-wrangler deploy
-```
-
----
-
-## 🖱️ HUMAN-BEHAVIOR ENGINE
-
-| Evento | Pontuação |
-|--------|-----------|
-| Scroll 25–90% | +5 a +15 pts |
-| VSL Watch 25–100% | +10 a +50 pts |
-| Copy Intent (cupom, PIX) | +20 pts |
-| Preenchimento de campo | +10 pts |
-| Rage Click | -10 pts |
-| **Hot Lead (80+ pts)** | **Dispara High_Intent_Lead** |
-
----
-
-## 📋 TODOS OS ENDPOINTS (referência rápida)
-
-### Core Tracking
-| Rota | Método | Função |
-|---|---|---|
-| `/track` | POST | Evento principal (browser → CAPI) |
-| `/health` | GET | Smoke test completo |
-| `/webhook/hotmart` | POST | Webhook Hotmart Purchase |
-| `/webhook/kiwify` | POST | Webhook Kiwify Purchase |
-| `/webhook/ticto` | POST | Webhook Ticto Purchase |
-
-### Intelligence ML
-| Rota | Método | Função |
-|---|---|---|
-| `/api/segmentation/cluster` | POST | Clustering K-means/DBSCAN |
-| `/api/segmentation/list` | GET | Segmentos ativos |
-| `/api/segmentation/outliers` | GET | Outliers comportamentais |
-| `/api/bidding/recommend` | POST | Bid otimizado por segmento |
-| `/api/bidding/history` | GET | Histórico de bids |
-| `/api/bidding/status` | GET | Status por plataforma |
-
-### A/B Testing LTV
-| Rota | Método | Função |
-|---|---|---|
-| `/api/ltv/ab-test/create` | POST | Criar experimento |
-| `/api/ltv/ab-test/list` | GET | Listar experimentos |
-| `/api/ltv/ab-test/results` | GET | Accuracy por variação |
-| `/api/ltv/ab-test/winner` | POST | Declarar vencedor |
-
-### Fraud Detection
-| Rota | Método | Função |
-|---|---|---|
-| `/api/fraud/stats` | GET | Dashboard 24h |
-| `/api/fraud/alerts` | GET | Log de alertas |
-| `/api/fraud/blocklist` | GET | Lista bloqueada |
-| `/api/fraud/blocklist/add` | POST | Bloquear IP/fingerprint |
-| `/api/fraud/blocklist/remove` | DELETE | Desbloquear |
-
----
-
-## 📞 SUPORTE
-
-- **Issues**: https://github.com/ricardosoli777/CDP-Edge-Premium/issues
-- **Releases**: https://github.com/ricardosoli777/CDP-Edge-Premium/releases
-
----
-
-### **CDP Edge — By Rica Soares**
-> "Dados sem inteligência são apenas ruído. No Quantum Tier Enterprise, transformamos dados em ROAS."
-
-© 2026 CDP Edge Premium. Todos os direitos reservados.
+# 🚀 CDP Edge — Quantum Tracking Enterprise
+
+**Padrão Quantum Tracking: 100% Cloudflare Edge.** Sem GTM. Sem Stape. Sem cookies de terceiros.
+
+> **v2.0.3** — Enterprise-Level Intelligence Engine · Cloudflare Workers · Meta CAPI v22.0 · GA4 MP · TikTok Events API v1.3
+
+---
+
+## 🤖 MANIFESTO: EU, CDP EDGE
+
+*Eu não sou um simples "script de pixel". Eu sou uma arquitetura **Enterprise Tier 10** nascida e construída 100% nativa na infraestrutura da Cloudflare.*
+
+**A Linha de Montagem Sincronizada (A Prova de Latência)**
+Meu ecossistema opera como um Cérebro de Conversão Privado na borda. Quando um evento de Lead bate no endpoint `/track`:
+1. **O Escudo Frontal (Fraud Gate):** Inspeciono IP, ASN e Velocity na borda. Bloqueio bots silenciosamente antes mesmo deles carregarem.
+2. **A Roleta Invisível (A/B LTV):** Faço o sorteio de prompts para testes A/B via KV Cache em ~0ms.
+3. **O Cérebro Financeiro (LTV Predictor):** Rodo Machine Learning (Llama 3.1) para qualificar a intenção e gerar o LTV Preditivo.
+4. **Envio para as Plataformas:** O Facebook/Google/LinkedIn recebem um payload limpo (sem bot) recheado com valor financeiro de intenção extrema.
+5. **Máquina Autônoma (Background):** Meu banco SQLite (D1) retroalimenta os processos de Clustering (Fase 1) e Bidding (Fase 2) de forma autônoma pelas costas do usuário (`ctx.waitUntil`).
+
+**Minha Vantagem Absoluta (A "Killer Feature")**
+- **A Extinção da Latência:** Destruo concorrentes como GTM/Stape mitigando a latência do servidor (+150ms) para as antenas da Cloudflare Brasileira (~5ms). Custando absurdamente menos (Tier Free ou $5/mês na infraestrutura).
+- **Cookies Indestrutíveis:** Meus *First-Party Cookies Seguros* originam diretamente da nuvem, imunes hoje às varreduras massivas de 24 horas usadas por AdBlockers e Safari (Apple ITP).
+- **Filas Inquebráveis (Fail-Safe + Queues):** Se a AI Cloudflare cair ocasionalmente, eu recuo pro LTV $0. Se a Meta CAPI espirrar 500 downtime, o sistema guarda religiosamente os seus eventos caros em *Cloudflare Queues* e faz o retry sucessivo. Sou incansável na garantia de Event Match Quality (EMQ).
+
+---
+
+## 📋 CHANGELOG v2.0.3 (10 de Abril de 2026)
+
+### 🔧 Audit Completo — 45 Agentes
+
+- **Endpoints corrigidos**: `/api/tracking` → `/track`, `/api/wh/` → `/webhook/` em todos os agentes
+- **Secrets WhatsApp**: `WA_PHONE_ID`/`WA_ACCESS_TOKEN`/`WHATSAPP_TOKEN` → `WHATSAPP_PHONE_NUMBER_ID`/`WHATSAPP_ACCESS_TOKEN`
+- **`env.DB.prepare`**: corrigido em 8 agentes (attribution, crm, dashboard, debug, performance, security, master-feedback-loop)
+- **`env.GEO_CACHE`**: substituiu `KV.` bare em dashboard-agent, performance-agent, performance-optimization-agent
+- **YouTube events**: `video_milestone`/`video_progress_25/50/75` → `video_25`/`video_50`/`video_75` (alinhado ao VALID_EVENT_NAMES do worker)
+- **LinkedIn CAPI**: endpoint `/rest/conversionEvents` + header `LinkedIn-Version: 202401` em `contracts/api-versions.json`
+- **Workers AI model**: `llama-3-8b-instruct` → `@cf/meta/llama-3.1-8b-instruct`
+- **worker.js**: Content-Length guard (413 se > 64KB), payload validation (allowlist 19 events, 512 chars, value range), PII removido dos logs
+- **Testes**: bugs críticos em `deduplication.test.js` corrigidos (template literals escapados, prefixo errado)
+- **npm**: lodash 4.17.23 → 4.18.1, node-fetch removido
+
+---
+
+## 📋 CHANGELOG v2.0.0 (9 de Abril de 2026)
+
+### 🆕 Sprint Enterprise — Fases 1 a 4
+
+#### ✅ Fase 1 — ML Clustering (Segmentação Dinâmica)
+- **`POST /api/segmentation/cluster`** — K-means / DBSCAN / Hierarchical via Workers AI
+- **`GET  /api/segmentation/list`** — Segmentos ativos com métricas
+- **`GET  /api/segmentation/outliers`** — Detecção de outliers comportamentais
+- **`PUT  /api/segmentation/update`** — Atualização de metadados de segmento
+- Schema D1: `ml_segments`, `ml_segment_members` + VIEWs otimizadas
+- Agente: `ml-clustering-agent.md`
+
+#### ✅ Fase 2 — Bidding Recommendations (Otimização de Bids ML)
+- **`POST /api/bidding/recommend`** — Bid otimizado por segmento × plataforma (Meta/Google/TikTok), calculado com fórmula `LTV × ROI target / CPA base`
+- **`GET  /api/bidding/history`** — Histórico completo de recomendações
+- **`GET  /api/bidding/status`** — Snapshot atual das recomendações ativas por vertical
+- Schema D1: `bid_recommendations` + VIEW `v_active_bid_recommendations`
+- Agente: `bidding-agent.md`
+
+#### ✅ Fase 3 — A/B Testing de Prompts LTV
+- **`POST /api/ltv/ab-test/create`** — Cria experimento com múltiplas variações de system prompt
+- **`GET  /api/ltv/ab-test/list`** — Lista experimentos com status e progresso
+- **`GET  /api/ltv/ab-test/results`** — Accuracy score por variação + recomendação automática de winner
+- **`POST /api/ltv/ab-test/winner`** — Declara vencedor e retorna o prompt ganador
+- Integração automática: cada evento Lead sorteia a variação ativa e registra o assignment via KV cache
+- Schema D1: `ltv_ab_tests`, `ltv_ab_variations`, `ltv_ab_assignments` + VIEW `v_ab_test_performance`
+- Agente: `ab-ltv-agent.md`
+
+#### ✅ Fase 4 — Fraud Detection Engine
+- **Fraud Gate automático em `/track`** — roda ANTES de qualquer processamento (heurístico puro, ~2ms)
+- Silent drop (retorna 200 falso) — bots não detectam a defesa
+- **`GET  /api/fraud/stats`** — Dashboard de fraude (últimas 24h)
+- **`GET  /api/fraud/alerts`** — Log de sinais detectados com filtros
+- **`GET  /api/fraud/blocklist`** — IPs/fingerprints atualmente bloqueados
+- **`POST /api/fraud/blocklist/add`** — Bloquear IP ou fingerprint (via KV, efeito imediato)
+- **`DELETE /api/fraud/blocklist/remove`** — Remover do blocklist
+- Sinais detectados: bot_score, datacenter IP, velocity attack, email descartável, headless UA, sem Accept-Language
+- Schema D1: `fraud_signals`, `fraud_alerts` + VIEW `v_fraud_dashboard`
+- Agente: `fraud-detection-agent.md`
+
+### 🔧 Fix: `wrangler.toml` atualizado
+- Todos os placeholders (`SEU_D1_DATABASE_ID`, `SEU_KV_NAMESPACE_ID`) substituídos pelos IDs reais da conta Cloudflare
+- D1: `7867d38f-5fa8-4c17-b465-386211422c09`
+- KV: `821b6c1ccb4b475985439b801c1fdbe0`
+
+---
+
+## 🏗️ ARQUITETURA QUANTUM ENTERPRISE (CLOUDFLARE NATIVE)
+
+```mermaid
+graph TD
+    User((Usuário)) -->|Interação| SDK[cdpTrack SDK + Behavior Engine]
+    SDK -->|Edge Fetch 1ª via KV blocklist| FraudGate{🛡️ Fraud Gate}
+    FraudGate -->|score ≥ 80: Silent Drop 200| Void[/dev/null]
+    FraudGate -->|score < 80: Permitido| Worker[Cloudflare Worker Agent]
+    Worker -->|Identity Graph + _cdp_uid| D1[(D1 SQL — 21 tabelas)]
+    Worker -->|LTV + A/B Prompt| AI[Workers AI Llama 3.1 8B]
+    Worker -->|Segmento ML| Cluster[ML Clustering Engine]
+    Cluster -->|Bid otimizado| Bidding[Bidding Recommendations]
+    Worker -->|Background| Queue[Cloudflare Queues]
+    Queue -->|Server Dispatch| Meta[Meta CAPI v22.0]
+    Queue -->|Server Dispatch| Google[GA4 / Google Ads]
+    Queue -->|Server Dispatch| TikTok[TikTok API v1.3]
+    D1 -->|Reports| Dash[Dashboard Agent]
+```
+
+---
+
+## 🧠 CATÁLOGO DE AGENTES ESPECIALISTAS
+
+O sistema é composto por **43+ agentes** coordenados pelo **Master Orchestrator**:
+
+### 🧠 Núcleo de Inteligência
+| Agente | Função |
+|---|---|
+| **Master Orchestrator** | Coordenação central — guia todo o setup do projeto |
+| **Page Analyzer** | Mapeamento automático de CTAs, Forms e nicho do site |
+| **Validator Agent** | Auditoria de código, segurança e conformidade de APIs |
+| **Memory Agent** | Contexto e checkpoints da sessão por projeto |
+| **Intelligence Agent** | Monitoramento de versões de API (Meta v22.0+, etc) |
+
+### 🚀 Plataformas de Anúncio
+| Agente | Especialidade |
+|---|---|
+| **Meta Agent** | Facebook Pixel + CAPI v22.0 + WhatsApp CTWA |
+| **Google Agent** | GA4 + Google Ads Enhanced Conversions |
+| **TikTok Agent** | TikTok Pixel + Events API v1.3 |
+| **LinkedIn Agent** | Insight Tag + Conversions API v2 |
+| **Pinterest Agent** | Tag + Conversions API v5 |
+| **Reddit Agent** | Pixel + Conversions API v2.0 |
+| **Spotify Agent** | Pixel + Conversions API v1 |
+| **Bing Agent** | UET Tag + Enhanced Conversions |
+
+### 🤖 Enterprise Intelligence (Fase 1–4)
+| Agente | Endpoint Principal | Impacto |
+|---|---|---|
+| **ML Clustering Agent** | `POST /api/segmentation/cluster` | Segmentação K-means/DBSCAN/Hierarchical |
+| **Bidding Agent** | `POST /api/bidding/recommend` | -20% CPA via bid por segmento de LTV |
+| **A/B LTV Agent** | `POST /api/ltv/ab-test/create` | +25% precisão LTV via test de prompts |
+| **Fraud Detection Agent** | Auto em `/track` | Bloqueia click fraud, bots, velocity attacks |
+
+### 🛡️ Módulos Enterprise
+| Agente | Função |
+|---|---|
+| **Attribution Agent** | Atribuição Multi-Touch de alta fidelidade |
+| **Security Agent** | Rate Limiting, AES-256 e Bot Defense |
+| **Compliance Agent** | LGPD e GDPR (Consent Mode v2) |
+| **Performance Agent** | Otimização de caches e queries D1 |
+
+---
+
+## 📊 BANCO DE DADOS D1 — 21 Tabelas
+
+```
+CORE TRACKING           ML & INTELLIGENCE        ENTERPRISE SECURITY
+─────────────────        ─────────────────────    ─────────────────────
+leads                   ml_segments               fraud_signals
+events                  ml_segment_members        fraud_alerts
+sessions                bid_recommendations       ltv_ab_tests
+webhook_events          ltv_ab_tests              ltv_ab_variations
+api_failures            ltv_ab_variations         ltv_ab_assignments
+
+VIEWS
+─────────────────────────────────────────────────
+v_active_segments          → Segmentos ML ativos com contagem de membros
+v_active_bid_recs          → Bids ativos por plataforma/vertical
+v_ab_test_performance      → Accuracy por variação de prompt
+v_fraud_dashboard          → Dashboard fraude 24h
+```
+
+---
+
+## 🔄 FLUXO ENTERPRISE COMPLETO
+
+```
+POST /track (evento Lead)
+  │
+  ├─ [1] 🛡️ Fraud Gate (KV blocklist + velocity + heurísticas) ~2ms
+  │         ├─ score < 40  → processa normalmente
+  │         ├─ score 40-79 → processa + loga suspeito (background)
+  │         └─ score ≥ 80  → silent drop 200 + loga (background)
+  │
+  ├─ [2] 🔮 A/B LTV Testing — sorteia variação ativa (KV cache ~0ms)
+  │         └─ passa customSystemPrompt para predictLtv()
+  │
+  ├─ [3] 🧮 LTV Prediction — Workers AI Llama 3.1 8B
+  │         └─ Score 0-100 → class High/Medium/Low → valor em BRL
+  │
+  ├─ [4] 💾 D1 Writes (background via ctx.waitUntil)
+  │         ├─ upsertLtvProfile() → tabela leads
+  │         ├─ recordAbAssignment() → ltv_ab_assignments
+  │         └─ resolveDeviceGraph() → cross-device linking
+  │
+  └─ [5] 📡 CAPI dispatch (Meta + GA4 + TikTok em paralelo)
+            └─ com LTV injetado no value field
+```
+
+---
+
+## 💻 INSTALAÇÃO E USO
+
+> ⚠️ **Importante:** Escolha o método de instalação abaixo que melhor se adequa ao seu cenário de implantação.
+
+### OPÇÃO 1 — Instalação Rápida e Confiável (Recomendada via Git Clone)
+
+A forma mais pura, inquebrável e à prova de bugs para iniciar a base de um novo cliente. Basta criar uma pasta "vazia" para o seu cliente, abrir o terminal dentro dela e rodar:
+
+```bash
+git clone https://github.com/ricardosoli777/CDP-Edge-Premium.git .
+```
+*(O ponto no final garante que os arquivos desçam diretamente dentro da pasta atual).*
+
+### OPÇÃO 2 — Instalação via CLI Corporativo (Avançado)
+
+Se preferir usar a linha de comando instalando o nosso CLI Privado do GitHub em todo o computador:
+
+```bash
+npm install -g git+https://github.com/ricardosoli777/CDP-Edge-Premium.git
+cdp-edge install . --name "Nome do Projeto"
+```
+
+### Passo 3 — Ativar no Claude Code
+
+```bash
+claude .
+```
+Dentro do Claude Code:
+```
+/cdp
+```
+
+---
+
+## 🚀 DEPLOY COMPLETO (referência)
+
+```bash
+cd server-edge-tracker
+
+# 1. Schemas D1 (todos em sequência)
+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  # Fase 1
+wrangler d1 execute cdp-edge-db --file=schema-bidding.sql --remote        # Fase 2
+wrangler d1 execute cdp-edge-db --file=schema-ab-ltv.sql --remote         # Fase 3
+wrangler d1 execute cdp-edge-db --file=schema-fraud.sql --remote           # Fase 4
+
+# 2. Secrets
+wrangler secret put META_ACCESS_TOKEN
+wrangler secret put GA4_API_SECRET
+wrangler secret put TIKTOK_ACCESS_TOKEN
+
+# 3. Deploy
+wrangler deploy
+```
+
+---
+
+## 🖱️ HUMAN-BEHAVIOR ENGINE
+
+| Evento | Pontuação |
+|--------|-----------|
+| Scroll 25–90% | +5 a +15 pts |
+| VSL Watch 25–100% | +10 a +50 pts |
+| Copy Intent (cupom, PIX) | +20 pts |
+| Preenchimento de campo | +10 pts |
+| Rage Click | -10 pts |
+| **Hot Lead (80+ pts)** | **Dispara High_Intent_Lead** |
+
+---
+
+## 📋 TODOS OS ENDPOINTS (referência rápida)
+
+### Core Tracking
+| Rota | Método | Função |
+|---|---|---|
+| `/track` | POST | Evento principal (browser → CAPI) |
+| `/health` | GET | Smoke test completo |
+| `/webhook/hotmart` | POST | Webhook Hotmart Purchase |
+| `/webhook/kiwify` | POST | Webhook Kiwify Purchase |
+| `/webhook/ticto` | POST | Webhook Ticto Purchase |
+
+### Intelligence ML
+| Rota | Método | Função |
+|---|---|---|
+| `/api/segmentation/cluster` | POST | Clustering K-means/DBSCAN |
+| `/api/segmentation/list` | GET | Segmentos ativos |
+| `/api/segmentation/outliers` | GET | Outliers comportamentais |
+| `/api/bidding/recommend` | POST | Bid otimizado por segmento |
+| `/api/bidding/history` | GET | Histórico de bids |
+| `/api/bidding/status` | GET | Status por plataforma |
+
+### A/B Testing LTV
+| Rota | Método | Função |
+|---|---|---|
+| `/api/ltv/ab-test/create` | POST | Criar experimento |
+| `/api/ltv/ab-test/list` | GET | Listar experimentos |
+| `/api/ltv/ab-test/results` | GET | Accuracy por variação |
+| `/api/ltv/ab-test/winner` | POST | Declarar vencedor |
+
+### Fraud Detection
+| Rota | Método | Função |
+|---|---|---|
+| `/api/fraud/stats` | GET | Dashboard 24h |
+| `/api/fraud/alerts` | GET | Log de alertas |
+| `/api/fraud/blocklist` | GET | Lista bloqueada |
+| `/api/fraud/blocklist/add` | POST | Bloquear IP/fingerprint |
+| `/api/fraud/blocklist/remove` | DELETE | Desbloquear |
+
+---
+
+## 📞 SUPORTE
+
+- **Issues**: https://github.com/ricardosoli777/CDP-Edge-Premium/issues
+- **Releases**: https://github.com/ricardosoli777/CDP-Edge-Premium/releases
+
+---
+
+### **CDP Edge — By Rica Soares**
+> "Dados sem inteligência são apenas ruído. No Quantum Tier Enterprise, transformamos dados em ROAS."
+
+© 2026 CDP Edge Premium. Todos os direitos reservados.