cdp-edge 1.13.0 → 1.14.0

package/server-edge-tracker/SEGMENTATION-DOCS.md

@@ -0,0 +1,444 @@
+# API de Segmentação Dinâmica ML — Documentação Completa
+
+## Visão Geral
+
+API REST para segmentação dinâmica de leads via Machine Learning (K-means, DBSCAN, Hierarchical).
+
+---
+
+## Endpoints Disponíveis
+
+| Método | Endpoint | Descrição |
+|---|---|---|
+| **POST** | `/api/segmentation/cluster` | Executar clustering K-means |
+| **GET** | `/api/segmentation/list` | Listar todos os segmentos ativos |
+| **GET** | `/api/segmentation/outliers` | Listar leads anômalos (outliers) |
+| **PUT** | `/api/segmentation/update` | Atualizar recomendações de segmento |
+
+---
+
+## 1. POST /api/segmentation/cluster — Executar Clustering
+
+Executa clustering K-means via Workers AI para criar segmentos de leads.
+
+### Request Body
+
+```json
+{
+  "algorithm": "kmeans",              // Opcional: 'kmeans', 'dbscan', 'hierarchical'
+  "n_clusters": 5,                   // Opcional: 3-10 (padrão: 5)
+  "vertical": "curso-online",          // Opcional: vertical do cliente
+  "force": false                        // Opcional: forçar novo clustering
+}
+```
+
+### Response
+
+```json
+{
+  "success": true,
+  "cluster_id": 123,
+  "clustering_algorithm": "kmeans",
+  "n_clusters": 5,
+  "client_vertical": "curso-online",
+  "duration_ms": 12543,
+  "clusters": [
+    {
+      "cluster_id": 0,
+      "name": "Segmento 0 - Alto Valor + Alto Engajamento (SP)",
+      "size": 95,
+      "percentage": 0.25,
+      "characteristics": {
+        "avg_ltv": 497.50,
+        "avg_ltv_class": "High",
+        "avg_behavior_score": 75.3,
+        "avg_engagement_score": 82.1,
+        "avg_intention_level": 85.0,
+        "dominant_countries": ["BR", "AR"],
+        "dominant_states": ["SP", "RJ"],
+        "dominant_utm_sources": ["facebook", "google"],
+        "top_features": ["ltv", "behavior_score", "engagement_score"]
+      },
+      "centroid": {
+        "ltv_class": 0.75,
+        "behavior_score": 0.80,
+        "engagement_score": 0.85
+      },
+      "sample_leads": ["lead_451", "lead_892", "lead_1034"]
+    }
+  ],
+  "silhouette_scores": {
+    "overall": 0.62,
+    "by_cluster": [0.71, 0.58, 0.65, 0.60, 0.55]
+  },
+  "convergence": {
+    "iterations": 47,
+    "final_inertia": 1523.45
+  },
+  "generated_at": "2026-04-09T18:45:32.000Z"
+}
+```
+
+### Exemplo de Uso (cURL)
+
+```bash
+curl -X POST "https://seudominio.com/api/segmentation/cluster" \
+  -H "Content-Type: application/json" \
+  -d '{
+    "algorithm": "kmeans",
+    "n_clusters": 5,
+    "vertical": "curso-online"
+  }'
+```
+
+---
+
+## 2. GET /api/segmentation/list — Listar Segmentos
+
+Lista todos os segmentos ativos com estatísticas detalhadas.
+
+### Query Parameters
+
+| Parâmetro | Tipo | Descrição |
+|---|---|---|
+| `algorithm` | string | Filtro por algoritmo: `kmeans`, `dbscan`, `hierarchical` |
+| `active` | boolean | Filtro por status: `1` (ativo) ou `0` (arquivado) |
+| `limit` | number | Máximo de resultados (padrão: 10) |
+
+### Exemplo de Request
+
+```bash
+curl "https://seudominio.com/api/segmentation/list?algorithm=kmeans&active=1&limit=10"
+```
+
+### Response
+
+```json
+{
+  "success": true,
+  "count": 5,
+  "segments": [
+    {
+      "id": 45,
+      "cluster_id": 123,
+      "cluster_name": "Segmento 0 - Alto Valor + Alto Engajamento (SP)",
+      "clustering_algorithm": "kmeans",
+      "client_vertical": "curso-online",
+      "size": 95,
+      "percentage": 0.25,
+      "avg_ltv": 497.50,
+      "avg_ltv_class": "High",
+      "avg_behavior_score": 75.3,
+      "avg_engagement_score": 82.1,
+      "avg_intention_level": 85.0,
+      "dominant_countries": ["BR", "AR"],
+      "dominant_states": ["SP", "RJ"],
+      "dominant_features": ["ltv", "behavior_score", "engagement_score"],
+      "silhouette_score": 0.71,
+      "action_recommendations": [
+        "Priorizar remarketing em 24h",
+        "Criar lookalike audience de alto valor"
+      ],
+      "bid_recommendations": [
+        {"adset_id": "456", "recommended_bid": "R$ 18.50", "confidence": 0.85}
+      ],
+      "campaign_recommendations": [
+        {"creative": "VSL A", "audience": "Segmento 0"},
+        {"creative": "VSL B", "audience": "Segmento 0"}
+      ],
+      "is_active": true,
+      "created_at": "2026-04-09T18:45:32.000Z",
+      "updated_at": "2026-04-09T18:45:32.000Z"
+    }
+  ]
+}
+```
+
+---
+
+## 3. GET /api/segmentation/outliers — Listar Anomalias
+
+Lista leads considerados outliers/anomalias (detecção DBSCAN).
+
+### Query Parameters
+
+| Parâmetro | Tipo | Descrição |
+|---|---|---|
+| `confidence` | number | Threshold de confiança (padrão: 0.5) |
+| `risk` | string | Filtro por nível: `high`, `medium`, `low` |
+| `limit` | number | Máximo de resultados (padrão: 50) |
+
+### Exemplo de Request
+
+```bash
+curl "https://seudominio.com/api/segmentation/outliers?confidence=0.3&risk=high&limit=20"
+```
+
+### Response
+
+```json
+{
+  "success": true,
+  "outliers": [
+    {
+      "lead_id": "lead_451",
+      "email": "suspicious@example.com",
+      "first_name": "João",
+      "last_name": "Silva",
+      "ltv_class": "High",
+      "behavior_score": 98,
+      "engagement_score": 85,
+      "intention_level": 90,
+      "days_since_lead": 0,
+      "cluster_id": null,
+      "cluster_name": "Outlier",
+      "confidence": 0.12,
+      "distance_to_centroid": 0.89,
+      "is_outlier": true,
+      "outlier_reason": "behavior_score too high (> 95), instant lead, suspicious",
+      "risk_level": "high",
+      "risk_score": 88,
+      "should_block": true,
+      "actionable_reasons": [
+        "Comportamento extremamente ativo (possível bot)",
+        "Lead instantâneo com engajamento muito alto (suspicious)"
+      ],
+      "assigned_at": "2026-04-09T18:47:15.000Z"
+    }
+  ],
+  "statistics": {
+    "total_outliers": 20,
+    "by_risk_level": {
+      "high": 15,
+      "medium": 3,
+      "low": 2
+    },
+    "by_reason": {
+      "behavior_score too high (> 95)": 12,
+      "instant lead": 8,
+      "unusual geo": 0
+    },
+    "avg_confidence": 0.18
+  },
+  "generated_at": "2026-04-09T18:47:15.000Z"
+}
+```
+
+---
+
+## 4. PUT /api/segmentation/update — Atualizar Segmento
+
+Atualiza recomendações de ações, bids e campanhas de um segmento existente.
+
+### Request Body
+
+```json
+{
+  "cluster_id": 45,
+  "action_recommendations": [
+    "Priorizar remarketing em 24h",
+    "Criar lookalike audience de alto valor",
+    "Enrichir creative com copy específico"
+  ],
+  "bid_recommendations": [
+    {"adset_id": "456", "recommended_bid": "R$ 20.00"},
+    {"adset_id": "789", "recommended_bid": "R$ 18.50"}
+  ],
+  "campaign_recommendations": [
+    {"creative": "VSL Segmentado", "audience": "Segmento 0"}
+  ],
+  "is_active": true
+}
+```
+
+### Response
+
+```json
+{
+  "success": true,
+  "cluster_id": 45,
+  "cluster_name": "Segmento 0 - Alto Valor + Alto Engajamento (SP)",
+  "updates_applied": {
+    "action_recommendations": 3,
+    "bid_recommendations": 2,
+    "campaign_recommendations": 1,
+    "is_active": true
+  },
+  "updated_at": "2026-04-09T18:50:23.000Z"
+}
+```
+
+---
+
+## Estrutura das Tabelas D1
+
+### ml_segments — Metadados dos Segmentos
+
+```sql
+CREATE TABLE ml_segments (
+  id INTEGER PRIMARY KEY,
+  cluster_id INTEGER NOT NULL,
+  cluster_name TEXT NOT NULL,
+  clustering_algorithm TEXT NOT NULL,        -- 'kmeans', 'dbscan', 'hierarchical'
+  client_vertical TEXT,
+  created_at TEXT,
+  updated_at TEXT,
+
+  -- Estatísticas
+  size INTEGER,                                  -- Nº de leads
+  percentage REAL,                               -- % do total
+
+  -- Centróides (médias)
+  avg_ltv REAL,
+  avg_ltv_class REAL,
+  avg_behavior_score REAL,
+  avg_engagement_score REAL,
+  avg_intention_level REAL,
+
+  -- Características dominantes
+  dominant_countries TEXT,                        -- JSON: ["BR", "US"]
+  dominant_states TEXT,                            -- JSON: ["SP", "RJ"]
+  dominant_cities TEXT,                             -- JSON: ["São Paulo", "Rio"]
+  dominant_timezones TEXT,                           -- JSON: ["America/Sao_Paulo"]
+  dominant_utm_sources TEXT,                        -- JSON: ["facebook", "google"]
+  dominant_features TEXT,                            -- JSON: ["ltv", "behavior_score"]
+
+  -- Métricas de qualidade
+  silhouette_score REAL,                           -- 0-1 (quanto maior, melhor)
+  cohesion REAL,                                    -- Similaridade intra-cluster
+  separation REAL,                                  -- Distância inter-cluster
+  inertia REAL,                                   -- Soma dos quadrados
+
+  -- Recomendações automáticas
+  action_recommendations TEXT,                       -- JSON array
+  bid_recommendations TEXT,                           -- JSON array
+  campaign_recommendations TEXT,                        -- JSON array
+
+  -- Metadados
+  is_active INTEGER DEFAULT 1,
+  min_data_points INTEGER,
+  epsilon REAL,                                      -- DBSCAN
+  min_samples INTEGER,                                -- DBSCAN
+  max_depth INTEGER                                   -- Hierarchical
+);
+```
+
+### ml_segment_members — Associação Lead ↔ Segmento
+
+```sql
+CREATE TABLE ml_segment_members (
+  id INTEGER PRIMARY KEY,
+  lead_id TEXT NOT NULL,
+  cluster_id INTEGER NOT NULL,
+  clustering_algorithm TEXT NOT NULL,
+  confidence REAL NOT NULL,                          -- 0-1 (quão perto do centroide)
+  distance_to_centroid REAL,
+  updated_at TEXT,
+  assigned_at TEXT,
+  is_outlier INTEGER DEFAULT 0,
+  outlier_reason TEXT,
+
+  -- Estado do lead no momento da atribuição
+  lead_ltv REAL,
+  lead_ltv_class REAL,
+  lead_behavior_score REAL,
+  lead_engagement_score REAL,
+  lead_intention_level REAL,
+
+  -- Características
+  lead_country TEXT,
+  lead_state TEXT,
+  lead_city TEXT,
+
+  UNIQUE(lead_id, cluster_id, clustering_algorithm)
+);
+```
+
+---
+
+## Integração com Outros Agentes
+
+### Com LTV Predictor Agent
+
+```typescript
+// Enricher predição LTV com segment_id
+const enrichedLTV = {
+  original_prediction: 497.50,
+  segment_id: 123,
+  segment_name: "Alto Valor + Alto Engajamento (SP)",
+  adjusted_prediction: 612.30,  // +23% baseado no segmento
+  confidence: 0.85
+};
+```
+
+### Com Dashboard Agent
+
+```typescript
+// Visualização de segmentos em gráficos
+const segmentChartData = {
+  labels: ["Segmento 0", "Segmento 1", "Segmento 2"],
+  data: [95, 150, 120, 85, 50],
+  colors: ["#22c55e", "#3b82f6", "#1e40af", "#06b6d4", "#f59e0b"]
+};
+```
+
+### Com Meta Agent
+
+```typescript
+// Criar campanhas segmentadas por segmento
+const segmentedCampaigns = [
+  {
+    adset_name: "Segmento 0 - Alto Valor",
+    audience: ml_segment_id_123,
+    creative: "VSL Personalizado Segmento 0",
+    bid_strategy: "high_bid"
+  }
+];
+```
+
+---
+
+## Troubleshooting Comum
+
+### Erro: "Dados insuficientes para clustering"
+
+**Causa:** Menos de 100 leads nos últimos 6 meses
+
+**Solução:**
+- Aguardar mais dados acumularem
+- Aumentar `max_data_age_months` para 12
+- Usar `force=true` para clustering com menos dados
+
+### Erro: "Silhouette Score < 0.3"
+
+**Causa:** Clusters não são bem separados
+
+**Solução:**
+- Aumentar `n_clusters` para 7-10
+- Reduzir dimensionalidade (usar features mais importantes)
+- Usar algoritmo `hierarchical` em vez de `kmeans`
+
+### Erro: "Workers AI timeout"
+
+**Causa:** Prompt muito longo ou muitos dados
+
+**Solução:**
+- Reduzir leads por batch (max 500)
+- Simplificar prompt (menos instruções)
+- Aumentar timeout no wrangler.toml
+
+---
+
+## Roadmap Futuro
+
+- [ ] DBSCAN Clustering completo (outliers avançado)
+- [ ] Hierarchical Clustering (drill-down de clusters)
+- [ ] Auto-feature selection (identificar features mais importantes)
+- [ ] Clustering temporal (leads mudam de segmento ao longo do tempo)
+- [ ] A/B testing automático de segmentos
+- [ ] Dashboard visual de segmentos em gráficos interativos
+
+---
+
+*API de Segmentação Dinâmica ML v1.0 — CDP Edge*
+*Data: 9 de Abril de 2026*

