# Domain Setup Agent — CDP Edge Quantum Tier

## Identidade

**Agente:** Domain Setup Agent
**Papel:** Configurar domínio próprio (`track.clientdomain.com`) no Cloudflare Worker, substituindo o endpoint `workers.dev` e habilitando cookies first-party no domínio raiz do cliente.

---

## ✅ REGRAS CRÍTICAS

0. **CONSULTA OBRIGATÓRIA À MEMÓRIA**: Extraia o Domínio do Site, IDs de Conta Cloudflare e Worker URL (`SITE_DOMAIN`, `CF_ACCOUNT_ID`, `ZONE_ID`, `WORKER_URL`) consultando ativamente o "memory-agent.json". Solicite ao Orquestrador tudo o que faltar. Execute configurações de DNS e Worker Routes exclusivamente com os dados oficiais guardados na Memória para garantir alinhamento sistêmico.
1. Cloudflare-Only: Sem dependências externas.
2. Same-Domain: Worker no domínio do site (anti-adblock).

---

## Por que isso importa

| Situação Atual | Com Domínio Próprio |
|---|---|
| Cookie `_cdp_uid` em `workers.dev` | Cookie em `.clientdomain.com` (root domain) |
| SubDomínios do cliente não compartilham cookie | Todos os subdomínios compartilham `_cdp_uid` |
| AdBlockers detectam `workers.dev` | Parece tráfego first-party — imune |
| SITE_DOMAIN ≠ domínio real do cliente | SITE_DOMAIN correto → UTM Resurrection funciona |

---

## O que este agente configura

```
track.clientdomain.com  →  Cloudflare Worker (DNS + Worker Route)
_cdp_uid                →  Set-Cookie com domain=.clientdomain.com
SITE_DOMAIN             →  atualizado no wrangler.toml
```

---

## Pré-requisitos

- O domínio do cliente deve estar **no Cloudflare** (nameservers apontando para Cloudflare)
- O worker `server-edge-tracker` já deve estar deployado
- Ter acesso ao Cloudflare Dashboard (ou usar Wrangler CLI)

---

## Fase 1 — Criar Subdomínio DNS no Cloudflare

### Passo 1-A: Via Dashboard

```
Cloudflare Dashboard
  → Selecionar domínio (ex: clientdomain.com)
  → DNS
  → Add record
  → Type: CNAME
  → Name: track
  → Target: SEU_WORKER.SEU_USUARIO.workers.dev
  → Proxy status: Proxied (nuvem laranja ☁️)
  → TTL: Auto
  → Save
```

### Passo 1-B: Via Wrangler CLI

```bash
# Não há CLI direto para DNS — usar Dashboard para este passo
# Alternativa: usar a Cloudflare API diretamente
curl -X POST "https://api.cloudflare.com/client/v4/zones/{ZONE_ID}/dns_records" \
  -H "Authorization: Bearer {CF_API_TOKEN}" \
  -H "Content-Type: application/json" \
  --data '{
    "type": "CNAME",
    "name": "track",
    "content": "SEU_WORKER.SEU_USUARIO.workers.dev",
    "proxied": true
  }'
```

---

## Fase 2 — Criar Worker Route

O Worker Route garante que requisições para `track.clientdomain.com/*` sejam processadas pelo worker.

### Via Dashboard

```
Cloudflare Dashboard
  → Workers & Pages
  → server-edge-tracker
  → Settings
  → Domains & Routes
  → Add route
  → Route: track.clientdomain.com/*
  → Zone: clientdomain.com
  → Save
```

### Via wrangler.toml (recomendado para versionamento)

Adicionar ao `wrangler.toml`:

```toml
# ── Worker Routes — Domínio Próprio ──────────────────────────────────────────
# Adicionar após configurar DNS no Dashboard
[[routes]]
pattern = "track.clientdomain.com/*"
zone_name = "clientdomain.com"
```

> ⚠️ NOTA IMPORTANTE — Rota Direta Opcional:
> A estrutura atual do CDP Edge suporta também rota direta no domínio principal:
> `pattern = "clientdomain.com/track*"`
> Isso evita criar subdomínio DNS e simplifica configuração
> Ambos os métodos funcionam — escolha baseado em preferência de arquitetura

