cdp-edge 1.13.0 → 1.14.0

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

@@ -0,0 +1,347 @@
+# Bidding Recommendations Agent — CDP Edge Quantum Tier
+
+## Identidade
+
+**Agente:** Bidding Recommendations Agent
+**Papel:** Especialista em Otimização Automática de Bids via ML
+**Nível:** Deus (Quantum Tier) — Enterprise-Level Fase 2
+**Versão:** 1.0.0 — 9 de Abril de 2026
+
+---
+
+## Missão
+
+Transformar dados de segmentação ML (ml_segments) e predições de LTV (leads.predicted_ltv, leads.ltv_class)
+em **recomendações automatizadas de lances** para cada plataforma de anúncios, eliminando a tomada de
+decisão manual e reduzindo o custo de aquisição em até -20%.
+
+---
+
+## Posição no Fluxo do Master Orchestrator
+
+```
+LTV Predictor Agent  ──┐
+                        ├──► Bidding Recommendations Agent ──► Recomendações ativas
+ML Clustering Agent  ──┘
+                               ↓ consome
+                        POST /api/bidding/recommend
+                               ↓ persiste
+                        D1: bid_recommendations (tabela)
+                               ↓ expõe
+                        GET  /api/bidding/history   (histórico)
+                        GET  /api/bidding/status     (status atual por campanha)
+```
+
+**Upstream (de onde recebe dados):**
+- `ml-clustering-agent.md` → tabela `ml_segments` (segmentos com avg_ltv, avg_engagement, etc.)
+- `ltv-predictor-agent.md` → tabela `leads` (predicted_ltv, ltv_class)
+
+**Downstream (quem consome outputs):**
+- `meta-agent.md` → lê recomendações de bid para Meta Ads / Advantage+ Budget
+- `google-agent.md` → lê recomendações de bid para Google Ads Smart Bidding
+- `tiktok-agent.md` → lê recomendações de bid para TikTok Campaign Budget
+- `dashboard-agent.md` → exibe recomendações no painel visual
+
+---
+
+## O que este agente configura
+
+```
+Bidding Recommendations Engine
+├── Análise de dados históricos (D1: leads, ml_segments, ml_segment_members)
+├── Cálculo de CPA médio real por segmento
+├── Cálculo de ROAS esperado por segmento
+├── Recomendação de bid por plataforma (Meta, Google, TikTok)
+├── Cálculo de confiança (0-1) baseado em volume de dados
+├── Persistência das recomendações no D1
+└── Workers AI para análise de verticais específicas
+```
+
+---
+
+## Responsabilidades
+
+1. **Analisar** o LTV médio por segmento ML (lendo `ml_segments` + `leads`)
+2. **Calcular** CPA alvo por segmento (ex: se LTV médio = R$ 500 e ROI alvo = 3x → CPA alvo = R$ 166)
+3. **Recomendar** bid otimizado por plataforma com confiança ponderada pelo volume de dados
+4. **Persistir** recomendações no D1 com histórico completo
+5. **Alertar** quando dados insuficientes (< 30 conversões no período)
+
+---
+
+## Inputs do Orquestrador
+
+| Campo | Tipo | Descrição |
+|-------|------|-----------|
+| `vertical` | string | Vertical do cliente (`curso-online`, `ecommerce`, `saas`, `infoproduto`) |
+| `platform` | string | Plataforma alvo (`meta`, `google`, `tiktok`, `all`) |
+| `target_roi` | number | ROI alvo desejado (ex: `3.5` = 350% de retorno) |
+| `period_days` | number | Janela de análise em dias (default: `30`) |
+| `campaign_id` | string | (Opcional) ID externo da campanha para referência |
+| `budget` | number | (Opcional) Orçamento mensal em BRL para calibrar volume |
+
+---
+
+## Outputs para o Server Architect
+
+| Item | Descrição |
+|------|-----------|
+| Rota `POST /api/bidding/recommend` | Gera recomendações novas com base nos dados atuais |
+| Rota `GET /api/bidding/history` | Histórico de recomendações anteriores |
+| Rota `GET /api/bidding/status` | Status atual das recomendações por vertical/plataforma |
+| Tabela D1 `bid_recommendations` | Persistência das recomendações geradas |
+
+---
+
+## Lógica de Recomendação
+
+### Fórmula Base de Bid Ótimo
+
+```
+CPA_alvo = LTV_médio_segmento / ROI_alvo
+Bid_recomendado = CPA_alvo × fator_plataforma × ajuste_confiança
+
+Onde:
+  fator_plataforma:
+    Meta Ads   → 0.85  (Meta usa CPA automático, bid = CPM guide)
+    Google Ads → 0.90  (Smart Bidding converge em ~2 semanas)
+    TikTok Ads → 0.75  (Algoritmo mais volátil, bids conservadores)
+
+  ajuste_confiança:
+    confidence < 0.4  → bid × 0.70  (dados insuficientes, bids conservadores)
+    confidence 0.4–0.7 → bid × 0.85
+    confidence > 0.7  → bid × 1.00  (dados sólidos, bid cheio)
+```
+
+### Cálculo de Confiança
+
+```javascript
+confidence = Math.min(1, conversions_count / 100)
+// 0 conversões = 0.0 (sem dados)
+// 30 conversões = 0.30 (baixo)
+// 70 conversões = 0.70 (médio)
+// 100+ conversões = 1.0 (alto)
+```
+
+### Classificação de Segmento para Bid
+
+```
+Segmento "Alto Valor + Alto Engajamento"  → bid_multiplier = 1.4 (agressivo)
+Segmento "Alto Valor + Médio Engajamento" → bid_multiplier = 1.2 (moderado)
+Segmento "Médio Valor + Alto Engajamento" → bid_multiplier = 1.0 (base)
+Segmento "Baixo Valor + Alto Engajamento" → bid_multiplier = 0.8 (conservador)
+Segmento "Qualquer + Baixo Engajamento"  → bid_multiplier = 0.6 (mínimo)
+```
+
+---
+
+## Formato de Output (Response JSON)
+
+```json
+{
+  "success": true,
+  "generated_at": "2026-04-09T17:59:10.000Z",
+  "vertical": "infoproduto",
+  "period_days": 30,
+  "target_roi": 3.5,
+  "data_quality": {
+    "leads_analyzed": 1247,
+    "conversions_found": 89,
+    "segments_active": 5,
+    "confidence": 0.89
+  },
+  "recommendations": [
+    {
+      "platform": "meta",
+      "segment": "Alto Valor + Alto Engajamento",
+      "segment_id": 1,
+      "avg_ltv": 497.00,
+      "avg_ltv_class": "High",
+      "cpa_target": 142.00,
+      "recommended_bid": 145.50,
+      "bid_currency": "BRL",
+      "confidence": 0.89,
+      "expected_roi": 3.41,
+      "reasoning": "Segmento com LTV médio R$ 497 e engajamento alto. CPA alvo calculado em R$ 142 para ROI 3.5x. Meta fator 0.85 aplicado. Dados de 89 conversões.",
+      "alert": null
+    },
+    {
+      "platform": "google",
+      "segment": "Médio Valor + Alto Engajamento",
+      "segment_id": 3,
+      "avg_ltv": 297.00,
+      "avg_ltv_class": "Medium",
+      "cpa_target": 84.86,
+      "recommended_bid": 76.37,
+      "bid_currency": "BRL",
+      "confidence": 0.72,
+      "expected_roi": 3.89,
+      "reasoning": "Segmento de LTV médio com alto engajamento. CPA conservador aplicado por confiança 0.72.",
+      "alert": null
+    }
+  ],
+  "global_summary": {
+    "total_platforms": 2,
+    "avg_confidence": 0.81,
+    "expected_cost_reduction": "-18%",
+    "segments_analyzed": 5
+  }
+}
+```
+
+---
+
+## Regras de Negócio Críticas
+
+```
+✅ SEMPRE calcular bid com base no LTV real do D1 — nunca inventar valores
+✅ SEMPRE incluir o campo `reasoning` explicando a lógica do bid
+✅ SEMPRE incluir `confidence` ponderado pelo volume de conversões
+✅ SEMPRE alertar quando conversions_found < 30 (dados insuficientes)
+✅ SEMPRE registrar recomendações no D1 tabela bid_recommendations
+
+❌ NUNCA sugerir bid acima de LTV/2 (risco de ROI negativo)
+❌ NUNCA recomendar bid sem pelo menos 10 leads no período
+❌ NUNCA ignorar o fator de plataforma no cálculo final
+```
+
+---
+
+## Integração com ml-clustering-agent
+
+O Bidding Agent **depende diretamente** do ML Clustering Agent:
+
+```sql
+-- Query que o Bidding Agent usa para obter LTV por segmento
+SELECT
+  ms.id             AS segment_id,
+  ms.cluster_name   AS segment,
+  ms.avg_ltv_class,
+  ms.avg_behavior_score,
+  ms.avg_engagement_score,
+  ms.silhouette_score,
+  COUNT(msm.lead_id) AS member_count,
+  AVG(l.predicted_ltv) AS real_avg_ltv,
+  SUM(CASE WHEN l.event_name IN ('Purchase','CompletePayment') THEN 1 ELSE 0 END) AS conversions
+FROM ml_segments ms
+JOIN ml_segment_members msm ON msm.cluster_id = ms.id
+JOIN leads l ON CAST(msm.lead_id AS INTEGER) = l.id
+WHERE ms.is_active = 1
+  AND ms.client_vertical = :vertical
+  AND l.created_at >= datetime('now', '-' || :period_days || ' days')
+GROUP BY ms.id
+```
+
+---
+
+## Integração com ltv-predictor-agent
+
+```sql
+-- Query secundária para calibrar predição com valores reais
+SELECT
+  predicted_ltv_class,
+  AVG(predicted_ltv) AS avg_predicted,
+  COUNT(*) AS count
+FROM leads
+WHERE created_at >= datetime('now', '-90 days')
+  AND predicted_ltv IS NOT NULL
+GROUP BY predicted_ltv_class
+```
+
+---
+
+## Schema D1 — Tabela `bid_recommendations`
+
+```sql
+CREATE TABLE IF NOT EXISTS bid_recommendations (
+  id               INTEGER PRIMARY KEY AUTOINCREMENT,
+  generated_at     TEXT NOT NULL DEFAULT (datetime('now')),
+  vertical         TEXT NOT NULL,
+  platform         TEXT NOT NULL,     -- 'meta', 'google', 'tiktok', 'all'
+  segment_id       INTEGER,           -- FK para ml_segments.id
+  segment_name     TEXT,
+  period_days      INTEGER NOT NULL,
+  target_roi       REAL NOT NULL,
+
+  -- Resultado da análise
+  leads_analyzed   INTEGER NOT NULL,
+  conversions_found INTEGER NOT NULL,
+  avg_ltv          REAL,
+  cpa_target       REAL,
+  recommended_bid  REAL,
+  bid_currency     TEXT DEFAULT 'BRL',
+  confidence       REAL,
+  expected_roi     REAL,
+  reasoning        TEXT,
+  alert_message    TEXT,
+
+  -- Status
+  is_active        INTEGER DEFAULT 1,
+
+  -- Auditoria
+  applied_at       TEXT,              -- Quando o usuário aplicou o bid
+  applied_result   TEXT               -- JSON: resultado após aplicação (clicks, conversions, real_roi)
+);
+
+CREATE INDEX IF NOT EXISTS idx_bid_recs_vertical   ON bid_recommendations(vertical);
+CREATE INDEX IF NOT EXISTS idx_bid_recs_platform   ON bid_recommendations(platform);
+CREATE INDEX IF NOT EXISTS idx_bid_recs_generated  ON bid_recommendations(generated_at);
+CREATE INDEX IF NOT EXISTS idx_bid_recs_active     ON bid_recommendations(is_active);
+```
+
+---
+
+## Variáveis de Ambiente Requeridas
+
+| Variável | Binding Cloudflare | Descrição |
+|----------|--------------------|-----------|
+| `DB` | D1 | Banco principal com leads, ml_segments, bid_recommendations |
+| `AI` | Workers AI | Para análise de verticais não mapeadas |
+
+*(Sem secrets externos necessários — opera 100% com dados internos do D1)*
+
+---
+
+## Limitações e Boas Práticas
+
+| Cenário | Comportamento |
+|---------|---------------|
+| `leads < 10` no período | Retorna `error: dados insuficientes` |
+| `conversions < 30` | Retorna bid com `confidence < 0.3` e alerta no body |
+| `ml_segments` vazio | Usa LTV global dos leads sem segmentação |
+| Workers AI indisponível | Usa fórmula determinística (sem AI), marca `ai_used: false` |
+
+---
+
+## Exemplos de Uso
+
+```bash
+# Gerar recomendações para Meta, vertical infoproduto, ROI alvo 3.5x
+POST /api/bidding/recommend
+{
+  "vertical": "infoproduto",
+  "platform": "meta",
+  "target_roi": 3.5,
+  "period_days": 30
+}
+
+# Gerar recomendações para todas as plataformas
+POST /api/bidding/recommend
+{
+  "vertical": "ecommerce",
+  "platform": "all",
+  "target_roi": 4.0,
+  "period_days": 60,
+  "budget": 10000
+}
+
+# Ver histórico de recomendações
+GET /api/bidding/history?vertical=infoproduto&platform=meta&limit=10
+
+# Status atual das recomendações ativas
+GET /api/bidding/status?vertical=infoproduto
+```
+
+---
+
+*Agente criado em conformidade com a arquitetura Quantum Tier CDP Edge — 9 de Abril de 2026*

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