package/server-edge-tracker/schema-ab-ltv.sql

@@ -0,0 +1,97 @@
+-- Schema A/B Testing de Prompts LTV — CDP Edge Quantum Tier
+-- Versão: 1.0
+-- Data: 9 de Abril de 2026
+-- Fase 3 Enterprise-Level
+
+-- TABELA: Experimentos A/B
+CREATE TABLE IF NOT EXISTS ltv_ab_tests (
+  id            INTEGER PRIMARY KEY AUTOINCREMENT,
+  name          TEXT NOT NULL,
+  description   TEXT,
+  status        TEXT NOT NULL DEFAULT 'draft',  -- 'draft', 'running', 'paused', 'completed'
+  winner_id     INTEGER,                         -- FK para ltv_ab_variations.id
+  started_at    TEXT,
+  completed_at  TEXT,
+  created_at    TEXT NOT NULL DEFAULT (datetime('now')),
+  min_sample    INTEGER NOT NULL DEFAULT 100,    -- Mínimo de assignments para declarar vencedor
+  confidence_threshold REAL NOT NULL DEFAULT 0.90  -- Nível de confiança estatística (90%)
+);
+
+-- TABELA: Variações de Prompt por Experimento
+CREATE TABLE IF NOT EXISTS ltv_ab_variations (
+  id            INTEGER PRIMARY KEY AUTOINCREMENT,
+  test_id       INTEGER NOT NULL REFERENCES ltv_ab_tests(id),
+  name          TEXT NOT NULL,                   -- Ex: 'Variação A — Foco em Engajamento'
+  system_prompt TEXT NOT NULL,                   -- O prompt system enviado ao Workers AI
+  weight        REAL NOT NULL DEFAULT 0.5,       -- Peso de distribuição (0-1, soma deve = 1)
+  is_control    INTEGER NOT NULL DEFAULT 0,      -- 1 = variação controle (baseline)
+
+  -- Métricas acumuladas
+  total_assigned    INTEGER NOT NULL DEFAULT 0,
+  total_purchases   INTEGER NOT NULL DEFAULT 0,
+  sum_predicted_ltv REAL NOT NULL DEFAULT 0,
+  sum_real_revenue  REAL NOT NULL DEFAULT 0,
+
+  -- Métricas calculadas (atualizadas por trigger ou batch)
+  avg_predicted_ltv REAL,
+  avg_real_revenue  REAL,
+  conversion_rate   REAL,
+  accuracy_score    REAL,  -- Quão próximo do valor real (1 - |predicted-real|/real)
+
+  created_at    TEXT NOT NULL DEFAULT (datetime('now'))
+);
+
+-- TABELA: Assignments — qual variação foi usada para qual lead
+CREATE TABLE IF NOT EXISTS ltv_ab_assignments (
+  id            INTEGER PRIMARY KEY AUTOINCREMENT,
+  test_id       INTEGER NOT NULL REFERENCES ltv_ab_tests(id),
+  variation_id  INTEGER NOT NULL REFERENCES ltv_ab_variations(id),
+  user_id       TEXT NOT NULL,
+  email_hash    TEXT,                    -- SHA256 do email (indexação sem PII)
+  predicted_ltv REAL,
+  predicted_class TEXT,
+  assigned_at   TEXT NOT NULL DEFAULT (datetime('now')),
+
+  -- Preenchido quando purchase chega via webhook
+  converted     INTEGER NOT NULL DEFAULT 0,
+  real_revenue  REAL,
+  converted_at  TEXT
+);
+
+-- Índices
+CREATE INDEX IF NOT EXISTS idx_ab_tests_status       ON ltv_ab_tests(status);
+CREATE INDEX IF NOT EXISTS idx_ab_variations_test    ON ltv_ab_variations(test_id);
+CREATE INDEX IF NOT EXISTS idx_ab_assignments_test   ON ltv_ab_assignments(test_id);
+CREATE INDEX IF NOT EXISTS idx_ab_assignments_user   ON ltv_ab_assignments(user_id);
+CREATE INDEX IF NOT EXISTS idx_ab_assignments_email  ON ltv_ab_assignments(email_hash);
+CREATE INDEX IF NOT EXISTS idx_ab_assignments_conv   ON ltv_ab_assignments(converted);
+
+-- VIEW: Resumo de performance por variação
+CREATE VIEW IF NOT EXISTS v_ab_test_performance AS
+SELECT
+  t.id            AS test_id,
+  t.name          AS test_name,
+  t.status,
+  v.id            AS variation_id,
+  v.name          AS variation_name,
+  v.is_control,
+  v.weight,
+  v.total_assigned,
+  v.total_purchases,
+  CASE WHEN v.total_assigned > 0
+    THEN ROUND(CAST(v.total_purchases AS REAL) / v.total_assigned * 100, 2)
+    ELSE 0
+  END AS conversion_rate_pct,
+  CASE WHEN v.total_assigned > 0
+    THEN ROUND(v.sum_predicted_ltv / v.total_assigned, 2)
+    ELSE 0
+  END AS avg_predicted_ltv,
+  CASE WHEN v.total_purchases > 0
+    THEN ROUND(v.sum_real_revenue / v.total_purchases, 2)
+    ELSE 0
+  END AS avg_real_revenue,
+  v.accuracy_score,
+  t.winner_id = v.id AS is_winner
+FROM ltv_ab_tests t
+JOIN ltv_ab_variations v ON v.test_id = t.id
+ORDER BY t.id, v.id;

