cdp-edge 1.2.2 → 1.3.0

package/server-edge-tracker/INSTALAR.md

@@ -1,5 +1,5 @@
 # Setup Completo — server-edge-tracker
-## groof.com.br | Meta CAPI v22.0 + GA4 Measurement Protocol + D1 Database
+## SEU_DOMINIO | Meta CAPI v22.0 + GA4 Measurement Protocol + D1 Database
 
 > Execute cada bloco no terminal, um de cada vez.
 > Tempo total estimado: 15–20 minutos.
@@ -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;"
 ```
 
 ---
@@ -118,21 +142,30 @@ wrangler secret put META_TEST_CODE
 > Encontrar no Gerenciador de Eventos Meta → Testar Eventos → copie o código "TEST12345"
 > **Lembrar de remover esse secret em produção** (veja PASSO 10)
 
-### WhatsApp — Meta Cloud API v22.0 (notificações de venda/lead):
+### WhatsApp — Webhook Verification (CTWA Tracking):
+```bash
+wrangler secret put WA_WEBHOOK_VERIFY_TOKEN
+```
+> Token de verificação do webhook WhatsApp (obrigatório para CTWA). Meta exige este token para registrar o webhook.
+> Defina qualquer string segura, ex: `cdp-edge-webhook-2026-secret-xyz`.
+
+### WhatsApp — Meta Cloud API v22.0 (mensagens automáticas - OPCIONAL):
+> ⚠️  Estes secrets são **OPCIONAIS**. Se você precisa apenas de tracking de dados (ctwaclid), não configure-os.
+
 ```bash
-wrangler secret put WA_PHONE_ID
+wrangler secret put WHATSAPP_PHONE_NUMBER_ID
 ```
-> Phone Number ID do WhatsApp Business. Encontrar em: developers.facebook.com → App → WhatsApp → Configuração da API.
+> Meta: "Phone Number ID" — ID do número WhatsApp Business. Necessário apenas para enviar mensagens automáticas.
 
 ```bash
-wrangler secret put WA_ACCESS_TOKEN
+wrangler secret put WHATSAPP_ACCESS_TOKEN
 ```
-> Token de acesso permanente do WhatsApp Business (Meta Developers → Token de acesso).
+> Meta: "Access Token" — Token de acesso do WhatsApp Business. Necessário apenas para enviar mensagens automáticas.
 
 ```bash
 wrangler secret put WA_NOTIFY_NUMBER
 ```
-> Número que vai receber as notificações de venda/lead. Ex: `5511999998888` (com código do país, sem `+`).
+> Número que vai receber as notificações de venda/lead. Necessário apenas para enviar mensagens automáticas.
 
 ### WhatsApp — CallMeBot (alertas internos do sistema):
 ```bash
@@ -197,8 +230,8 @@ Ainda com `META_TEST_CODE` configurado, rode este comando no terminal
 ```bash
 curl -X POST https://server-edge-tracker.seu-usuario.workers.dev/track \
   -H "Content-Type: application/json" \
-  -H "Origin: https://groof.com.br" \
-  -d "{\"eventName\":\"Lead\",\"email\":\"teste@email.com\",\"pageUrl\":\"https://groof.com.br/teste\"}"
+  -H "Origin: https://SEU_DOMINIO" \
+  -d "{\"eventName\":\"Lead\",\"email\":\"teste@email.com\",\"pageUrl\":\"https://SEU_DOMINIO/teste\"}"
 ```
 
 Resultado esperado:
@@ -210,7 +243,97 @@ Verificar no Meta: Gerenciador de Eventos → Testar Eventos → deve aparecer "
 
 ---
 