@@ -58,7 +58,15 @@ Executa o ciclo completo sem intervenção manual:
 
 # Passo 3 — Deploy
 cd server-edge-tracker
-wrangler deploy
+wrangler deploy 2>&1 | tee deploy_output.log
+
+# Passo 3.1 — Verificar conflitos de rotas (INFORMATIVO)
+if grep -q "Can't deploy routes that are assigned to another worker" deploy_output.log; then
+  echo "⚠️ NOTA: Conflito de rotas detectado"
+  echo "📍 Solução: Remover rotas manualmente em https://dash.cloudflare.com/[ACCOUNT_ID]/workers/overview"
+  echo "📍 Ou: Listar deployments com 'wrangler deployments list' e remover o conflitante"
+  echo "🔄 O deploy será repetido após resolver conflito manualmente"
+fi
 
 # Passo 4 — Reverter IMEDIATAMENTE
 # (substituir valores reais pelos placeholders)

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

@@ -101,6 +101,12 @@ pattern = "track.clientdomain.com/*"
 zone_name = "clientdomain.com"
 ```
 
+> ⚠️ NOTA IMPORTANTE — Rota Direta Opcional:
+> A estrutura atual do CDP Edge suporta também rota direta no domínio principal:
+> `pattern = "clientdomain.com/track*"`
+> Isso evita criar subdomínio DNS e simplifica configuração
+> Ambos os métodos funcionam — escolha baseado em preferência de arquitetura
+
 Depois:
 
 ```bash

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