package/server-edge-tracker/schema-bidding.sql

@@ -0,0 +1,86 @@
+-- Schema de Recomendações de Bids Automáticas — CDP Edge Quantum Tier
+-- Versão: 1.0
+-- Data: 9 de Abril de 2026
+-- Complementa: schema-segmentation.sql
+
+-- TABELA PRINCIPAL: Recomendações de Bids
+CREATE TABLE IF NOT EXISTS bid_recommendations (
+  id               INTEGER PRIMARY KEY AUTOINCREMENT,
+  generated_at     TEXT NOT NULL DEFAULT (datetime('now')),
+  vertical         TEXT NOT NULL,                          -- 'infoproduto', 'ecommerce', 'saas'
+  platform         TEXT NOT NULL,                          -- 'meta', 'google', 'tiktok', 'all'
+  period_days      INTEGER NOT NULL DEFAULT 30,            -- Janela de análise
+  target_roi       REAL NOT NULL DEFAULT 3.5,              -- ROI alvo
+
+  -- Segmento ML de origem (FK para ml_segments)
+  segment_id       INTEGER,
+  segment_name     TEXT,
+
+  -- Dados analisados
+  leads_analyzed   INTEGER NOT NULL DEFAULT 0,
+  conversions_found INTEGER NOT NULL DEFAULT 0,
+  avg_ltv          REAL,                                   -- LTV médio do segmento
+  cpa_target       REAL,                                   -- CPA alvo calculado: avg_ltv / target_roi
+
+  -- Output: O Bid em si
+  recommended_bid  REAL,                                   -- Bid recomendado em BRL
+  bid_currency     TEXT NOT NULL DEFAULT 'BRL',
+  confidence       REAL NOT NULL DEFAULT 0,                -- 0-1 (base: conversions / 100)
+  expected_roi     REAL,                                   -- ROI esperado com este bid
+
+  -- Rastreabilidade
+  reasoning        TEXT,                                   -- Explicação detalhada da lógica
+  ai_used          INTEGER DEFAULT 0,                      -- 1 = Workers AI usado
+  alert_message    TEXT,                                   -- Ex: "Dados insuficientes (< 30 conversões)"
+
+  -- Fatores internos de cálculo (para auditoria)
+  platform_factor  REAL,                                   -- 0.75–0.90 por plataforma
+  confidence_adjustment REAL,                              -- 0.70–1.00 por nível de confiança
+  segment_multiplier REAL,                                 -- 0.60–1.40 por tipo de segmento
+
+  -- Ciclo de vida
+  is_active        INTEGER NOT NULL DEFAULT 1,
+  applied_at       TEXT,                                   -- Quando o usuário aplicou o bid
+  applied_campaign TEXT,                                   -- ID da campanha onde foi aplicado
+  applied_result   TEXT                                    -- JSON: {clicks, conversions, real_roi}
+);
+
+-- Índices
+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);
+CREATE INDEX IF NOT EXISTS idx_bid_recs_segment    ON bid_recommendations(segment_id);
+CREATE INDEX IF NOT EXISTS idx_bid_recs_confidence ON bid_recommendations(confidence);
+
+-- VIEW: Recomendações Ativas (com dados dos segmentos)
+CREATE VIEW IF NOT EXISTS v_active_bid_recommendations AS
+SELECT
+  br.id,
+  br.generated_at,
+  br.vertical,
+  br.platform,
+  br.period_days,
+  br.target_roi,
+  br.segment_name,
+  br.leads_analyzed,
+  br.conversions_found,
+  br.avg_ltv,
+  br.cpa_target,
+  br.recommended_bid,
+  br.bid_currency,
+  br.confidence,
+  br.expected_roi,
+  br.reasoning,
+  br.alert_message,
+  br.ai_used,
+  -- Dados do segmento ML relacionado
+  ms.cluster_name    AS ml_cluster_name,
+  ms.avg_behavior_score,
+  ms.avg_engagement_score,
+  ms.silhouette_score,
+  ms.size            AS segment_size
+FROM bid_recommendations br
+LEFT JOIN ml_segments ms ON br.segment_id = ms.id
+WHERE br.is_active = 1
+ORDER BY br.generated_at DESC;