# Setup Completo — server-edge-tracker
## SEU_DOMINIO | Meta CAPI v25.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 v25.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 v25.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  = "cliente.com.br/track*"
# zone_name = "cliente.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.