-## PASSO 10 — Remover o Test Code antes de ir ao ar
+## PASSO 10 — Verificar Plano Workers ($5) e Dados Geográficos
+
+### IMPORTANTE: Plano Workers Paid ($5/mês)
+
+O CDP Edge foi desenvolvido para aproveitar todos os recursos do **Cloudflare Workers Paid ($5/mês)**, especialmente os dados geográficos avançados.
+
+**O que você ganha com o plano $5:**
+- **Cidade exata:** Ex: "São Paulo" (plano free: NULL)
+- **Estado completo:** Ex: "São Paulo" (plano free: NULL)  
+- **Estado (sigla):** Ex: "SP" (plano free: NULL)
+- **CEP:** Ex: "01310-100" (plano free: NULL)
+- **Latitude/Longitude:** Ex: "-23.5505", "-46.6333" (plano free: NULL)
+- **Timezone:** Ex: "America/Sao_Paulo" (plano free: NULL)
+
+**Como verificar se está funcionando:**
+
+1. **Enviar evento de teste:**
+```bash
+curl -X POST "https://SEU_DOMINIO/track" \
+  -H "Content-Type: application/json" \
+  -H "Origin: https://SEU_DOMINIO" \
+  -H "User-Agent: Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36" \
+  -d '{"eventName":"TestGeo","pageUrl":"https://SEU_DOMINIO/teste","email":"teste@exemplo.com","firstName":"Teste","lastName":"Geo"}'
+```
+
+2. **Verificar no banco D1 se os dados geográficos foram capturados:**
+```bash
+wrangler d1 execute cdp-edge-db --remote --command="SELECT event_name, email, city, state, country FROM leads WHERE email = 'teste@exemplo.com' ORDER BY created_at DESC LIMIT 1"
+```
+
+**Resultado esperado (com plano $5):**
+```json
+{
+  "event_name": "TestGeo",
+  "email": "teste@exemplo.com",
+  "city": "São Bernardo do Campo",    // ← Plano $5: nome da cidade
+  "state": "SP",                       // ← Plano $5: sigla do estado
+  "country": "BR"                      // ← Plano free: país
+}
+```
+
+**Se `city` e `state` aparecem como `NULL`:**
+- O plano $5 não está ativo
+- Verifique no painel Cloudflare se Workers está contratado
+- Contrate o plano em: https://dash.cloudflare.com/[ID_DA_CONTA]/workers/plans
+
+---
+
+## PASSO 11.1 — Solução de Conflitos de Rotas
+
+### ⚠️ Se aparecer erro no deploy:
+
+```
+ERROR: Can't deploy routes that are assigned to another worker.
+"server-edge-tracker" is already assigned to routes:
+  - SEU_DOMINIO/track*
+```
+
+### SOLUÇÃO 1 — Via Painel Cloudflare (RECOMENDADO):
+
+1. Acesse: https://dash.cloudflare.com/[ID_DA_CONTA]/workers/overview
+2. Clique no worker que está usando as rotas do seu domínio
+3. Vá em Settings → Triggers → Routes
+4. Clique "Delete" nas rotas do domínio `SEU_DOMINIO`
+5. Repita o `wrangler deploy`
+
+### SOLUÇÃO 2 — Via Wrangler CLI:
+
+```bash
+# Listar workers para encontrar o deployment conflitante
+wrangler deployments list
+
+# Remover deployment conflitante (substituir pelo ID correto)
+wrangler deployment delete --id <ID_DO_DEPLOYMENT_CONFLITANTE>
+```
+
+### SOLUÇÃO 3 — Usar Sufixo nas Rotas:
+
+Se não quiser remover rotas existentes, use sufixo:
+
+```toml
+[[routes]]
+pattern = "SEU_DOMINIO/track-worker-novo*"
+zone_name = "SEU_DOMINIO"
+```
+
+**URL do tracking:** `https://SEU_DOMINIO/track-worker-novo`
+
+---
+
+## PASSO 11.2 — Remover o Test Code antes de ir ao ar
 
 ```bash
 wrangler secret delete META_TEST_CODE
@@ -219,18 +342,94 @@ wrangler deploy
 
 ---
 
-## PASSO 11 — Configurar domínio personalizado (opcional)
+## PASSO 12 — Configurar domínio personalizado (OBRIGATÓRIO para produção)
+
+### ⚠️ ATENÇÃO: Domínio OBRIGATÓRIO
+
+Para o tracking funcionar corretamente em produção, você **PRECISA** configurar um domínio personalizado. **NÃO** use o domínio `.workers.dev` em produção.
+
+### INSTRUÇÕES EXATAS:
+
+#### 1. Verificar se o domínio está na Cloudflare
+```bash
+# No painel Cloudflare: https://dash.cloudflare.com
+# Verifique se o domínio está listado em "Websites"
+# Se não estiver, adicione o domínio antes de continuar
+```
+
+#### 2. Configurar rotas no wrangler.toml
+
+Edite o arquivo `wrangler.toml` e substitua:
+```toml
+# SUBSTITUIR estes valores:
+pattern  = "SEU_DOMINIO/track*"      # ← Substituir pelo domínio real
+zone_name = "SEU_DOMINIO"            # ← Substituir pelo domínio real
+
+# Exemplo real:
+# pattern  = "cliente.com.br/track*"
+# zone_name = "cliente.com.br"
+```
+
+#### 3. Fazer o deploy com as rotas
+```bash
+wrangler deploy
+```
 
-Se quiser usar `track.groof.com.br` em vez do domínio `.workers.dev`:
+#### 4. Resolver conflitos de rotas (se ocorrer erro)
 
-1. No painel da Cloudflare → Workers & Pages → seu Worker → Settings → Domains & Routes
-2. Clique "Add Custom Domain"
-3. Digite: `track.groof.com.br`
-4. Cloudflare configura o DNS automaticamente (como o domínio já está na Cloudflare)
+Se aparecer erro: `Can't deploy routes that are assigned to another worker`:
+
+**SOLUÇÃO A - Via painel Cloudflare:**
+1. Acesse: https://dash.cloudflare.com/[ID_DA_CONTA]/workers/overview
+2. Clique no worker que está usando as rotas do seu domínio
+3. Vá em Settings → Triggers → Routes
+4. Clique "Delete" nas rotas do domínio
+5. Repita o `wrangler deploy`
+
+**SOLUÇÃO B - Via API (rápido):**
+```bash
+# Listar workers para encontrar o ID
+wrangler deployments list
+
+# Remover rotas do worker conflitante (substituir pelo ID correto)
+wrangler deployment delete --id <ID_DO_DEPLOYMENT>
+```
+
+#### 5. Verificar se funcionou
+```bash
+# Testar endpoint de health
+curl "https://SEU_DOMINIO/track/health"
+
+# Deve retornar:
+# {"status": "ok", "bindings": {...}}
+```
+
+#### 6. Testar endpoint de tracking
+```bash
+curl -X POST "https://SEU_DOMINIO/track" \
+  -H "Content-Type: application/json" \
+  -H "Origin: https://SEU_DOMINIO" \
+  -d '{"eventName":"Test","pageUrl":"https://SEU_DOMINIO/teste"}'
+```
+
+**URL FINAL DO TRACKING:**
+- ✅ `https://SEU_DOMINIO/track` (CORRETO - produção)
+- ❌ `https://seu-worker.workers.dev/track` (ERRADO - teste apenas)
+
+---
+
+### DOMÍNIOS SUPOSTOS (.workers.dev) — Apenas para testes locais:
+
+```bash
+# Para testar localmente sem domínio real:
+wrangler dev
+
+# Acesso temporário: http://localhost:8787/track
+```
 
 ---
 
