cdp-edge 1.0.0

package/server-edge-tracker/INSTALAR.md

@@ -0,0 +1,527 @@
+# Setup Completo — server-edge-tracker
+## 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.
+
+---
+
+## PRÉ-REQUISITOS
+- Node.js instalado → `node -v` deve retornar v18 ou superior
+- Conta Cloudflare ativa em cloudflare.com
+- Pixel ID e Access Token Meta já em mãos ✅
+- GA4 Measurement ID já em mãos ✅
+
+---
+
+## PASSO 1 — Instalar Wrangler (ferramenta da Cloudflare)
+
+```bash
+npm install -g wrangler
+```
+
+Verificar se instalou:
+```bash
+wrangler --version
+```
+
+---
+
+## PASSO 2 — Login na Cloudflare
+
+```bash
+wrangler login
+```
+
+> Vai abrir o navegador. Faça login com sua conta Cloudflare e clique em "Autorizar".
+> Resultado esperado: "Successfully logged in."
+
+---
+
+## PASSO 3 — Entrar na pasta do projeto
+
+**Windows (PowerShell):**
+```powershell
+cd "C:\Users\comer\COWORK CLAUDE\CDP Edge\server-edge-tracker"
+```
+
+**Mac / Linux:**
+```bash
+cd ~/Desktop/server-edge-tracker
+# ou o caminho onde você salvou a pasta
+```
+
+> **Claude Code (Linux):** Ao rodar via Claude Code, use o caminho absoluto Linux do projeto clonado, ex: `/home/user/projeto/server-edge-tracker`
+
+---
+
+## PASSO 4 — Criar o banco de dados D1
+
+```bash
+wrangler d1 create cdp-edge-db
+```
+
+> Resultado esperado — copie o `database_id` retornado:
+> ```
+> ✅ Successfully created DB 'cdp-edge-db'
+> database_id = "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
+> ```
+
+Abra o arquivo `wrangler.toml` e substitua a linha:
+```
+database_id  = "SUBSTITUIR_PELO_ID_DO_D1"
+```
+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
+# 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 para cada arquivo: "✅ Successfully executed SQL"
+
+Verificar se as tabelas foram criadas:
+```bash
+wrangler d1 execute cdp-edge-db --remote --command="SELECT name FROM sqlite_master WHERE type='table' ORDER BY name;"
+```
+
+---
+
+## PASSO 6 — Configurar os Secrets (tokens privados)
+
+Os tokens NUNCA ficam no código. São configurados aqui e ficam criptografados na Cloudflare.
+
+### Meta Access Token:
+```bash
+wrangler secret put META_ACCESS_TOKEN
+```
+> Cole o token quando pedir: `EAAO3ZAGKmRi8B...` (o token completo)
+> Pressione Enter
+
+### GA4 API Secret:
+```bash
+wrangler secret put GA4_API_SECRET
+```
+> Para obter esse secret:
+> 1. Abra o GA4 → Administrar → Fluxos de dados → clique no seu site
+> 2. Role até "Secrets da API do Measurement Protocol"
+> 3. Clique em "Criar" → dê um nome qualquer → copie o valor gerado
+> Cole aqui e pressione Enter.
+
+### Test Event Code Meta (só para testes — apagar depois):
+```bash
+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 — 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 WHATSAPP_PHONE_NUMBER_ID
+```
+> Meta: "Phone Number ID" — ID do número WhatsApp Business. Necessário apenas para enviar mensagens automáticas.
+
+```bash
+wrangler secret put WHATSAPP_ACCESS_TOKEN
+```
+> 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. Necessário apenas para enviar mensagens automáticas.
+
+### WhatsApp — CallMeBot (alertas internos do sistema):
+```bash
+wrangler secret put CALLMEBOT_PHONE
+```
+> Seu número de WhatsApp pessoal. Ex: `5511999998888`. Ativar em: `wa.me/34638398527` com a mensagem `I allow callmebot to send me messages`.
+
+```bash
+wrangler secret put CALLMEBOT_APIKEY
+```
+> API Key gerada pelo CallMeBot após ativação (você recebe via WhatsApp após enviar a mensagem de ativação).
+
+> **Nota:** CallMeBot é usado exclusivamente para alertas críticos do sistema (Worker com erro, API falhando, token expirado). Notificações de venda/lead usam a Meta Cloud API v22.0.
+
+---
+
+## PASSO 7 — Fazer o deploy (publicar o Worker)
+
+```bash
+wrangler deploy
+```
+
+> Resultado esperado:
+> ```
+> ✅ Deployed server-edge-tracker
+> https://server-edge-tracker.seu-usuario.workers.dev
+> ```
+> **Copie essa URL** — é o endereço do seu servidor.
+
+---
+
+## PASSO 8 — Testar se está funcionando
+
+Substitua a URL abaixo pela sua e abra no navegador:
+
+```
+https://server-edge-tracker.seu-usuario.workers.dev/health
+```
+
+Resultado esperado:
+```json
+{
+  "status": "ok",
+  "pixel": "1234567890123456",
+  "ga4": "G-XXXXXXXXXX",
+  "db": "connected",
+  "meta_token": "set",
+  "ga4_secret": "set"
+}
+```
+
+Se `db: "not bound"` → o `database_id` no wrangler.toml está errado. Corrija e rode `wrangler deploy` de novo.
+Se `meta_token: "MISSING"` → o secret não foi configurado. Rode o PASSO 6 de novo.
+
+---
+
+## PASSO 9 — Testar evento real no Meta
+
+Ainda com `META_TEST_CODE` configurado, rode este comando no terminal
+(substitua pela sua URL):
+
+```bash
+curl -X POST https://server-edge-tracker.seu-usuario.workers.dev/track \
+  -H "Content-Type: application/json" \
+  -H "Origin: https://SEU_DOMINIO" \
+  -d "{\"eventName\":\"Lead\",\"email\":\"teste@email.com\",\"pageUrl\":\"https://SEU_DOMINIO/teste\"}"
+```
+
+Resultado esperado:
+```json
+{"ok": true, "meta": {"events_received": 1}, "ga4": {"ok": true}}
+```
+
+Verificar no Meta: Gerenciador de Eventos → Testar Eventos → deve aparecer "Lead" recebido.
+
+---
+
+## 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
+wrangler deploy
+```
+
+---
+
+## 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  = "lancamentosabc.com.br/track*"
+# zone_name = "lancamentosabc.com.br"
+```
+
+#### 3. Fazer o deploy com as rotas
+```bash
+wrangler deploy
+```
+
+#### 4. Resolver conflitos de rotas (se ocorrer erro)
+
+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 13 — Configurar webhooks nas plataformas
+
+### Ticto (plataforma principal):
+
+**Caminho no painel:**
+`Meus Produtos → [selecione o produto] → aba Webhooks → + Adicionar Webhook`
+
+Preencher:
+- **URL:** `https://server-edge-tracker.seu-usuario.workers.dev/webhook/ticto`
+- **Versão:** `2.0` ← obrigatório (v1.0 tem estrutura diferente)
+- **Formato:** `JSON`
+- **Evento:** marcar **Venda Realizada** (status `paid`)
+
+> 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).
+
+**O que o worker faz ao receber o webhook Ticto:**
+1. Verifica se o status é `paid`, `approved` ou `complete` — ignora outros (reembolso, chargeback)
+2. Recupera `fbp`, `fbc`, `gclid` do comprador no banco D1 pelo e-mail
+3. Converte `paid_amount` de centavos para reais (ex: `29700 → 297.00`)
+4. Dispara simultaneamente: Meta CAPI Purchase + GA4 Purchase + TikTok CompletePayment + D1 Insert
+
+---
+
+### Hotmart:
+- Hotmart Club → Configurações → Webhooks
+- URL: `https://server-edge-tracker.seu-usuario.workers.dev/webhook/hotmart`
+- Eventos: PURCHASE_APPROVED, PURCHASE_COMPLETE
+
+### Kiwify:
+- Kiwify → Configurações → Webhooks
+- URL: `https://server-edge-tracker.seu-usuario.workers.dev/webhook/kiwify`
+
+---
+
+## ENDPOINTS DISPONÍVEIS
+
+| Método | Rota | Uso |
+|---|---|---|
+| `POST` | `/track` | Evento do browser (Lead, Purchase, PageView…) |
+| `POST` | `/webhook/ticto` | Webhook de compra Ticto (v2 JSON) |
+| `POST` | `/webhook/hotmart` | Webhook de compra Hotmart |
+| `POST` | `/webhook/kiwify` | Webhook de compra Kiwify |
+| `GET` | `/health` | Status do servidor |
+
+---
+
+## ESTRUTURA DO PAYLOAD — POST /track
+
+```json
+{
+  "eventName": "Lead",
+  "email": "joao@email.com",
+  "phone": "11999998888",
+  "firstName": "João",
+  "lastName": "Silva",
+  "city": "São Paulo",
+  "state": "SP",
+  "country": "BR",
+  "fbp": "_fbp cookie value",
+  "fbc": "_fbc cookie value",
+  "userId": "usr_abc123",
+  "gaClientId": "GA1.1.123456789.1234567890",
+  "eventId": "CDP_1234567890_abc123",
+  "pageUrl": "https://SEU_DOMINIO/obrigado",
+  "value": 297,
+  "currency": "BRL",
+  "utmSource": "facebook",
+  "utmMedium": "cpc",
+  "utmCampaign": "campanha-01"
+}
+```
+
+Todos os campos são opcionais exceto `eventName`.
+
+---
+
+## ATUALIZAR O WORKER (após editar worker.js)
+
+```bash
+wrangler deploy
+```
+
+Simples assim — sem restart, sem downtime.
+
+---
+
+## MONITORAR LOGS EM TEMPO REAL
+
+```bash
+wrangler tail
+```
+
+Mostra cada requisição e possíveis erros em tempo real.