cdp-edge 2.0.3 → 2.0.5

package/extracted-skill/tracking-events-generator/MELHORIAS-IMPLEMENTADAS.md

@@ -410,3 +410,104 @@ Todas as 6 melhorias principais + o bônus foram implementadas com sucesso:
 ---
 
 > 🎯 **Conclusão:** O ecossistema CDP Edge agora tem um sistema de agentes **sincronizados, resilientes e auto-corrigíveis**, com memória persistente e atualização automática de APIs. O tempo de desenvolvimento foi drasticamente reduzido e a qualidade do código foi significativamente aumentada.
+
+---
+
+## ✅ FASE 5 — Melhoria Contínua Automática (2026-04-10)
+
+**Status:** ✅ COMPLETO (4 features)
+
+---
+
+### ✅ 1. LTV Real — Regressão Logística Treinada em Dados Reais
+
+**O que foi implementado:**
+- Cron semanal no Worker busca leads × purchases dos últimos 90 dias no D1
+- Treina regressão logística com features reais (ltv_score, behavior_score, engagement_score, utm_source, state)
+- Pesos gravados em `ltv_model_weights` com `is_active = 1` e accuracy registrada
+- Pesos cacheados em KV para acesso em ~0ms por cada evento `/track`
+- Fallback automático para heurística se modelo não estiver disponível
+
+**Arquivos criados/modificados:**
+- `server-edge-tracker/migrate-v7.sql` — Tabela `ltv_model_weights` + `match_quality_log`
+- `server-edge-tracker/modules/ml/ltv.js` — Função de treinamento + predição com modelo treinado
+- `server-edge-tracker/worker.js` — Handler do cron semanal de treinamento
+
+**Benefício:** Score LTV baseado em dados reais do funil (não apenas heurísticas). Bids mais precisos. Experimentos A/B com baseline real.
+
+---
+
+### ✅ 2. Match Quality Alerts — Monitoramento Automático de EMQ
+
+**O que foi implementado:**
+- Cada dispatch para Meta CAPI registra flags em `match_quality_log`: `has_email`, `has_phone`, `has_fbp`, `has_fbc`, `was_email_recovered`
+- View `v_match_quality_24h` agrega os dados por janela de 2 horas
+- Cron semanal verifica os thresholds: email_rate < 40%, fbp_rate < 30%, composite_score < 45%
+- Alerta via CallMeBot quando qualquer threshold é ultrapassado
+
+**Arquivos criados/modificados:**
+- `server-edge-tracker/migrate-v7.sql` — Tabela `match_quality_log` + view `v_match_quality_24h`
+- `server-edge-tracker/modules/dispatch/meta.js` — Log de qualidade após cada dispatch
+- `server-edge-tracker/modules/intelligence.js` — Análise semanal de match quality + alerta
+
+**Benefício:** Degradação de EMQ detectada automaticamente antes de impactar o CPA. Alerta proativo ao invés de descobrir via queda de performance.
+
+---
+
+### ✅ 3. A/B LTV Auto-Winner — Declaração Automática de Vencedor
+
+**O que foi implementado:**
+- Quando uma variação bate o controle por ≥5pp de acurácia, o Worker declara o vencedor automaticamente
+- Prompt vencedor é ativado imediatamente para todos os novos eventos `/track`
+- Alerta WhatsApp enviado com detalhes: nome da variação, diferença de acurácia, prompt ativado
+- Sem necessidade de revisão manual de experimentos
+
+**Arquivos criados/modificados:**
+- `server-edge-tracker/modules/ml/ltv.js` — Lógica de detecção de vencedor automático
+- `server-edge-tracker/modules/dispatch/whatsapp.js` — Alerta de auto-winner
+
+**Benefício:** Experimentos A/B de prompt LTV se resolvem sozinhos. O prompt com maior acurácia é sempre usado sem intervenção manual.
+
+---
+
+### ✅ 4. Auto-Enrich — Identity Graph Antes do Dispatch
+
+**O que foi implementado:**
+- Antes de cada dispatch para Meta CAPI, Worker consulta `user_profiles` pelo `userId` do evento
+- Se o evento chegou sem email/fbp/fbc/phone mas o perfil os tem, os dados são injetados automaticamente
+- Campo `was_email_recovered` registrado em `match_quality_log` para rastreabilidade
+- Processo 100% transparente para o browser
+
+**Arquivos criados/modificados:**
+- `server-edge-tracker/modules/dispatch/meta.js` — Consulta ao Identity Graph antes do dispatch
+- `server-edge-tracker/modules/db.js` — Função `enrichPayloadFromProfile(userId, payload)`
+
+**Benefício:** Eventos que chegariam sem email agora vão para a Meta com Advanced Matching completo. EMQ melhora sem qualquer mudança no browser. Atribuição retroativa funciona melhor.
+
+---
+
+## 📈 NOVAS TABELAS D1 (Fase 5)
+
+| Tabela | Criada em | Conteúdo |
+|---|---|---|
+| `ltv_model_weights` | `migrate-v7.sql` | Pesos do modelo de regressão logística treinado |
+| `match_quality_log` | `migrate-v7.sql` | Flags de qualidade por evento despachado para Meta |
+
+**View criada:** `v_match_quality_24h` — dashboard de EMQ pronto para consulta via SQL.
+
+**Sequência de migration atualizada:**
+```
+schema.sql → migrate-v6.sql → schema-segmentation.sql → schema-bidding.sql
+→ schema-ab-ltv.sql → schema-fraud.sql → schema-indexes.sql → migrate-v7.sql
+```
+
+---
+
+## 🎯 IMPACTO ESPERADO DA FASE 5
+
+| Métrica | Mecanismo | Melhoria Esperada |
+|---|---|---|
+| **EMQ (Event Match Quality)** | Auto-Enrich + Match Quality Alerts | +15-25pp no score Meta |
+| **Precisão de LTV** | Modelo treinado em dados reais | Acurácia > heurística em 2-4 semanas |
+| **Tempo de resposta a degradação** | Alertas automáticos de match quality | Horas vs. dias |
+| **CPA** | Melhor atribuição → otimização Meta mais precisa | -10-20% esperado |

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