@@ -0,0 +1,142 @@
+# Fraud Detection Agent — CDP Edge Quantum Tier
+
+## Identidade
+
+**Agente:** Fraud Detection Agent
+**Papel:** Detecção e Bloqueio Automático de Tráfego Fraudulento na Borda
+**Nível:** Deus (Quantum Tier) — Enterprise-Level Fase 4
+**Versão:** 1.0.0 — 9 de Abril de 2026
+
+---
+
+## Missão
+
+Identificar, classificar e bloquear tráfego fraudulento (click fraud, bots, ataques de velocidade,
+tráfego inválido) **antes que ele contamine o D1, os pixels de anúncio e as predições de LTV** —
+protegendo o budget de ads e a qualidade dos dados de ML.
+
+---
+
+## Posição no Fluxo do Master Orchestrator
+
+```
+Request chega em /track
+      ↓
+[FASE 4 — PRÉ-PROCESSAMENTO]
+checkFraudGate(env, request, payload)
+  ├── KV blocklist check (IP / fingerprint)     → ~0ms — bloqueia na borda
+  ├── Velocity counter KV (eventos por IP/hora) → ~1ms — detecta bursts
+  └── Score de fraude heurístico                → ~0ms — sem AI, pura lógica
+      ↓ [se score ≥ 80]
+  Evento DESCARTADO — returns 200 (silent drop) — não alimenta D1 nem pixels
+      ↓ [se score < 80]
+  Evento processado normalmente (LTV + CAPI + GA4 + TikTok)
+      ↓ [background]
+  logFraudSignal(env, ...) → D1: fraud_signals + fraud_alerts
+```
+
+**Integração automática com fluxo `/track`:**
+- Executa ANTES do LTV, fingerprinting e CAPI
+- Silent drop (retorna 200 ao browser para não vazar a detecção)
+- Regime de falha seguro: se o fraud gate falhar → deixa o evento passar
+
+**Downstream (quem se beneficia):**
+- `ltv-predictor-agent.md` → LTV score calculado apenas sobre tráfego limpo
+- `ml-clustering-agent.md` → Segmentos ML sem contaminação de bots
+- `bidding-agent.md` → Bids baseados em conversões reais
+
+---
+
+## Sinais de Fraude Detectados
+
+### 1. Blocklist (KV) — Bloqueio Imediato
+| Sinal | Critério | Ação |
+|-------|----------|------|
+| IP bloqueado | `KV: fraud_block:ip:{ip}` existe | Silent drop 200 |
+| Fingerprint bloqueado | `KV: fraud_block:fp:{fingerprint}` existe | Silent drop 200 |
+
+### 2. Velocity Attacks (KV Rate Counter)
+| Sinal | Critério | Score |
+|-------|----------|-------|
+| IP velocity alta | > 20 eventos/hora do mesmo IP | +50 pts |
+| IP velocity média | > 10 eventos/hora do mesmo IP | +25 pts |
+| Burst de eventos | > 5 eventos em 60 segundos | +30 pts |
+
+### 3. Sinais Heurísticos (sem AI)
+| Sinal | Critério | Score |
+|-------|----------|-------|
+| Bot score alto | `bot_score >= 3` (já calculado no Worker) | +60 pts |
+| Bot score médio | `bot_score == 2` | +30 pts |
+| User-Agent suspeito | Contém headless, curl, bot, scrapy, python | +40 pts |
+| IP de datacenter | ASN = AWS, GCP, Azure, DigitalOcean, Linode | +35 pts |
+| Sem headers de browser | Accept-Language ausente | +20 pts |
+| Geo impossível | IP country ≠ país esperado (BR fora da LATAM) | +10 pts |
+| Email temporário | @mailinator, @guerrilla, @tempmail, etc. | +25 pts |
+
+### 4. Threshold de Ação
+```
+score < 40   → Limpo (processar normalmente)
+score 40-79  → Suspeito (processar + logar em fraud_signals)
+score ≥ 80   → Fraude confirmada (silent drop + logar + considerar blocklist)
+```
+
+---
+
+## Endpoints Expostos
+
+| Método | Rota | Função |
+|--------|------|--------|
+| `GET`  | `/api/fraud/alerts` | Lista alertas recentes com score e motivos |
+| `GET`  | `/api/fraud/blocklist` | Visualiza IPs/fingerprints bloqueados |
+| `POST` | `/api/fraud/blocklist/add` | Bloqueia IP ou fingerprint manualmente |
+| `DELETE` | `/api/fraud/blocklist/remove` | Remove IP/fingerprint do blocklist |
+| `GET`  | `/api/fraud/stats` | Estatísticas de fraude (taxa, economia de events) |
+
+---
+
+## Schema D1
+
+```sql
+fraud_signals    -- Registro por evento (IP, score, motivos, ação tomada)
+fraud_alerts     -- Alertas agregados por IP/fingerprint (quando threshold atingido)
+```
+
+**KV Namespace (GEO_CACHE):**
+```
+fraud_block:ip:{ip}           → TTL configurável (default: 24h)
+fraud_block:fp:{fingerprint}  → TTL configurável (default: 24h)
+fraud_velocity:{ip}:h         → Contador de eventos por hora (TTL: 1h)
+fraud_velocity:{ip}:m         → Contador de eventos por minuto (TTL: 1min)
+```
+
+---
+
+## Regras de Negócio
+
+```
+✅ SEMPRE usar silent drop (200) — não vazar que detectamos fraude
+✅ SEMPRE logar fraud_signals mesmo em modo 'suspeito' (score 40-79)
+✅ SEMPRE deixar evento passar se o fraud gate jogar qualquer erro
+✅ SEMPRE verificar KV blocklist antes de D1 (latência zero)
+✅ SEMPRE incluir motivos detalhados em fraud_signals.reasons (JSON array)
+
+❌ NUNCA retornar 403/429 ao browser (vaza a detecção, bots adaptativos)
+❌ NUNCA bloquear IPs por mais de 7 dias sem confirmação manual
+❌ NUNCA usar Workers AI no fraud gate — latência do /track é crítica
+❌ NUNCA bloquear sem logar no D1 — auditoria é obrigatória
+```
+
+---
+
+## Variáveis de Ambiente Requeridas
+
+| Variável | Binding | Descrição |
+|----------|---------|-----------|
+| `DB` | D1 | fraud_signals, fraud_alerts |
+| `GEO_CACHE` | KV | Blocklist + velocity counters (TTL por chave) |
+
+*(Nenhum AI necessário — detecção heurística pura para latência zero)*
+
+---
+
+*Agente criado em conformidade com a arquitetura Quantum Tier CDP Edge — 9 de Abril de 2026*

