cdp-edge 1.21.0 → 1.22.0

package/extracted-skill/tracking-events-generator/INTEGRACAO-COMPLETA.md

@@ -592,3 +592,92 @@ Para suporte, consulte:
 
 *CDP Edge Premium Tracking Intelligence - Integração Completa (Quantum Tier)*
 *Versão 1.0.0 - Atualizado em 2026-03-27*
+
+---
+
+## Pipeline de Melhoria Contínua Automática (Fase 5)
+
+A Fase 5 não adiciona novos eventos de tracking — ela fecha o ciclo de dados para que cada evento coletado melhore automaticamente a qualidade dos próximos.
+
+### Arquitetura do pipeline
+
+```
+Browser (cdpTrack.js)
+    │
+    └─ POST /track
+            │
+            ├─ [Auto-Enrich] Antes do dispatch Meta CAPI:
+            │       Worker consulta user_profiles por userId
+            │       → recupera email/fbp/fbc ausentes do perfil
+            │       → evento vai para Meta com Advanced Matching completo
+            │
+            ├─ [Dispatch Meta CAPI]
+            │       → Grava match_quality_log (has_email, has_fbp, etc.)
+            │
+            ├─ [LTV Prediction]
+            │       → Usa ltv_model_weights (se modelo treinado disponível)
+            │       → Fallback para heurística
+            │
+            └─ [D1 Writes]
+                    → leads, user_profiles, match_quality_log
+
+Cron semanal (Worker scheduled)
+    │
+    ├─ Treina regressão logística → ltv_model_weights (is_active=1)
+    │       → cached em KV para ~0ms no próximo /track
+    │
+    ├─ Analisa match_quality_log (janela 2h)
+    │       → email_rate < 40%   → alerta CallMeBot
+    │       → fbp_rate < 30%     → alerta CallMeBot
+    │       → composite < 45%    → alerta CallMeBot
+    │
+    ├─ Verifica experimentos A/B LTV
+    │       → variação bate controle por ≥5pp → auto-winner declarado
+    │       → alerta WhatsApp com prompt ativado
+    │
+    └─ Export Customer Match
+            → leads high_intent → GET /export/customer-match
+            → CSV para Google Ads (SHA-256 hashed)
+```
+
+### Novas tabelas D1 criadas na Fase 5
+
+| Tabela | Migration | Conteúdo |
+|---|---|---|
+| `ltv_model_weights` | `migrate-v7.sql` | Pesos do modelo treinado (trained_at, is_active, accuracy, weights_json) |
+| `match_quality_log` | `migrate-v7.sql` | Flags por evento: has_email, has_fbp, has_phone, has_fbc, was_email_recovered |
+
+**View:** `v_match_quality_24h` — agrega match quality das últimas 24h para consulta rápida.
+
+### Migration completa atualizada (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
+wrangler d1 execute cdp-edge-db --file=migrate-v7.sql --remote
+```
+
+### Endpoints novos para monitoramento
+
+| Endpoint | O que monitora |
+|---|---|
+| `GET /api/fraud/stats` | Fraude 24h + qualidade de sinal |
+| `GET /api/segmentation/list` | Clusters ML ativos com métricas de LTV |
+| `GET /api/bidding/status` | Bids recomendados por segmento × plataforma |
+| `GET /api/ltv/ab-test/results` | Acurácia por variação de prompt LTV |
+| `GET /export/customer-match` | Export CSV de leads high-intent para Google Ads |
+
+### Impacto esperado no funil
+
+| Componente | Mecanismo | Resultado |
+|---|---|---|
+| Advanced Matching Meta | Auto-Enrich recupera email/fbp de sessões anteriores | EMQ sobe → atribuição mais precisa |
+| LTV Score | Modelo treinado em dados reais do funil | Bids mais precisos → menor CPA |
+| Match Quality Alerts | Degradação detectada automaticamente | Fix em horas, não em dias |
+| A/B Auto-Winner | Melhor prompt LTV ativado automaticamente | LTV scores mais precisos sem revisão manual |
+| Customer Match | Leads high-intent exportados semanalmente | Audiência Google sempre atualizada |

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/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": "1.21.0",
+  "version": "1.22.0",
   "description": "CDP Edge - Quantum Tracking - Sistema multi-agente para tracking digital Cloudflare Native (Workers + D1)",
   "main": "dist/index.js",
   "type": "module",

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 |

package/server-edge-tracker/index.js

@@ -111,6 +111,17 @@ export default {
 
     const url = new URL(request.url);
 
+    // ── Rate Limiter — camada 0, antes do Fraud Gate ─────────────────────────
+    if (url.pathname === '/track' && request.method === 'POST' && env.RATE_LIMITER) {
+      const ip = request.headers.get('CF-Connecting-IP')
+              || request.headers.get('X-Forwarded-For')?.split(',')[0].trim()
+              || '0.0.0.0';
+      const { success } = await env.RATE_LIMITER.limit({ key: ip });
+      if (!success) {
+        return new Response(JSON.stringify({ status: 'ok', queued: true }), { status: 200, headers });
+      }
+    }
+
     // ── Fraud Gate — Fase 4 (apenas em /track) ────────────────────────────────
     // Roda ANTES de qualquer processamento de evento
     // Silent drop (200) — bots não sabem que foram detectados

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

@@ -46,13 +46,13 @@ CREATE INDEX IF NOT EXISTS idx_profiles_email_updated
 
 -- ── fraud_signals: dashboard e alertas ───────────────────────────────────────
 
--- handleFraudAlerts: filtra por ip + período
-CREATE INDEX IF NOT EXISTS idx_fraud_ip_created
-  ON fraud_signals(ip_address, created_at DESC);
+-- handleFraudAlerts: filtra por ip + período (coluna: detected_at)
+CREATE INDEX IF NOT EXISTS idx_fraud_ip_detected
+  ON fraud_signals(ip_address, detected_at DESC);
 
 -- handleFraudStats: fraud_score >= threshold ordenado por data
-CREATE INDEX IF NOT EXISTS idx_fraud_score_created
-  ON fraud_signals(fraud_score DESC, created_at DESC);
+CREATE INDEX IF NOT EXISTS idx_fraud_score_detected
+  ON fraud_signals(fraud_score DESC, detected_at DESC);
 
 -- ── ltv_ab_assignments: resultados de A/B test ───────────────────────────────
 
@@ -62,6 +62,6 @@ CREATE INDEX IF NOT EXISTS idx_ab_testid_class
 
 -- ── ml_segment_members: join com leads para bidding ─────────────────────────
 
--- handleBiddingRecommend: segment_id lookup
+-- handleBiddingRecommend: segment_id lookup (coluna: assigned_at)
 CREATE INDEX IF NOT EXISTS idx_seg_members_segid
-  ON ml_segment_members(segment_id, joined_at DESC);
+  ON ml_segment_members(cluster_id, assigned_at DESC);

package/server-edge-tracker/worker.js

@@ -3780,6 +3780,21 @@ export default {
 
     const url = new URL(request.url);
 
+    // ── Rate Limiter — camada 0, antes do Fraud Gate ─────────────────────────
+    // Bloqueia na borda por IP antes de qualquer CPU ser consumida
+    // Silent drop (200) — atacante não sabe que foi bloqueado
+    // Requer binding RATE_LIMITER no wrangler.toml (Workers Paid)
+    // Fail-open: se binding não existir, deixa passar (não quebra o fluxo)
+    if (url.pathname === '/track' && request.method === 'POST' && env.RATE_LIMITER) {
+      const ip = request.headers.get('CF-Connecting-IP')
+              || request.headers.get('X-Forwarded-For')?.split(',')[0].trim()
+              || '0.0.0.0';
+      const { success } = await env.RATE_LIMITER.limit({ key: ip });
+      if (!success) {
+        return new Response(JSON.stringify({ status: 'ok', queued: true }), { status: 200, headers });
+      }
+    }
+
     // ── Fraud Gate — Fase 4 (apenas em /track e /api) ────────────────────────
     // Roda ANTES de qualquer processamento de evento
     // Silent drop (200) — bots não sabem que foram detectados

package/server-edge-tracker/wrangler.toml

@@ -82,6 +82,19 @@ crons = ["0 2 * * 7", "0 3 1 * *"]
 [ai]
 binding = "AI"
 
+# ── Rate Limiting — proteção do /track contra abuso de cota ──────────────────
+# Bloqueia na borda ANTES de qualquer processamento do Worker
+# Limite: 60 requisições por minuto por IP (generoso para usuário real)
+# Requer Workers Paid plan ($5/mês) — remover bloco se usar plano free
+[[unsafe.bindings]]
+name         = "RATE_LIMITER"
+type         = "ratelimit"
+namespace_id = "1001"
+
+[unsafe.bindings.simple]
+limit  = 60
+period = 60
+
 # ── Secrets (NÃO ficam aqui — configurar via CLI) ─────────────────────────────
 # wrangler secret put META_ACCESS_TOKEN     ← token Meta CAPI (obrigatório)
 # wrangler secret put GA4_API_SECRET        ← secret GA4 Measurement Protocol (obrigatório)