@@ -113,10 +113,21 @@ wrangler d1 execute cdp-edge-db --file=schema-ab-ltv.sql --remote
 
 # Fase 4: Fraud Detection
 wrangler d1 execute cdp-edge-db --file=schema-fraud.sql --remote
+
+# Índices compostos de performance (queries D1)
+wrangler d1 execute cdp-edge-db --file=schema-indexes.sql --remote
+
+# Fase 5: LTV Model (regressão logística) + Match Quality Log
+wrangler d1 execute cdp-edge-db --file=migrate-v7.sql --remote
 ```
 
 Após cada migração: confirmar sucesso antes de prosseguir.
 
+> **Fase 5 cria duas tabelas críticas:**
+> - `ltv_model_weights` — pesos do modelo LTV treinado semanalmente pelo cron
+> - `match_quality_log` — registra flags de qualidade de dados (has_email, has_fbp, etc.) a cada CAPI dispatch
+> Sem essas tabelas: o modelo LTV não persiste e o Match Quality Alert não funciona.
+
 ---
 
 ## PROCEDURE `*rollback`

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

@@ -306,6 +306,33 @@ async function checkApiDepreciations(env) {
 
 ---
 
+### MONITORAMENTO AUTOMÁTICO DE MATCH QUALITY (CRON SEMANAL)
+
+O Intelligence Agent monitora a qualidade dos dados enviados ao Meta CAPI a cada execução do cron.
+Os dados são lidos da tabela `match_quality_log` (populada automaticamente pelo Worker a cada dispatch).
+
+**Thresholds obrigatórios — alertar via CallMeBot se:**
+
+| Métrica | Threshold mínimo | Ação automática |
+|---|---|---|
+| `email_rate` | 40% dos eventos com email | Alerta ⚠️ — verificar Identity Graph |
+| `fbp_rate` | 30% dos eventos com cookie fbp | Alerta ⚠️ — verificar cdpTrack.js |
+| `composite_score` | 45% (email×0.4 + fbp×0.3 + phone×0.2 + fbc×0.1) | Alerta 🚨 CRÍTICO |
+
+**O cron semanal executa automaticamente (sem intervenção manual):**
+1. `_trainLtvModel(env)` — re-treina regressão logística com últimos 5000 leads do D1; pesos salvos em `ltv_model_weights` e cache KV invalidado
+2. `_autoDecideAbWinner(env)` — declara winner de A/B LTV se melhoria ≥ 5pp vs controle; alerta WhatsApp automático
+3. `_analyzeMatchQuality(env)` — analisa janela 2h; dispara alertas CallMeBot se abaixo dos thresholds
+4. `syncMetaCustomAudience(env)` — sincroniza leads high_intent com Meta Custom Audience
+
+**Auto-recuperação integrada ao dispatch:**
+- Antes de cada envio ao Meta CAPI, o Worker tenta enriquecer automaticamente o payload consultando o Identity Graph pelo `userId` (recupera email, fbp, fbc, phone ausentes)
+- Resultado de recuperação é logado em `match_quality_log.was_email_recovered`
+
+**Pré-requisito de infraestrutura:** `migrate-v7.sql` deve estar aplicada no D1 (tabelas `ltv_model_weights` + `match_quality_log`).
+
+---
+
 ### CHECK DE NOVOS PARÂMETROS DE EVENT MATCH QUALITY
 
 O Intelligence Agent DEVE buscar novos parâmetros que melhoram a nota de atribuição:

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

@@ -1285,7 +1285,7 @@ Spawnar o **Intelligence Agent** para realizar auditoria completa da stack:
 
 **2. Infraestrutura Cloudflare**
 - `wrangler.toml` — bindings D1, KV, Queue, AI estão todos declarados
-- `schema.sql` e migrations — todas as fases (core, segmentation, bidding, ab-ltv, fraud) aplicadas
+- `schema.sql` e migrations — todas as fases aplicadas na ordem: core → segmentation → bidding → ab-ltv → fraud → schema-indexes → **migrate-v7** (LTV model + Match Quality)
 - Worker.js — endpoints ativos correspondem à arquitetura esperada
 
 **3. Conformidade e Qualidade de Sinal**

package/extracted-skill/tracking-events-generator/agents/server-tracking.md

@@ -526,7 +526,7 @@ async function syncIdentity(DB, body) {
   const fp = body.fingerprint || null;
   if (!fp || !DB) return body;
 
-  const existing = await DB.prepare(
+  const existing = await env.DB.prepare(
     'SELECT * FROM identity_graph WHERE fingerprint = ?'
   ).bind(fp).first();
 
@@ -541,7 +541,7 @@ async function syncIdentity(DB, body) {
       visit_count: (existing.visit_count || 1) + 1
     };
   } else {
-    await DB.prepare(`
+    await env.DB.prepare(`
       INSERT OR IGNORE INTO identity_graph (fingerprint, fbp, fbc, ga_client_id, external_id, ttclid, first_utm)
       VALUES (?, ?, ?, ?, ?, ?, ?)
     `).bind(fp, body.fbp, body.fbc, body.ga_client_id, body.external_id, body.ttclid, JSON.stringify(body.utm || {})).run();