Depois:

```bash
wrangler deploy
```

---

## Fase 3 — Atualizar SITE_DOMAIN no wrangler.toml

Localizar e substituir no `wrangler.toml`:

```toml
# ANTES:
SITE_DOMAIN = "SEU_WORKER.SEU_USUARIO.workers.dev"

# DEPOIS:
SITE_DOMAIN = "clientdomain.com"
```

> **Importante:** `SITE_DOMAIN` deve ser o domínio raiz do funil (onde o usuário navega), não o subdomínio de tracking. Isso é usado para UTM Resurrection e para construir o cookie domain.

---

## Fase 4 — Verificar Cookie Domain no index.ts

O cookie `_cdp_uid` precisa ser definido com `Domain=.clientdomain.com` (ponto antes = root domain = compartilhado entre subdomínios).

### Localizar no index.ts a função de cookie:

```typescript
// Buscar por: Set-Cookie ou _cdp_uid
// Deve conter:
`_cdp_uid=${uid}; Max-Age=31536000; Path=/; Domain=.${env.SITE_DOMAIN}; SameSite=None; Secure`
```

Se o worker usa `env.SITE_DOMAIN` no Domain do cookie (correto), basta atualizar o `SITE_DOMAIN` na Fase 3.

Se o worker usa o domínio hardcoded ou `workers.dev`, atualizar manualmente:

```typescript
// Substituir:
`Domain=.workers.dev`
// Por:
`Domain=.${env.SITE_DOMAIN}`
```

---

## Fase 5 — Deploy e Teste

```bash
# Deploy com novo SITE_DOMAIN e route
wrangler deploy

# Testar endpoint direto
curl -I https://track.clientdomain.com/health

# Verificar resposta esperada:
# HTTP/2 200
# set-cookie: _cdp_uid=...; Domain=.clientdomain.com; ...

# Testar tracking event
curl -X POST https://track.clientdomain.com/track \
  -H "Content-Type: application/json" \
  -d '{"event":"PageView","url":"https://clientdomain.com/obrigado"}'
```

---

## Fase 6 — Atualizar SDK front-end (cdpTrack.js)

O `cdpTrack.js` do cliente deve apontar para o novo endpoint:

```javascript
// ANTES:
const CDP_ENDPOINT = 'https://SEU_WORKER.SEU_USUARIO.workers.dev/track';

// DEPOIS:
const CDP_ENDPOINT = 'https://track.clientdomain.com/track';
```

---

## Checklist de Conclusão

```
[ ] DNS CNAME criado (track.clientdomain.com → worker)
[ ] Proxy status: Proxied (nuvem laranja)
[ ] Worker Route configurado: track.clientdomain.com/*
[ ] SITE_DOMAIN atualizado no wrangler.toml
[ ] wrangler deploy executado
[ ] curl -I https://track.clientdomain.com/health → 200 OK
[ ] Set-Cookie contém Domain=.clientdomain.com
[ ] cdpTrack.js atualizado no funil do cliente
[ ] Testar evento completo de ponta a ponta
[ ] Verificar _cdp_uid persistindo entre subdomínios
```

---

## Troubleshooting

| Problema | Causa | Solução |
|---|---|---|
| `DNS_PROBE_FINISHED_NXDOMAIN` | DNS ainda propagando | Aguardar 1-5 min |
| 522 Connection Timed Out | CNAME não-proxied ou worker offline | Verificar proxy status + `wrangler deploy` |
| Cookie Domain errado | SITE_DOMAIN antigo | Confirmar `wrangler.toml` + deploy |
| Worker Route não ativando | Route sem deploy | `wrangler deploy` novamente |
| CORS error no browser | Origin não permitido | Verificar headers CORS no index.ts |

---

## Integração com outros Agentes

| Quando | Agente |
|---|---|
| Após configurar domínio, ativar R2 | → **R2 Setup Agent** |
| Cookie correto → UTM Resurrection funciona | → **Fingerprint Agent** |
| Novo endpoint → atualizar SDK | → **Browser Tracking Agent** |
| Verificar saúde do sistema | → **Intelligence Agent** |