cdp-edge 1.0.0

package/server-edge-tracker/modules/ml/roas.ts

@@ -0,0 +1,255 @@
+/**
+ * CDP Edge — ROAS Feedback Loop (Fase 7)
+ *
+ * Cruza dados de leads (UTM) com compras confirmadas (Purchase events) no D1
+ * para calcular qualidade real de cada campanha:
+ *   → revenue_per_lead, conversion_rate, ltv_accuracy
+ *   → alimenta bidding.ts com dados reais de ROAS
+ *   → relatório semanal via CallMeBot
+ */
+
+import { Env } from '../../types.js';
+import { sendIntelligenceAlert } from '../intelligence.js';
+
+// ── Tipos ─────────────────────────────────────────────────────────────────────
+
+export interface CampaignRoas {
+  utm_source:       string;
+  utm_campaign:     string;
+  utm_content:      string;   // origem do lead: quiz_*, video_*, landing_*, ctwa_*
+  total_leads:      number;
+  confirmed_buyers: number;
+  conversion_rate:  number;   // 0.0–1.0
+  total_revenue:    number;   // soma de value dos Purchase events
+  revenue_per_lead: number;   // total_revenue / total_leads
+  avg_ltv_score:    number;   // média do ltvScore predito (valida accuracy do modelo)
+  ltv_accuracy:     number;   // % de leads com ltvClass=High que realmente compraram
+  top_qualification: string;  // qualificação quiz mais frequente nessa campanha
+  bid_recommendation: 'increase' | 'maintain' | 'decrease' | 'pause';
+}
+
+export interface RoasReport {
+  generated_at:    string;
+  period_days:     number;
+  campaigns:       CampaignRoas[];
+  total_revenue:   number;
+  total_leads:     number;
+  best_campaign:   string | null;
+  worst_campaign:  string | null;
+  model_accuracy:  number;   // % geral do modelo LTV
+}
+
+// ── computeRoasFeedback — calcula ROAS por campanha ───────────────────────────
+
+export async function computeRoasFeedback(
+  env: Env,
+  periodDays = 30,
+): Promise<RoasReport | null> {
+  if (!env.DB) return null;
+
+  try {
+    // Leads com UTM no período + seu LTV predito
+    const leadsRows = await env.DB.prepare(`
+      SELECT
+        COALESCE(l.utm_source,   'direct')   AS utm_source,
+        COALESCE(l.utm_campaign, 'unknown')  AS utm_campaign,
+        COALESCE(l.utm_content,  'unknown')  AS utm_content,
+        l.user_id,
+        l.value                              AS predicted_value,
+        l.intention_level,
+        up.predicted_ltv_class,
+        qs.qualification                     AS quiz_qualification
+      FROM leads l
+      LEFT JOIN user_profiles up ON up.user_id = l.user_id
+      LEFT JOIN quiz_sessions  qs ON qs.user_id = l.user_id
+      WHERE l.created_at >= datetime('now', '-' || ? || ' days')
+        AND l.event_name IN ('Lead','Contact','QuizComplete','CompleteRegistration')
+      ORDER BY l.created_at DESC
+    `).bind(periodDays).all();
+
+    // Compras confirmadas no mesmo período — JOIN por user_id
+    const purchaseRows = await env.DB.prepare(`
+      SELECT
+        l.utm_source,
+        l.utm_campaign,
+        l.utm_content,
+        l.user_id,
+        e.value  AS purchase_value
+      FROM events e
+      JOIN leads l ON l.user_id = e.user_id
+      WHERE e.event_name IN ('Purchase','purchase')
+        AND e.created_at >= datetime('now', '-' || ? || ' days')
+        AND l.event_name IN ('Lead','Contact','QuizComplete','CompleteRegistration')
+    `).bind(periodDays).all();
+
+    const leads    = (leadsRows.results    || []) as any[];
+    const purchases = (purchaseRows.results || []) as any[];
+
+    if (leads.length === 0) return null;
+
+    // Indexa compras por user_id para lookup O(1)
+    const buyerMap = new Map<string, number>(); // user_id → purchase_value
+    for (const p of purchases) {
+      const existing = buyerMap.get(p.user_id) || 0;
+      buyerMap.set(p.user_id, existing + (parseFloat(String(p.purchase_value || 0))));
+    }
+
+    // Agrupa por campanha
+    const campaignMap = new Map<string, {
+      leads: any[];
+      buyers: Set<string>;
+      revenue: number;
+      highLtvLeads: number;
+      highLtvBuyers: number;
+      qualifications: Record<string, number>;
+    }>();
+
+    for (const lead of leads) {
+      const key = `${lead.utm_source}|||${lead.utm_campaign}|||${lead.utm_content || 'unknown'}`;
+      if (!campaignMap.has(key)) {
+        campaignMap.set(key, {
+          leads: [], buyers: new Set(), revenue: 0,
+          highLtvLeads: 0, highLtvBuyers: 0,
+          qualifications: {},
+        });
+      }
+      const c = campaignMap.get(key)!;
+      c.leads.push(lead);
+
+      if (lead.predicted_ltv_class === 'High') c.highLtvLeads++;
+
+      const purchaseValue = buyerMap.get(lead.user_id);
+      if (purchaseValue !== undefined) {
+        c.buyers.add(lead.user_id);
+        c.revenue += purchaseValue;
+        if (lead.predicted_ltv_class === 'High') c.highLtvBuyers++;
+      }
+
+      const qual = lead.quiz_qualification || lead.intention_level || 'unknown';
+      c.qualifications[qual] = (c.qualifications[qual] || 0) + 1;
+    }
+
+    // Monta relatório por campanha
+    const campaigns: CampaignRoas[] = [];
+    for (const [key, c] of campaignMap.entries()) {
+      const [utm_source, utm_campaign, utm_content] = key.split('|||');
+      const total_leads      = c.leads.length;
+      const confirmed_buyers = c.buyers.size;
+      const conversion_rate  = total_leads > 0 ? confirmed_buyers / total_leads : 0;
+      const revenue_per_lead = total_leads > 0 ? c.revenue / total_leads : 0;
+      const avg_ltv_score    = c.leads.reduce((s: number, l: any) => s + parseFloat(String(l.predicted_value || 0)), 0) / total_leads;
+      const ltv_accuracy     = c.highLtvLeads > 0 ? c.highLtvBuyers / c.highLtvLeads : 0;
+
+      const top_qualification = Object.entries(c.qualifications)
+        .sort((a, b) => b[1] - a[1])[0]?.[0] || 'unknown';
+
+      // Recomendação de bid baseada em conversão + accuracy
+      let bid_recommendation: CampaignRoas['bid_recommendation'];
+      if (conversion_rate >= 0.15 && ltv_accuracy >= 0.6)      bid_recommendation = 'increase';
+      else if (conversion_rate >= 0.05 && ltv_accuracy >= 0.3)  bid_recommendation = 'maintain';
+      else if (conversion_rate > 0 && confirmed_buyers > 0)      bid_recommendation = 'decrease';
+      else                                                        bid_recommendation = 'pause';
+
+      campaigns.push({
+        utm_source, utm_campaign, utm_content,
+        total_leads, confirmed_buyers,
+        conversion_rate: Math.round(conversion_rate * 10000) / 10000,
+        total_revenue: Math.round(c.revenue * 100) / 100,
+        revenue_per_lead: Math.round(revenue_per_lead * 100) / 100,
+        avg_ltv_score: Math.round(avg_ltv_score * 100) / 100,
+        ltv_accuracy: Math.round(ltv_accuracy * 10000) / 10000,
+        top_qualification,
+        bid_recommendation,
+      });
+    }
+
+    // Ordena por revenue total desc
+    campaigns.sort((a, b) => b.total_revenue - a.total_revenue);
+
+    const total_revenue  = campaigns.reduce((s, c) => s + c.total_revenue, 0);
+    const total_leads    = campaigns.reduce((s, c) => s + c.total_leads, 0);
+    // model_accuracy: média ponderada de ltv_accuracy por campanha (High LTV que realmente compraram)
+    const model_accuracy = campaigns.length > 0
+      ? campaigns.reduce((s, c) => s + c.ltv_accuracy * c.total_leads, 0) / Math.max(total_leads, 1)
+      : 0;
+
+    const best_campaign  = campaigns.find(c => c.bid_recommendation === 'increase')
+      ? `${campaigns[0].utm_source} / ${campaigns[0].utm_campaign}`
+      : null;
+    const worst_campaign = campaigns.find(c => c.bid_recommendation === 'pause')
+      ? (() => { const w = campaigns.find(c => c.bid_recommendation === 'pause')!; return `${w.utm_source} / ${w.utm_campaign}`; })()
+      : null;
+
+    // Persiste no D1 para histórico
+    await _persistRoasReport(env, campaigns, periodDays);
+
+    return {
+      generated_at:   new Date().toISOString(),
+      period_days:    periodDays,
+      campaigns,
+      total_revenue:  Math.round(total_revenue * 100) / 100,
+      total_leads,
+      best_campaign,
+      worst_campaign,
+      model_accuracy: Math.round(model_accuracy * 10000) / 10000,
+    };
+
+  } catch (err: any) {
+    console.error('[ROAS] computeRoasFeedback error:', err?.message || String(err));
+    return null;
+  }
+}
+
+// ── sendRoasAlert — relatório via CallMeBot ───────────────────────────────────
+
+export async function sendRoasAlert(env: Env, report: RoasReport): Promise<void> {
+  const top3 = report.campaigns.slice(0, 3);
+  const lines = top3.map(c =>
+    `• ${c.utm_source}/${c.utm_campaign}/${c.utm_content}: ${c.confirmed_buyers} compradores, R$${c.total_revenue.toLocaleString('pt-BR')} (${(c.conversion_rate * 100).toFixed(1)}% conv) → ${c.bid_recommendation.toUpperCase()}`
+  ).join('\n');
+
+  const pauseCount   = report.campaigns.filter(c => c.bid_recommendation === 'pause').length;
+  const increaseCount = report.campaigns.filter(c => c.bid_recommendation === 'increase').length;
+
+  const details = [
+    `📅 Período: últimos ${report.period_days} dias`,
+    `💰 Receita total: R$${report.total_revenue.toLocaleString('pt-BR')}`,
+    `👥 Total leads: ${report.total_leads}`,
+    `📈 Top campanhas por receita:\n${lines}`,
+    increaseCount > 0 ? `✅ ${increaseCount} campanha(s) recomendada(s) para AUMENTAR bid` : '',
+    pauseCount > 0    ? `⛔ ${pauseCount} campanha(s) recomendada(s) para PAUSAR` : '',
+    report.best_campaign  ? `🏆 Melhor: ${report.best_campaign}` : '',
+    report.worst_campaign ? `🔻 Pior:   ${report.worst_campaign}` : '',
+  ].filter(Boolean).join('\n');
+
+  await sendIntelligenceAlert(env, 'info', 'ROAS Feedback Semanal', details);
+}
+
+// ── _persistRoasReport — salva snapshot no D1 ────────────────────────────────
+
+async function _persistRoasReport(
+  env: Env,
+  campaigns: CampaignRoas[],
+  periodDays: number,
+): Promise<void> {
+  if (!env.DB) return;
+  try {
+    for (const c of campaigns) {
+      await env.DB.prepare(`
+        INSERT INTO roas_reports (
+          utm_source, utm_campaign, utm_content, period_days,
+          total_leads, confirmed_buyers, conversion_rate,
+          total_revenue, revenue_per_lead, ltv_accuracy,
+          top_qualification, bid_recommendation, created_at
+        ) VALUES (?,?,?,?,?,?,?,?,?,?,?,?,datetime('now'))
+      `).bind(
+        c.utm_source, c.utm_campaign, c.utm_content, periodDays,
+        c.total_leads, c.confirmed_buyers, c.conversion_rate,
+        c.total_revenue, c.revenue_per_lead, c.ltv_accuracy,
+        c.top_qualification, c.bid_recommendation,
+      ).run();
+    }
+  } catch (err: any) {
+    console.error('[ROAS] persist error:', err?.message || String(err));
+  }
+}