-## PASSO 12 — Configurar webhooks nas plataformas
+## PASSO 13 — Configurar webhooks nas plataformas
 
 ### Ticto (plataforma principal):
 
@@ -243,8 +442,8 @@ Preencher:
 - **Formato:** `JSON`
 - **Evento:** marcar **Venda Realizada** (status `paid`)
 
-> Se usar domínio personalizado (ex: `track.groof.com.br`):
-> URL fica: `https://track.groof.com.br/webhook/ticto`
+> Se usar domínio personalizado (ex: `track.SEU_DOMINIO`):
+> URL fica: `https://track.SEU_DOMINIO/webhook/ticto`
 
 **Testar:** na tela de webhook da Ticto há um botão **"Enviar teste"**. Ao clicar, a Ticto envia um POST simulado. Confirme que o evento aparece no Gerenciador de Eventos do Meta como `Purchase` e que o dado foi registrado no banco D1 (ver comando no final deste guia).
 
@@ -296,7 +495,7 @@ Preencher:
   "userId": "usr_abc123",
   "gaClientId": "GA1.1.123456789.1234567890",
   "eventId": "CDP_1234567890_abc123",
-  "pageUrl": "https://groof.com.br/obrigado",
+  "pageUrl": "https://SEU_DOMINIO/obrigado",
   "value": 297,
   "currency": "BRL",
   "utmSource": "facebook",