@@ -635,7 +635,7 @@ function buildCookieHeader(visitor, umbrellaDomain) {
 async function logBehavioralEvent(DB, body, visitor, engagementScore) {
   if (!DB) return;
 
-  await DB.prepare(`
+  await env.DB.prepare(`
     INSERT OR REPLACE INTO behavioral_events (
       event_id, user_id, session_id,
       engagement_score, time_level, scroll_score, click_score, video_score, hover_score, intention_level,
@@ -972,7 +972,7 @@ CREATE INDEX IF NOT EXISTS idx_retry_scheduled ON retry_queue(scheduled_at, stat
 async function logEventSuccess(DB, platform, eventId) {
   if (!DB) return;
 
-  await DB.prepare(`
+  await env.DB.prepare(`
     UPDATE events_log
     SET status = 'success',
         retry_count = 0,
@@ -988,7 +988,7 @@ async function logEventFailure(DB, platform, eventId, errorMessage, retryCount)
   const maxRetries = 3;
   const isFinalFailure = retryCount >= maxRetries;
 
-  await DB.prepare(`
+  await env.DB.prepare(`
     UPDATE events_log
     SET status = ?,
         retry_count = ?,

package/extracted-skill/tracking-events-generator/knowledge-base.md

@@ -2892,3 +2892,175 @@ async function sha256(data) {
 4.  **SDK Site**: Inserir `cdpTrack.js` e `tracking.config.js` no site.
 5.  **Event Mapping**: Configurar gatilhos de clique e formulário no site.
 6.  **Webhooks**: Configurar o endpoint de webhook na plataforma de vendas (Ticto/Hotmart).
+
+---
+
+## 🤖 8. MELHORIA CONTÍNUA AUTOMÁTICA (FASE 5)
+
+A Fase 5 fecha o ciclo de dados: cada evento coletado alimenta modelos e alertas que, automaticamente, melhoram a qualidade de atribuição na próxima semana — sem intervenção manual.
+
+---
+
+### 8.1 O Ciclo de Melhoria Contínua
+
+```
+Evento /track
+    │
+    ├─ match_quality_log (has_email, has_fbp, has_phone, has_fbc, was_email_recovered)
+    │       │
+    │       └─ Cron semanal analisa janela de 2h
+    │               → email_rate < 40%  → alerta CallMeBot
+    │               → fbp_rate < 30%    → alerta CallMeBot
+    │               → composite_score < 45% → alerta CallMeBot
+    │
+    ├─ user_profiles (Identity Graph)
+    │       │
+    │       └─ Auto-Enrich: antes de cada dispatch Meta CAPI,
+    │               Worker consulta user_profiles por userId
+    │               → recupera email/fbp/fbc/phone ausentes
+    │               → evento vai para Meta COM email → EMQ sobe
+    │
+    ├─ leads × purchases (D1)
+    │       │
+    │       └─ Cron semanal treina regressão logística
+    │               → pesos gravados em ltv_model_weights (is_active=1)
+    │               → cached em KV → próximo /track usa modelo treinado
+    │               → fallback heurístico se modelo não disponível
+    │
+    └─ user_profiles (alta intenção) → Customer Match Export semanal
+            → GET /export/customer-match → CSV para Google Ads
+            → Meta Custom Audience auto-atualizada
+```
+
+---
+
+### 8.2 Match Quality — Monitoramento Automático
+
+Cada dispatch para a Meta CAPI registra na tabela `match_quality_log`:
+
+| Campo | O que indica |
+|---|---|
+| `has_email` | Evento foi com email (principal fator de EMQ) |
+| `has_phone` | Evento foi com telefone |
+| `has_fbp` | Cookie _fbp presente (atribuição via pixel) |
+| `has_fbc` | Cookie _fbc presente (atribuição via clique em anúncio) |
+| `was_email_recovered` | Email recuperado via Identity Graph (Auto-Enrich) |
+
+**Thresholds de alerta (cron semanal):**
+
+| Métrica | Threshold de alerta | Impacto |
+|---|---|---|
+| `email_rate` | < 40% | Atribuição fraca — muitos eventos sem email |
+| `fbp_rate` | < 30% | Pixel sem rastrear adequadamente |
+| `composite_score` | < 45% | EMQ geral degradado |
+
+A view `v_match_quality_24h` agrega os dados prontos para consulta instantânea:
+
+```sql
+SELECT * FROM v_match_quality_24h;
+-- Retorna: event_count, email_rate, phone_rate, fbp_rate, fbc_rate, composite_score
+```
+
+---
+
+### 8.3 Identity Graph — Auto-Enrich Antes do Dispatch
+
+Antes de cada dispatch para a Meta CAPI, o Worker consulta `user_profiles` usando o `userId` do evento. Se o evento chegou sem email ou sem fbp, mas o perfil do usuário tem esses dados de uma sessão anterior, eles são injetados automaticamente no payload.
+
+**Resultado prático:**
+- Lead preencheu formulário na semana passada (email registrado no perfil)
+- Hoje clicou em anúncio e disparou `ViewContent` sem email
+- Worker recupera o email do perfil → evento vai para Meta COM email
+- Meta recebe o sinal com Advanced Matching completo → melhor atribuição
+- `was_email_recovered = 1` fica registrado em `match_quality_log`
+
+Esse processo é transparente: o browser não precisa enviar nada a mais.
+
+---
+
+### 8.4 LTV Real — Modelo Treinado em Dados Reais
+
+**Como funciona:**
+
+1. Cron semanal executa no Worker
+2. Busca leads com `purchase = true/false` dos últimos 90 dias no D1
+3. Treina regressão logística com as features disponíveis (ltv_score, behavior_score, engagement_score, utm_source, state)
+4. Grava os pesos em `ltv_model_weights` com `is_active = 1`
+5. Cacheia os pesos em KV para acesso em ~0ms
+
+**Uso em runtime (cada `/track`):**
+- Worker verifica se há pesos ativos no KV
+- Se sim: usa o modelo treinado para prever LTV
+- Se não: fallback para heurística baseada em regras
+- Score 0-100 → classificação High/Medium/Low → valor estimado em BRL
+
+**Tabela `ltv_model_weights`:**
+
+| Campo | Descrição |
+|---|---|
+| `trained_at` | Timestamp do treinamento |
+| `is_active` | Apenas 1 registro ativo por vez |
+| `accuracy` | Acurácia do modelo no conjunto de teste (0-1) |
+| `weights_json` | Pesos serializados da regressão logística |
+
+---
+
+### 8.5 A/B LTV — Auto-Winner
+
+Quando um experimento A/B de prompt LTV tem uma variação com acurácia ≥5pp acima do controle:
+
+1. O Worker declara o vencedor automaticamente via `POST /api/ltv/ab-test/winner`
+2. O prompt vencedor é ativado para todos os novos eventos
+3. Um alerta WhatsApp é enviado informando qual variação ganhou e a diferença de acurácia
+
+Isso elimina a necessidade de revisão manual de experimentos.
+
+---
+
+### 8.6 Customer Match — Sync Semanal
+
+O cron semanal também exporta os perfis com `intention_level = 'high'` via `GET /export/customer-match`.
+
+- Formato CSV compatível com Google Customer Match
+- Emails e telefones hashados (SHA-256) conforme exigido pelo Google
+- Pode ser automatizado para upload direto via Google Ads API
+
+---
+
+### 8.7 Como Cada Tabela Alimenta o Desempenho
+
+| Tabela | Alimenta | Resultado |
+|---|---|---|
+| `match_quality_log` | Alerta de degradação de EMQ | Fix proativo antes do CPA subir |
+| `user_profiles` | Auto-Enrich no dispatch | Mais eventos com email → EMQ sobe |
+| `ltv_model_weights` | Score LTV real no /track | Bids mais inteligentes via bid_recommendations |
+| `ml_segments` + `bid_recommendations` | Bid por segmento × plataforma | ROAS por cluster |
+| `fraud_signals` | Tráfego limpo | Melhor atribuição Meta/Google |
+| `ltv_ab_assignments` | Experimentos de prompt | Prompt com maior acurácia vence automaticamente |
+
+---
+
+### 8.8 Endpoints para Consultar os Dados
+
+| Endpoint | O que retorna |
+|---|---|
+| `GET /api/fraud/stats` | Dashboard de fraude nas últimas 24h |
+| `GET /api/segmentation/list` | Segmentos ML ativos com métricas |
+| `GET /api/bidding/status` | Recomendações de bid por segmento × plataforma |
+| `GET /api/ltv/ab-test/results` | Acurácia por variação + vencedor recomendado |
+| `GET /export/customer-match` | Export de leads high-intent para Google Ads |
+
+---
+
+### 8.9 Sequência Completa de Migrations D1 (incluindo Fase 5)
+
+```bash
+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
+wrangler d1 execute cdp-edge-db --file=schema-bidding.sql --remote
+wrangler d1 execute cdp-edge-db --file=schema-ab-ltv.sql --remote
+wrangler d1 execute cdp-edge-db --file=schema-fraud.sql --remote
+wrangler d1 execute cdp-edge-db --file=schema-indexes.sql --remote   # Índices compostos de performance
+wrangler d1 execute cdp-edge-db --file=migrate-v7.sql --remote       # Fase 5: ltv_model_weights + match_quality_log
+```

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "cdp-edge",
-  "version": "2.0.3",
+  "version": "2.0.5",
   "description": "CDP Edge - Quantum Tracking - Sistema multi-agente para tracking digital Cloudflare Native (Workers + D1)",
   "main": "dist/index.js",
   "type": "module",
@@ -28,7 +28,12 @@
     "test:unit:hash": "node tests/unit/hashing.test.js",
     "test:unit:dedup": "node tests/unit/deduplication.test.js",
     "test:unit:payload": "node tests/unit/payload-validation.test.js",
-    "test:all": "npm run test:unit"
+    "test:all": "npm run test:unit",
+    "test:integration": "cd tests/integration && npx vitest run",
+    "agents:check": "node scripts/validate-agents.js",
+    "agents:sync": "node scripts/sync-agents.js",
+    "agents:sync:list": "node scripts/sync-agents.js --list",
+    "agents:sync:all": "node scripts/sync-agents.js --apply-all"
   },
   "keywords": [
     "pixel",

package/server-edge-tracker/INSTALAR.md

@@ -77,15 +77,39 @@ pelo ID que você copiou. Salve o arquivo.
 
 ## PASSO 5 — Criar as tabelas no banco
 
+Execute os arquivos de schema na ordem abaixo. Cada arquivo usa `IF NOT EXISTS` e é idempotente — pode ser executado mais de uma vez sem risco.
+
 ```bash
-wrangler d1 execute cdp-edge-db --file=schema.sql
+# Core: tabelas principais (leads, user_profiles, events_log, identity_graph)
+wrangler d1 execute cdp-edge-db --file=schema.sql --remote
+
+# Migrations históricas (retry_queue, escalation_log, intelligence_logs)
+wrangler d1 execute cdp-edge-db --file=migrate-v6.sql --remote
+
+# Fase 1 — ML Clustering (ml_segments, ml_segment_members, views de segmentação)
+wrangler d1 execute cdp-edge-db --file=schema-segmentation.sql --remote
+
+# Fase 2 — Bidding ML (bid_recommendations, view v_active_bid_recs)
+wrangler d1 execute cdp-edge-db --file=schema-bidding.sql --remote
+
+# Fase 3 — A/B LTV Testing (ltv_ab_tests, ltv_ab_variations, ltv_ab_assignments)
+wrangler d1 execute cdp-edge-db --file=schema-ab-ltv.sql --remote
+
+# Fase 4 — Fraud Detection (fraud_signals, fraud_alerts, view v_fraud_dashboard)
+wrangler d1 execute cdp-edge-db --file=schema-fraud.sql --remote
+
+# Índices compostos de performance para queries D1 (todas as fases)
+wrangler d1 execute cdp-edge-db --file=schema-indexes.sql --remote
+
+# Fase 5 — LTV Real + Match Quality (ltv_model_weights, match_quality_log, view v_match_quality_24h)
+wrangler d1 execute cdp-edge-db --file=migrate-v7.sql --remote
 ```
 
-> Resultado esperado: "✅ Successfully executed SQL"
+> Resultado esperado para cada arquivo: "✅ Successfully executed SQL"
 
 Verificar se as tabelas foram criadas:
 ```bash
-wrangler d1 execute cdp-edge-db --command="SELECT name FROM sqlite_master WHERE type='table';"
+wrangler d1 execute cdp-edge-db --remote --command="SELECT name FROM sqlite_master WHERE type='table' ORDER BY name;"
 ```
 
 ---

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

@@ -442,3 +442,72 @@ const segmentedCampaigns = [
 
 *API de Segmentação Dinâmica ML v1.0 — CDP Edge*
 *Data: 9 de Abril de 2026*
+
+---
+
+## Integração com LTV Real e Match Quality (Fase 5)
+
+### Como ml_segments alimenta o modelo LTV
+
+Os segmentos gerados pelo clustering não são apenas para campanhas — eles são features do modelo LTV treinado semanalmente.
+
+Quando o cron semanal treina a regressão logística em `ltv_model_weights`, ele inclui o `cluster_id` do lead como feature. Isso significa:
+
+- Leads do "Segmento Alto Valor + Alto Engajamento (SP)" têm peso positivo maior no modelo
+- O modelo aprende quais segmentos historicamente convertem mais
+- O LTV Score de cada novo `/track` já leva em conta o segmento do usuário
+
+**Fluxo de dados:**
+
+```
+ml_segment_members (cluster_id por lead)
+    │
+    └─ JOIN com leads × purchases
+            │
+            └─ Treino semanal da regressão logística
+                    │
+                    └─ ltv_model_weights (is_active=1)
+                            │
+                            └─ Score LTV em cada /track
+```
+
+### Como bid_recommendations se conecta ao LTV treinado
+
+O `ltv_model_weights` ativo gera scores mais precisos, que alimentam diretamente as recomendações de bid:
+
+1. LTV Score do segmento sobe (modelo mais preciso) → `avg_ltv` do segmento é recalculado
+2. Bidding Agent roda `POST /api/bidding/recommend` com o novo `avg_ltv`
+3. `bid_recommendations` é atualizado com bid recomendado para o segmento × plataforma
+4. Você aplica o bid sugerido em Meta/Google Ads
+
+**Consulta útil — bid atual por segmento:**
+
+```bash
+curl "https://seudominio.com/api/bidding/status"
+# Retorna: bid recomendado atual por segmento × plataforma
+```
+
+### Como Match Quality afeta a qualidade dos segmentos
+
+A tabela `match_quality_log` registra se cada evento que alimentou o D1 tinha email, fbp, etc. Eventos com `has_email = 0` têm Advanced Matching incompleto — a Meta pode não ter conseguido fazer o match com um usuário real.
+
+Isso significa que `ml_segments` pode conter leads "fantasmas" (usuários que a Meta não reconheceu). Para garantir a qualidade dos segmentos:
+
+1. Monitore `v_match_quality_24h` para manter `email_rate > 40%`
+2. Se a taxa cair, o Auto-Enrich (Identity Graph) recupera emails de sessões anteriores automaticamente
+3. Leads com email recuperado (`was_email_recovered = 1`) são indistinguíveis dos outros no clustering — têm o mesmo peso
+
+**Consulta de match quality:**
+
+```bash
+curl "https://seudominio.com/api/fraud/stats"
+# Inclui métricas de qualidade de sinal junto com dados de fraude
+```
+
+### Tabelas relacionadas (Fase 5)
+
+| Tabela | Relação com segmentação |
+|---|---|
+| `ltv_model_weights` | Usa `cluster_id` como feature; melhora scores LTV por segmento |
+| `match_quality_log` | Indica qualidade dos eventos que geraram os leads dos segmentos |
+| `user_profiles` | Auto-Enrich recupera dados antes do dispatch → mais leads com email → melhor clustering |