package/server-edge-tracker/modules/ml/segmentation.ts

@@ -0,0 +1,407 @@
+/**
+ * CDP Edge — ML Clustering (Fase 1)
+ * Handlers das rotas /api/segmentation/*
+ */
+
+import { tryParseJson } from '../utils.js';
+import { Env } from '../../types.js';
+
+// ── Tipos ───────────────────────────────────────────────────────────────────────
+interface KmeansResult {
+  assignments: number[];
+  centroids: number[][];
+}
+
+interface ClusterStats {
+  c: number;
+  size: number;
+  pct: number;
+  avgLtv: number;
+  avgEng: number;
+  avgDays: number;
+  topSource: string;
+  topState: string;
+  topIntent: string;
+}
+
+interface Cluster {
+  cluster_id: number;
+  name: string;
+  size: number;
+  percentage: number;
+  action_recommendation: string;
+  characteristics: {
+    avg_ltv_class: number;
+    avg_engagement_score: number;
+    avg_intention_level: number;
+    avg_days_since_lead: number;
+    dominant_countries: string[];
+    dominant_states: string[];
+    dominant_utm_sources: string[];
+    top_features: string[];
+  };
+}
+
+interface ClusterInfo {
+  cluster_id: number;
+  name: string;
+  action: string;
+}
+
+// ── Helpers K-means vetorial ──────────────────────────────────────────────────
+
+function _cosDist(a: number[], b: number[]): number {
+  let dot = 0, na = 0, nb = 0;
+  for (let i = 0; i < a.length; i++) { dot += a[i]*b[i]; na += a[i]*a[i]; nb += b[i]*b[i]; }
+  return 1 - dot / (Math.sqrt(na) * Math.sqrt(nb) + 1e-10);
+}
+
+function _kmeansRun(vectors: number[][], k: number, maxIter = 25): KmeansResult {
+  const n = vectors.length, dim = vectors[0].length;
+  const centroids = [vectors[Math.floor(Math.random() * n)]];
+  while (centroids.length < k) {
+    const dists = vectors.map(v => Math.min(...centroids.map(c => _cosDist(v, c))));
+    const sum = dists.reduce((a, b) => a + b, 0);
+    let r = Math.random() * sum, cumul = 0;
+    for (let i = 0; i < n; i++) { cumul += dists[i]; if (cumul >= r) { centroids.push(vectors[i]); break; } }
+    if (centroids.length < k) centroids.push(vectors[Math.floor(Math.random() * n)]);
+  }
+  let assignments = new Array(n).fill(0);
+  for (let iter = 0; iter < maxIter; iter++) {
+    let changed = false;
+    for (let i = 0; i < n; i++) {
+      let best = 0, bestD = Infinity;
+      for (let c = 0; c < k; c++) { const d = _cosDist(vectors[i], centroids[c]); if (d < bestD) { bestD = d; best = c; } }
+      if (assignments[i] !== best) { assignments[i] = best; changed = true; }
+    }
+    if (!changed) break;
+    for (let c = 0; c < k; c++) {
+      const members = vectors.filter((_, i) => assignments[i] === c);
+      if (!members.length) continue;
+      for (let d = 0; d < dim; d++) centroids[c][d] = members.reduce((s, v) => s + v[d], 0) / members.length;
+    }
+  }
+  return { assignments, centroids };
+}
+
+function _silhouette(vectors: number[][], assignments: number[], k: number): number {
+  const n = vectors.length;
+  let total = 0;
+  for (let i = 0; i < n; i++) {
+    const ci = assignments[i];
+    const same = vectors.filter((_, j) => j !== i && assignments[j] === ci);
+    const a = same.length ? same.reduce((s, v) => s + _cosDist(vectors[i], v), 0) / same.length : 0;
+    let b = Infinity;
+    for (let c = 0; c < k; c++) {
+      if (c === ci) continue;
+      const other = vectors.filter((_, j) => assignments[j] === c);
+      if (other.length) b = Math.min(b, other.reduce((s, v) => s + _cosDist(vectors[i], v), 0) / other.length);
+    }
+    total += b === Infinity ? 0 : (b - a) / Math.max(a, b);
+  }
+  return Math.round((total / n) * 1000) / 1000;
+}
+
+function _buildLeadProfile(l: any): string {
+  return [
+    `LTV: ${l.predicted_ltv_class || 'desconhecido'}`,
+    `engajamento: ${Math.round(l.engagement_score || 0)}`,
+    `intenção: ${l.intention_level || 'desconhecida'}`,
+    `origem: ${l.utm_source || 'direto'}`,
+    `canal: ${l.utm_medium || 'desconhecido'}`,
+    `país: ${l.country || 'BR'}`,
+    `estado: ${l.state || ''}`,
+    `hora: ${l.hour_of_day || 12}h`,
+    (l.is_weekend ? 'fim-de-semana' : 'dia-útil'),
+    `recência: ${l.days_since_lead || 0} dias`,
+  ].filter(Boolean).join(', ');
+}
+
+// ── POST /api/segmentation/cluster ────────────────────────────────────────────
+// Clustering real: embeddinggemma-300m → K-means vetorial → Granite para nomear
+export async function handleSegmentationCluster(env: Env, request: Request, headers: Headers): Promise<Response> {
+  if (!env.DB) return new Response(JSON.stringify({ error: 'DB não configurado' }), { status: 503, headers });
+  if (!env.AI) return new Response(JSON.stringify({ error: 'Workers AI não configurado' }), { status: 503, headers });
+
+  const url            = new URL(request.url);
+  const algorithm      = url.searchParams.get('algorithm') || 'kmeans';
+  const nClusters      = Math.min(10, Math.max(2, parseInt(url.searchParams.get('n_clusters') || '5')));
+  const clientVertical = url.searchParams.get('vertical') || 'general';
+  const forceRecluster = url.searchParams.get('force') === 'true';
+
+  if (!['kmeans', 'dbscan', 'hierarchical'].includes(algorithm)) {
+    return new Response(JSON.stringify({ error: 'algorithm deve ser: kmeans, dbscan ou hierarchical', received: algorithm }), { status: 400, headers });
+  }
+
+  try {
+    if (!forceRecluster) {
+      const existing = await env.DB.prepare(`
+        SELECT id, created_at, cluster_name FROM ml_segments
+        WHERE clustering_algorithm = ? AND is_active = 1 AND client_vertical = ?
+        ORDER BY created_at DESC LIMIT 1
+      `).bind(algorithm, clientVertical).first();
+      if (existing) {
+        const ageDays = (Date.now() - new Date((existing as any).created_at).getTime()) / 864e5;
+        if (ageDays < 7) {
+          return new Response(JSON.stringify({
+            success: true, message: 'Cluster existente ainda válido (< 7 dias). Use ?force=true para re-clustering.',
+            cluster_id: (existing as any).id, cluster_name: (existing as any).cluster_name,
+            age_days: Math.round(ageDays * 10) / 10, use_existing: true,
+          }), { status: 200, headers });
+        }
+      }
+    }
+
+    const leadsRes = await env.DB.prepare(`
+      SELECT id, predicted_ltv_class, engagement_score, intention_level,
+             country, state, utm_source, utm_medium, bot_score,
+             CAST(strftime('%H', created_at) AS INTEGER) AS hour_of_day,
+             CAST(julianday('now') - julianday(created_at) AS INTEGER) AS days_since_lead,
+             CASE WHEN strftime('%w', created_at) IN ('0','6') THEN 1 ELSE 0 END AS is_weekend
+      FROM leads
+      WHERE created_at >= datetime('now', '-6 months') AND (bot_score IS NULL OR bot_score < 2)
+      ORDER BY RANDOM() LIMIT 2000
+    `).all();
+
+    const leads = leadsRes.results || [];
+    if (leads.length < 50) {
+      return new Response(JSON.stringify({ error: 'Dados insuficientes para clustering. Mínimo: 50 leads.', leads_found: leads.length, required: 50 }), { status: 400, headers });
+    }
+
+    const startTime = Date.now();
+    const sample    = leads.slice(0, 100);
+    const profiles  = sample.map(_buildLeadProfile);
+
+    // Embeddings reais via embeddinggemma-300m
+    const embRes = await env.AI.run('@cf/baai/bge-m3', { text: profiles });
+    const vectors = (embRes as any).data as number[][];
+    if (!vectors || vectors.length < nClusters) throw new Error(`embeddinggemma retornou ${vectors?.length ?? 0} vetores`);
+
+    // K-means vetorial real
+    const { assignments } = _kmeansRun(vectors, nClusters);
+    const silhouetteScore = _silhouette(vectors, assignments, nClusters);
+
+    // Agregação por cluster para nomear com Granite
+    const clusterStats: (ClusterStats | null)[] = Array.from({ length: nClusters }, (_, c) => {
+      const members = sample.filter((_, i) => assignments[i] === c);
+      if (!members.length) return null;
+      const ltvMap: Record<string, number> = { High: 1, Medium: 0.5, Low: 0 };
+      const avgLtv  = members.reduce((s: number, l: any) => s + (ltvMap[l.predicted_ltv_class] ?? 0), 0) / members.length;
+      const avgEng  = members.reduce((s: number, l: any) => s + (l.engagement_score || 0), 0) / members.length;
+      const avgDays = members.reduce((s: number, l: any) => s + (l.days_since_lead || 0), 0) / members.length;
+      const freq = (arr: string[]) => arr.length ? [...arr.reduce((m,s) => m.set(s,(m.get(s)||0)+1), new Map())].sort((a,b)=>b[1]-a[1])[0]?.[0] : null;
+      return {
+        c, size: members.length, pct: Math.round(members.length / sample.length * 100),
+        avgLtv, avgEng, avgDays,
+        topSource: freq(members.map((l: any) => l.utm_source).filter(Boolean)) || 'direto',
+        topState:  freq(members.map((l: any) => l.state).filter(Boolean))      || 'BR',
+        topIntent: freq(members.map((l: any) => l.intention_level).filter(Boolean)) || 'desconhecida',
+      };
+    }).filter(Boolean) as ClusterStats[];
+
+    // Type guard function to filter null values
+    function isNotNull<T>(value: T | null): value is T {
+      return value !== null;
+    }
+
+    const validClusterStats = clusterStats.filter(isNotNull);
+
+    // Granite apenas para nomear segmentos
+    const namingPrompt =
+`Você é especialista em segmentação de clientes. Dê um nome descritivo em português e uma recomendação de campanha para cada segmento. Retorne SOMENTE JSON válido:
+{"segments":[{"cluster_id":0,"name":"...","action":"..."},...]}
+
+${validClusterStats.map(s => `Cluster ${s.c}: LTV=${s.avgLtv.toFixed(2)}, engajamento=${s.avgEng.toFixed(0)}, intenção="${s.topIntent}", origem="${s.topSource}", estado="${s.topState}", recência=${s.avgDays.toFixed(0)} dias, tamanho=${s.size}`).join('\n')}`;
+
+    const nameRes = await env.AI.run('@cf/ibm-granite/granite-4.0-h-micro', { messages: [{ role: 'user', content: namingPrompt }], max_tokens: 800 });
+    let clusterNames: Record<number, ClusterInfo> = {};
+    try {
+      const m = ((nameRes as any)?.response || '').match(/\{[\s\S]*\}/);
+      if (m) {
+        const parsed = JSON.parse(m[0]);
+        (parsed.segments || []).forEach((s: any) => {
+          if (typeof s.cluster_id === 'number') {
+            clusterNames[s.cluster_id] = {
+              cluster_id: s.cluster_id,
+              name: s.name || `Segmento ${s.cluster_id + 1}`,
+              action: s.action || '',
+            };
+          }
+        });
+      }
+    } catch { /* usa nomes fallback */ }
+
+    const duration = Date.now() - startTime;
+
+    const clusters: Cluster[] = validClusterStats.map(s => ({
+      cluster_id: s.c,
+      name: clusterNames[s.c]?.name || `Segmento ${s.c + 1}`,
+      size: s.size, percentage: s.pct,
+      action_recommendation: clusterNames[s.c]?.action || '',
+      characteristics: {
+        avg_ltv_class: s.avgLtv, avg_engagement_score: s.avgEng,
+        avg_intention_level: s.avgLtv, avg_days_since_lead: s.avgDays,
+        dominant_countries: ['BR'], dominant_states: [s.topState || 'BR'],
+        dominant_utm_sources: [s.topSource || 'direto'], top_features: ['ltv', 'engagement', 'intention'],
+      },
+    }));
+
+    await env.DB.prepare(`UPDATE ml_segments SET is_active = 0 WHERE clustering_algorithm = ? AND client_vertical = ? AND is_active = 1`).bind(algorithm, clientVertical).run();
+
+    const now = new Date().toISOString();
+    for (const cluster of clusters) {
+      const ch = cluster.characteristics;
+      await env.DB.prepare(`
+        INSERT INTO ml_segments (
+          cluster_id, cluster_name, clustering_algorithm, client_vertical, size, percentage,
+          avg_ltv_class, avg_behavior_score, avg_engagement_score, avg_intention_level, avg_days_since_lead,
+          dominant_countries, dominant_states, dominant_utm_sources, dominant_features,
+          silhouette_score, action_recommendations, bid_recommendations, campaign_recommendations,
+          is_active, created_at, updated_at
+        ) VALUES (?,?,?,?,?,?,?,?,?,?,?,?,?,?,?,?,?,?,?,1,?,?)
+      `).bind(
+        cluster.cluster_id, cluster.name, algorithm, clientVertical, cluster.size, cluster.percentage,
+        ch.avg_ltv_class, ch.avg_engagement_score, ch.avg_engagement_score, ch.avg_intention_level, ch.avg_days_since_lead,
+        JSON.stringify(ch.dominant_countries), JSON.stringify(ch.dominant_states),
+        JSON.stringify(ch.dominant_utm_sources), JSON.stringify(ch.top_features),
+        silhouetteScore,
+        JSON.stringify([cluster.action_recommendation]), JSON.stringify([]), JSON.stringify([]),
+        now, now,
+      ).run();
+    }
+
+    try {
+      await env.DB.prepare(`
+        INSERT INTO ml_clustering_history (clustering_id, started_at, completed_at, algorithm, n_leads_processed, n_clusters_created, total_duration_ms, workers_ai_neurons_used, status, parameters, results_summary)
+        VALUES (0, ?, datetime('now'), ?, ?, ?, ?, ?, 'completed', ?, ?)
+      `).bind(new Date(startTime).toISOString(), algorithm, leads.length, clusters.length, duration, Math.ceil(duration * 0.01),
+        JSON.stringify({ algorithm, n_clusters: nClusters, vertical: clientVertical, engine: 'embeddinggemma-300m+kmeans' }),
+        JSON.stringify({ clusters: clusters.length, silhouette: silhouetteScore }),
+      ).run();
+    } catch (e: any) { console.error('[Segmentation] history log error:', e?.message || String(e)); }
+
+    return new Response(JSON.stringify({
+      success: true, algorithm, engine: 'embeddinggemma-300m + kmeans vetorial',
+      n_clusters: clusters.length, client_vertical: clientVertical,
+      leads_analyzed: leads.length, sample_embedded: sample.length,
+      duration_ms: duration, silhouette_score: silhouetteScore,
+      clusters, generated_at: now,
+    }), { status: 200, headers });
+
+  } catch (err: any) {
+    console.error('[Segmentation] cluster error:', err?.message || String(err));
+    try {
+      if (env.DB) await env.DB.prepare(`
+        INSERT INTO ml_clustering_history (clustering_id, started_at, algorithm, n_leads_processed, n_clusters_created, total_duration_ms, workers_ai_neurons_used, status, error_message, parameters, results_summary)
+        VALUES (0, datetime('now'), ?, 0, 0, 0, 0, 'failed', ?, ?, '{}')
+      `).bind(algorithm, err?.message || String(err), JSON.stringify({ algorithm, n_clusters: nClusters })).run();
+    } catch { /* não bloquear */ }
+    return new Response(JSON.stringify({ error: 'Erro ao executar clustering', message: err?.message || String(err) }), { status: 500, headers });
+  }
+}
+
+// ── GET /api/segmentation/list ────────────────────────────────────────────────
+export async function handleSegmentationList(env: Env, request: Request, headers: Headers): Promise<Response> {
+  if (!env.DB) return new Response(JSON.stringify({ error: 'DB não configurado' }), { status: 503, headers });
+
+  const url       = new URL(request.url);
+  const algorithm = url.searchParams.get('algorithm') || null;
+  const vertical  = url.searchParams.get('vertical')  || null;
+
+  try {
+    const conditions: string[] = ['is_active = 1'];
+    const bindings: (string | number)[]   = [];
+    if (algorithm) { conditions.push('clustering_algorithm = ?'); bindings.push(algorithm); }
+    if (vertical)  { conditions.push('client_vertical = ?');      bindings.push(vertical); }
+
+    const result   = await env.DB.prepare(`
+      SELECT id, cluster_id, cluster_name, clustering_algorithm, client_vertical,
+             size, percentage, avg_ltv_class, avg_behavior_score, avg_engagement_score,
+             avg_intention_level, avg_days_since_lead, silhouette_score,
+             dominant_countries, dominant_states, dominant_utm_sources, dominant_features,
+             action_recommendations, bid_recommendations, campaign_recommendations,
+             is_active, created_at, updated_at
+      FROM ml_segments
+      WHERE ${conditions.join(' AND ')}
+      ORDER BY created_at DESC
+      LIMIT 50
+    `).bind(...bindings).all();
+
+    const segments = (result.results || []).map((s: any) => ({
+      ...s,
+      dominant_countries:       tryParseJson(s.dominant_countries, []),
+      dominant_states:          tryParseJson(s.dominant_states, []),
+      dominant_utm_sources:     tryParseJson(s.dominant_utm_sources, []),
+      dominant_features:        tryParseJson(s.dominant_features, []),
+      action_recommendations:   tryParseJson(s.action_recommendations, []),
+      bid_recommendations:      tryParseJson(s.bid_recommendations, []),
+      campaign_recommendations: tryParseJson(s.campaign_recommendations, []),
+    }));
+
+    return new Response(JSON.stringify({ success: true, total: segments.length, segments }), { status: 200, headers });
+  } catch (err: any) {
+    console.error('[Segmentation] list error:', err?.message || String(err));
+    return new Response(JSON.stringify({ error: err?.message || String(err) }), { status: 500, headers });
+  }
+}
+
+// ── GET /api/segmentation/outliers ───────────────────────────────────────────
+export async function handleSegmentationOutliers(env: Env, request: Request, headers: Headers): Promise<Response> {
+  if (!env.DB) return new Response(JSON.stringify({ error: 'DB não configurado' }), { status: 503, headers });
+
+  const url   = new URL(request.url);
+  const limit = Math.min(parseInt(url.searchParams.get('limit') || '50'), 200);
+  const days  = parseInt(url.searchParams.get('days') || '30');
+
+  try {
+    const result = await env.DB.prepare(`
+      SELECT msm.lead_id, msm.cluster_id, msm.confidence, msm.is_outlier, msm.outlier_reason, msm.assigned_at,
+             l.email, l.phone, l.country, l.state, l.city, l.utm_source, l.bot_score, l.engagement_score, l.intention_level, l.created_at AS lead_created_at
+      FROM ml_segment_members msm
+      LEFT JOIN leads l ON CAST(msm.lead_id AS INTEGER) = l.id
+      WHERE msm.is_outlier = 1 AND msm.assigned_at >= datetime('now', '-' || ? || ' days')
+      ORDER BY msm.assigned_at DESC
+      LIMIT ?
+    `).bind(days, limit).all();
+
+    return new Response(JSON.stringify({ success: true, total: (result.results || []).length, period_days: days, outliers: result.results || [] }), { status: 200, headers });
+  } catch (err: any) {
+    console.error('[Segmentation] outliers error:', err?.message || String(err));
+    return new Response(JSON.stringify({ error: err?.message || String(err) }), { status: 500, headers });
+  }
+}
+
+// ── PUT /api/segmentation/update ─────────────────────────────────────────────
+export async function handleSegmentationUpdate(env: Env, request: Request, headers: Headers): Promise<Response> {
+  if (!env.DB) return new Response(JSON.stringify({ error: 'DB não configurado' }), { status: 503, headers });
+
+  let body: any;
+  try { body = await request.json(); }
+  catch { return new Response(JSON.stringify({ error: 'JSON inválido no body da requisição' }), { status: 400, headers }); }
+
+  const { cluster_id, action_recommendations, bid_recommendations, campaign_recommendations } = body;
+  if (cluster_id === undefined || cluster_id === null) {
+    return new Response(JSON.stringify({ error: 'cluster_id é obrigatório' }), { status: 400, headers });
+  }
+
+  try {
+    const sets: string[] = [];
+    const bindings: (string | number)[] = [];
+    if (action_recommendations   !== undefined) { sets.push('action_recommendations = ?');   bindings.push(JSON.stringify(action_recommendations)); }
+    if (bid_recommendations      !== undefined) { sets.push('bid_recommendations = ?');      bindings.push(JSON.stringify(bid_recommendations)); }
+    if (campaign_recommendations !== undefined) { sets.push('campaign_recommendations = ?'); bindings.push(JSON.stringify(campaign_recommendations)); }
+
+    if (sets.length === 0) {
+      return new Response(JSON.stringify({ error: 'Nenhum campo válido para atualizar (action_recommendations, bid_recommendations, campaign_recommendations)' }), { status: 400, headers });
+    }
+
+    sets.push("updated_at = datetime('now')");
+    bindings.push(cluster_id);
+
+    await env.DB.prepare(`UPDATE ml_segments SET ${sets.join(', ')} WHERE id = ?`).bind(...bindings).run();
+    return new Response(JSON.stringify({ success: true, cluster_id, fields_updated: sets.length - 1 }), { status: 200, headers });
+  } catch (err: any) {
+    console.error('[Segmentation] update error:', err?.message || String(err));
+    return new Response(JSON.stringify({ error: err?.message || String(err) }), { status: 500, headers });
+  }
+}