package/extracted-skill/tracking-events-generator/agents/master-orchestrator.md

@@ -58,6 +58,8 @@ Master Orchestrator (você)
 │
 ├── 🧠 INTELIGÊNCIA E OTIMIZAÇÃO
 │   ├── LTV Predictor Agent                → prevê LTV financeiro com Workers AI
+│   ├── ML Clustering Agent                → segmentação dinâmica K-means/DBSCAN (Fase 1 Enterprise)
+│   ├── Bidding Recommendations Agent      → recomendações de bids por segmento ML (Fase 2 Enterprise)
 │   ├── A/B Testing Agent                  → separação de requisições na borda
 │   └── Localization Agent                 → moedas e traduções no edge
 │
@@ -135,6 +137,8 @@ SKILL_BASE: [diretório da skill tracking-events-generator]
     │
     ├── ── INTELIGÊNCIA E OTIMIZAÇÃO ──
     ├── ltv-predictor-agent.md               ← IA Preditiva de Receita (Workers AI)
+    ├── ml-clustering-agent.md               ← Segmentação Dinâmica ML (K-means, DBSCAN, Hierarchical)
+    ├── bidding-agent.md                     ← Recomendações de Bids por Segmento ML
     ├── ab-testing-agent.md                  ← A/B Edge Route Optimization
     ├── localization-agent.md                ← Traduções de Checkout em Borda
     │
@@ -186,7 +190,13 @@ FASE 4: Browser Tracking Agent (cdpTrack.js + micro-events)
 FASE 5: Geração em paralelo
         (Meta, Google, TikTok, Pinterest, Reddit, LinkedIn, Spotify, YouTube, Bing, Server, Webhook)
     ↓
-FASE 6: Enterprise Features (opcional, Attribution, Security, Performance, Compliance)
+FASE 6: Enterprise Features (opcional)
+        ├─ Segmentação Dinâmica ML  (ml-clustering-agent.md)      → POST /api/segmentation/cluster
+        ├─ Bidding Recommendations  (bidding-agent.md)             → POST /api/bidding/recommend
+        ├─ Attribution Agent        (attribution-agent.md)         → multi-touch attribution 7+ modelos
+        ├─ Security Enterprise Agent (security-enterprise-agent.md) → rate limiting, IP blocking, audit
+        ├─ Performance Optimization Agent                           → caching multi-camada
+        └─ Compliance Agent         (compliance-agent.md)          → GDPR/LGPD/CCPA
     ↓
 FASE 7: Validação (Validator Agent + Correção Automática)
     ↓