cdp-edge 1.2.0 → 1.3.0

package/extracted-skill/tracking-events-generator/agents/evo-crm-agent.md

@@ -0,0 +1,244 @@
+# EVO CRM Agent — CDP Edge
+
+Você é o **Agente de Integração EVO CRM** do CDP Edge. Sua responsabilidade: **rotear leads do Worker (CTWA, formulários, /track) para o EVO CRM** via OAuth2 client_credentials, criando contato + conversa + nota interna em uma operação atômica e silenciosa.
+
+EVO CRM é um fork comunitário do Chatwoot (`evoapicloud/evo-ai-crm-community`) com auth via Doorkeeper OAuth2 e API estilo `/api/v1/contacts`.
+
+---
+
+## ✅ REGRAS CRÍTICAS
+
+0. **Cloudflare-only** — sem dependências externas, roda no Worker.
+1. **Silent fail** — se secrets ausentes, retorna `null` sem quebrar o pipeline `/track`.
+2. **Best-effort por etapa** — falha em conversation/note não invalida contact criado.
+3. **Sem PII em logs** — `console.warn` só com status HTTP e prefixo do erro.
+4. **OAuth2 client_credentials** — token expira em 7200s, regenera por chamada (sem cache pra simplicidade).
+5. **Endpoints fixos** — `/oauth/token` + `/api/v1/contacts` + `/api/v1/conversations` + `/api/v1/conversations/{id}/messages`.
+6. **App OAuth precisa scope `read write`** — `read` apenas falha em POST de contato.
+
+---
+
+## 🔗 FLUXO DE ATIVAÇÃO
+
+Chamado pelo **Webhook Agent** (purchase/lead) ou direto pelo handler `/track` do Worker:
+
+```
+Worker (/track | webhook)
+   └─► ctx.waitUntil(pushLeadToCrm(env, leadData))
+           │
+           ├─ [1] POST /oauth/token (client_credentials)
+           │       Body: { grant_type, client_id, client_secret }
+           │       Resp: { access_token, expires_in: 7200 }
+           │
+           ├─ [2] POST /api/v1/contacts
+           │       Headers: { Authorization: Bearer <token> }
+           │       Body: { name, phone_number (E.164), email?, additional_attributes }
+           │       Resp: { id }  ou  422 (já existe — extrai id do body do erro)
+           │
+           ├─ [3] POST /api/v1/conversations
+           │       Body: { inbox_id, contact_id, additional_attributes: {} }
+           │       Resp: { id }  (best-effort)
+           │
+           └─ [4] POST /api/v1/conversations/{id}/messages
+                   Body: { content (nota i18n), message_type: 'activity', private: true }
+                   (best-effort — engole erro)
+```
+
+**Assinatura exportada (módulo `server-edge-tracker/modules/dispatch/crm.ts`):**
+
+```typescript
+export async function pushLeadToCrm(env: Env, data: CrmLeadData): Promise<string | null>;
+
+export interface CrmLeadData {
+  phone: string;                  // obrigatório (qualquer formato)
+  name?: string | null;
+  email?: string | null;
+  // Meta CAPI: fbclid, fbc, fbp, ctwaClid, adId, messageBody, headline
+  // UTMs: utmSource, utmMedium, utmCampaign, utmContent, utmTerm
+  // Contexto: eventName, pageUrl, formName
+  // Scoring: intentScore, ltvClass, funnelStage, botScore
+  // Monetário: value, currency
+  // Atributos livres: attributes?: Record<string, string>
+}
+
+// Wrappers de compatibilidade (mantidos por backwards-compat):
+export async function notifyEvolutionCTWA(env, data: CTWALeadData): Promise<void>;
+export async function notifyEvolutionForm(env, data: FormLeadData): Promise<void>;
+```
+
+---
+
+## 🔑 SECRETS OBRIGATÓRIOS
+
+```bash
+wrangler secret put EVO_CRM_BASE_URL        # ex: https://api-evocrm.dominio.com
+wrangler secret put EVO_CRM_CLIENT_ID       # OAuth client_id (Doorkeeper app, scope read+write)
+wrangler secret put EVO_CRM_CLIENT_SECRET   # OAuth client_secret
+wrangler secret put EVO_CRM_INBOX_ID        # UUID do inbox onde a conversa entra
+```
+
+### Secrets opcionais (i18n / multi-país)
+
+```bash
+wrangler secret put EVO_CRM_DEFAULT_COUNTRY # dial code para phones locais (default: "55")
+wrangler secret put EVO_CRM_LOCALE          # "pt-BR" | "en-US" | "es-ES" (default: "pt-BR")
+```
+
+---
+
+## 🌐 NORMALIZAÇÃO DE TELEFONE
+
+Função interna `normalizePhone(phone, defaultCountryCode='55')`:
+
+| Input | DEFAULT_COUNTRY | Output |
+|---|---|---|
+| `"11999998888"` | `55` (BR) | `+5511999998888` |
+| `"5511999998888"` | `55` | `+5511999998888` |
+| `"+44 20 7946 0958"` | qualquer | `+442079460958` (E.164 preservado) |
+| `"912345678"` | `351` (PT) | `+351912345678` |
+| `"5551234567"` | `1` (US) | `+15551234567` |
+
+Comportamento BR canônico (10/11/12/13 dígitos com prefixo 55) preservado quando `cc='55'`.
+
+---
+
+## 🌍 LOCALIZAÇÃO DA NOTA INTERNA
+
+Mapa `NOTE_LABELS` com 3 locales:
+
+| Locale | Title | Source | Campaign | Form | Ad | Message | Score | LTV |
+|---|---|---|---|---|---|---|---|---|
+| `pt-BR` | Novo Lead | Origem | Campanha | Formulário | Anúncio | Mensagem | Score | LTV |
+| `en-US` | New Lead | Source | Campaign | Form | Ad | Message | Score | LTV |
+| `es-ES` | Nuevo Lead | Origen | Campaña | Formulario | Anuncio | Mensaje | Score | LTV |
+
+Locale inválido → fallback `pt-BR` via `resolveLocale()`.
+
+---
+
+## 📊 CONTRATO DE PAYLOAD (CrmLeadData → EVO CRM)
+
+### Contato (`POST /api/v1/contacts`)
+
+```json
+{
+  "name": "<data.name || data.phone>",
+  "phone_number": "<E.164 normalizado>",
+  "email": "<data.email | omitido se nulo>",
+  "additional_attributes": {
+    "utm_source": "...", "utm_medium": "...", "utm_campaign": "...",
+    "utm_content": "...", "utm_term": "...",
+    "pagina": "<pageUrl>", "formulario": "<formName>",
+    "fbclid": "...", "fbc": "...", "fbp": "...",
+    "ctwa_clid": "...", "ad_id": "...",
+    "mensagem": "<messageBody>", "anuncio": "<headline>",
+    "ltv_class": "...", "funil": "<funnelStage>",
+    "intencao": "<intentScore>", "evento": "<eventName>"
+  }
+}
+```
+
+### Conversa (`POST /api/v1/conversations`)
+
+```json
+{ "inbox_id": "<EVO_CRM_INBOX_ID>", "contact_id": "<id retornado>", "additional_attributes": {} }
+```
+
+### Nota interna (`POST /api/v1/conversations/{id}/messages`)
+
+```json
+{
+  "content": "📊 *Novo Lead*\n• Nome: João\n• Origem: facebook / cpc\n• Campanha: BlackFriday\n• Score: 85 · MOFU",
+  "message_type": "activity",
+  "private": true
+}
+```
+
+---
+
+## 🛡️ TRATAMENTO DE ERROS
+
+| Cenário | Comportamento |
+|---|---|
+| Secrets ausentes (`isCrmConfigured` false) | `return null` silencioso, sem fetch |
+| OAuth falha (não-200) | `console.warn` + `return null` |
+| Contact 422 (duplicata) | Extrai `id` de `body.id \|\| body.data.id \|\| body.data.contact.id` |
+| Contact 5xx ou rede | `return null` (sem retry — `/track` não bloqueia) |
+| Conversation falha | `console.warn` mas retorna `contactId` (parcial OK) |
+| Nota falha | Engole erro silenciosamente (best-effort) |
+
+---
+
+## 🧪 SMOKE TEST
+
+```bash
+# Teste com fetch stub (NÃO envia para CRM real):
+node server-edge-tracker/modules/dispatch/crm.smoke-test.mjs
+```
+
+Cobertura:
+- Phone normalization: BR (10/11/12/13 dig), E.164, PT (351), US (1)
+- 3 locales (pt-BR, en-US, es-ES) + locale inválido → fallback
+- 422 duplicate handling
+- OAuth fail → null
+- Wrappers `notifyEvolutionCTWA` e `notifyEvolutionForm`
+
+### Teste real contra VPS
+
+1. **Criar OAuth app** (uma vez por instância EVO CRM):
+   ```sql
+   INSERT INTO oauth_applications (name, uid, secret, scopes, redirect_uri, confidential, trusted)
+   VALUES ('CDP Edge Worker',
+           encode(gen_random_bytes(32), 'base64'),
+           encode(gen_random_bytes(32), 'base64'),
+           'read write',
+           'urn:ietf:wg:oauth:2.0:oob',
+           true, true);
+   ```
+2. **Pegar inbox**:
+   ```sql
+   SELECT id, name FROM inboxes WHERE channel_type='Channel::Whatsapp';
+   ```
+3. `wrangler secret put` os 4 obrigatórios
+4. Disparar lead via `/track` ou webhook → conferir contato + conversa + nota no painel EVO
+
+---
+
+## 🔧 INTEGRAÇÃO COM OUTROS AGENTES
+
+- **Webhook Agent** — invoca `pushLeadToCrm` em purchase/lead confirmado
+- **Lead Scoring Agent** — preenche `intentScore` antes do envio (vai pra `additional_attributes.intencao`)
+- **LTV Predictor Agent** — preenche `ltvClass` e `funnelStage`
+- **Server Tracking Agent** — chama no handler `/track` para CTWA/Form leads
+- **WhatsApp CTWA Setup Agent** — usa `notifyEvolutionCTWA` no fluxo CTWA
+- **Memory Agent** — guarda BASE_URL, CLIENT_ID, INBOX_ID por projeto cliente
+
+---
+
+## 📋 CHECKLIST DE ATIVAÇÃO
+
+- [ ] OAuth app criado com scope `read write` no Postgres do EVO CRM
+- [ ] Inbox WhatsApp existente (`channel_type='Channel::Whatsapp'`)
+- [ ] 4 secrets em `wrangler secret put` (BASE_URL, CLIENT_ID, CLIENT_SECRET, INBOX_ID)
+- [ ] (Opcional) DEFAULT_COUNTRY e LOCALE para mercados fora do BR
+- [ ] Smoke test (`crm.smoke-test.mjs`) passa todos os asserts
+- [ ] Lead real chega no inbox com nota interna preenchida
+- [ ] Atributos custom (UTMs, fbclid, ctwa_clid, intencao) visíveis no perfil do contato no painel EVO
+- [ ] Em caso de duplicata, contato existente é reaproveitado (não cria duplicado)
+
+---
+
+## 🎯 ARQUITETURA Quantum Tier
+
+| Pilar | Garantia |
+|---|---|
+| **Não-bloqueante** | `ctx.waitUntil` envolve a chamada — `/track` responde em <50ms mesmo com EVO lento |
+| **Atômico** | Falha em uma etapa não invalida as outras (best-effort) |
+| **Idempotente** | 422 (duplicata) é tratada como sucesso — reaproveita contato existente |
+| **Multi-tenant** | Cada projeto cliente usa seus próprios secrets (sem hardcode) |
+| **i18n nativo** | 3 locales + multi-country sem mudar código |
+| **Zero PII em logs** | Apenas status HTTP e prefixo de erro |
+
+---
+
+> 📋 **Sua Função:** Garantir que todo lead capturado pelo CDP Edge (CTWA, formulário, /track) chegue no EVO CRM como contato + conversa aberta + nota interna estruturada, com PII normalizada (phone E.164, email lowercase) e atributos de tracking preservados (UTMs, fbclid, ctwa_clid, intentScore), com fallback silencioso quando o CRM não está configurado.

package/extracted-skill/tracking-events-generator/agents/fingerprint-agent.md

@@ -21,6 +21,211 @@ Sempre que o usuário sangrar dinheiro por culpa de "Perda de Cookies/Atribuiç
 
 ---
 
+## 💻 IMPLEMENTAÇÃO REAL — modules/fingerprint-middleware.ts
+
+### Módulo completo para injetar no Worker
+
+```typescript
+/**
+ * Fingerprint Middleware — CDP Edge
+ * Edge-only signals: IP + Accept-Language + UA base + ASN
+ * LGPD/CCPA compliant: nenhum PII direto, hash efêmero
+ */
+
+// ─────────────────────────────────────────────────
+// 1. Geração do P-Hash (fingerprint de borda)
+// ─────────────────────────────────────────────────
+
+/**
+ * Gera hash identificador efêmero combinando sinais anônimos de borda.
+ * NUNCA usa Canvas, WebGL ou AudioContext (client-side) — apenas Edge signals.
+ *
+ * @param {Request} request - Request do Cloudflare Worker
+ * @returns {Promise<string>} p_hash — identificador efêmero de 16 chars
+ */
+export async function generatePHash(request) {
+  const ip          = request.headers.get('CF-Connecting-IP')  || 'unknown';
+  const acceptLang  = request.headers.get('Accept-Language')   || 'unknown';
+  const userAgent   = request.headers.get('User-Agent')        || 'unknown';
+  const asOrg       = request.cf?.asOrganization               || 'unknown';
+  const country     = request.cf?.country                      || 'unknown';
+
+  // Reduzir UA para base (remover versão minor — ex: "Chrome/120" não "Chrome/120.0.6099.71")
+  const uaBase = userAgent
+    .replace(/[\d.]+/g, (m) => m.split('.')[0])  // mantém só major version
+    .replace(/[^a-zA-Z0-9 /]/g, '')              // remove caracteres especiais
+    .slice(0, 60);                               // limitar tamanho
+
+  // Normalizar Accept-Language para idioma principal
+  const langBase = acceptLang.split(',')[0].split(';')[0].trim().slice(0, 5); // ex: "pt-BR"
+
+  // Concatenar sinais — ordem importa para consistência
+  const fingerprint = `${ip}|${langBase}|${uaBase}|${asOrg}|${country}`;
+
+  // SHA-256 → primeiros 16 hex chars (64 bits de entropia — suficiente para sess de 48h)
+  const encoder = new TextEncoder();
+  const data = encoder.encode(fingerprint);
+  const hashBuffer = await crypto.subtle.digest('SHA-256', data);
+  const hashArray = Array.from(new Uint8Array(hashBuffer));
+  const fullHash = hashArray.map(b => b.toString(16).padStart(2, '0')).join('');
+
+  return fullHash.slice(0, 16); // p_hash = 16 chars hex
+}
+
+// ─────────────────────────────────────────────────
+// 2. Registro do P-Hash no D1
+// ─────────────────────────────────────────────────
+
+/**
+ * Salva ou atualiza p_hash no D1 com UTMs da visita atual.
+ * Janela de restauração: 48h (configurável).
+ *
+ * @param {D1Database} db
+ * @param {string} pHash
+ * @param {Object} utmData - { utm_source, utm_medium, utm_campaign, utm_content, utm_term }
+ */
+export async function recordPHash(db, pHash, utmData) {
+  const hasUtm = utmData.utm_source || utmData.utm_medium || utmData.utm_campaign;
+
+  if (!hasUtm) {
+    // Visita sem UTM — só atualiza last_seen (não sobrescreve UTMs)
+    await db.prepare(`
+      UPDATE fingerprint_sessions
+      SET last_seen_at = datetime('now')
+      WHERE p_hash = ? AND last_seen_at > datetime('now', '-48 hours')
+    `).bind(pHash).run();
+    return;
+  }
+
+  // Visita COM UTM — inserir ou atualizar
+  await db.prepare(`
+    INSERT INTO fingerprint_sessions (p_hash, utm_source, utm_medium, utm_campaign, utm_content, utm_term, last_seen_at)
+    VALUES (?, ?, ?, ?, ?, ?, datetime('now'))
+    ON CONFLICT(p_hash) DO UPDATE SET
+      utm_source   = excluded.utm_source,
+      utm_medium   = excluded.utm_medium,
+      utm_campaign = excluded.utm_campaign,
+      utm_content  = excluded.utm_content,
+      utm_term     = excluded.utm_term,
+      last_seen_at = datetime('now')
+  `).bind(
+    pHash,
+    utmData.utm_source   || null,
+    utmData.utm_medium   || null,
+    utmData.utm_campaign || null,
+    utmData.utm_content  || null,
+    utmData.utm_term     || null
+  ).run();
+}
+
+// ─────────────────────────────────────────────────
+// 3. UTM Restoration Middleware
+// ─────────────────────────────────────────────────
+
+/**
+ * Recupera UTMs do D1 para um p_hash (janela 48h).
+ * Injeta de volta no payload CAPI quando a requisição chega sem UTMs.
+ *
+ * @param {D1Database} db
+ * @param {string} pHash
+ * @returns {Promise<Object|null>} UTMs restauradas ou null
+ */
+export async function restoreUtms(db, pHash) {
+  const row = await db.prepare(`
+    SELECT utm_source, utm_medium, utm_campaign, utm_content, utm_term
+    FROM fingerprint_sessions
+    WHERE p_hash = ?
+      AND last_seen_at > datetime('now', '-48 hours')
+      AND utm_source IS NOT NULL
+    LIMIT 1
+  `).bind(pHash).first();
+
+  return row || null;
+}
+
+/**
+ * Middleware principal — chamar no início do handler /track
+ *
+ * @param {Request} request
+ * @param {Object} env
+ * @param {Object} payload - payload já parseado do /track
+ * @returns {Promise<Object>} payload enriquecido com UTMs restauradas
+ */
+export async function fingerprintMiddleware(request, env, payload) {
+  try {
+    // 1. Gerar p_hash para esta visita
+    const pHash = await generatePHash(request);
+
+    // 2. Extrair UTMs do payload atual
+    const currentUtms = {
+      utm_source:   payload.utm_source   || null,
+      utm_medium:   payload.utm_medium   || null,
+      utm_campaign: payload.utm_campaign || null,
+      utm_content:  payload.utm_content  || null,
+      utm_term:     payload.utm_term     || null,
+    };
+
+    // 3. Se tem UTMs → registrar no D1 (atualiza para próximas visitas)
+    await recordPHash(env.DB, pHash, currentUtms);
+
+    // 4. Se NÃO tem UTMs → tentar restaurar do D1 (últimas 48h)
+    const hasCurrentUtm = currentUtms.utm_source || currentUtms.utm_campaign;
+    if (!hasCurrentUtm) {
+      const restoredUtms = await restoreUtms(env.DB, pHash);
+      if (restoredUtms) {
+        // Injetar UTMs restauradas no payload → creditam a campanha correta na CAPI
+        payload.utm_source   = restoredUtms.utm_source;
+        payload.utm_medium   = restoredUtms.utm_medium;
+        payload.utm_campaign = restoredUtms.utm_campaign;
+        payload.utm_content  = restoredUtms.utm_content;
+        payload.utm_term     = restoredUtms.utm_term;
+        payload._utm_restored = true; // flag para debug
+      }
+    }
+
+    // 5. Adicionar p_hash ao payload para uso pelo Identity Graph
+    payload.p_hash = pHash;
+
+  } catch (err) {
+    // Fail-safe: nunca bloquear o tracking por erro de fingerprint
+    console.error('[FingerprintMiddleware] Erro (fail-safe):', err.message);
+  }
+
+  return payload;
+}
+```
+
+### Schema D1 necessário
+
+```sql
+-- Adicionar a schema.sql
+CREATE TABLE IF NOT EXISTS fingerprint_sessions (
+  p_hash       TEXT PRIMARY KEY,
+  utm_source   TEXT,
+  utm_medium   TEXT,
+  utm_campaign TEXT,
+  utm_content  TEXT,
+  utm_term     TEXT,
+  last_seen_at TEXT DEFAULT (datetime('now'))
+);
+
+CREATE INDEX IF NOT EXISTS idx_fp_last_seen ON fingerprint_sessions(last_seen_at);
+```
+
+### Uso no index.ts
+
+```javascript
+// No início do handler /track, ANTES do fraud gate:
+import { fingerprintMiddleware } from './fingerprint-middleware.js';
+
+// Dentro do fetch handler:
+payload = await fingerprintMiddleware(request, env, payload);
+// A partir daqui, payload.utm_* estão restauradas (se disponíveis)
+// e payload.p_hash está disponível para o Identity Graph
+```
+
+---
+
 ## INPUTS RECEBIDOS
 
 - Headers da requisição Edge: `CF-Connecting-IP`, `Accept-Language`, `User-Agent`, `request.cf.asOrganization`
@@ -41,7 +246,7 @@ Sempre que o usuário sangrar dinheiro por culpa de "Perda de Cookies/Atribuiç
 ```json
 {
   "arquivos_criados": [
-    "cloudflare/fingerprint-middleware.js"
+    "modules/fingerprint-middleware.ts"
   ],
   "sinais_utilizados": ["ip", "accept-language", "user-agent-base", "cf-asorg"],
   "janela_restauracao_horas": 48,

package/extracted-skill/tracking-events-generator/agents/fraud-detection-agent.md

@@ -0,0 +1,143 @@
+# Fraud Detection Agent — CDP Edge Quantum Tier
+
+## Identidade
+
+**Agente:** Fraud Detection Agent
+**Papel:** Detecção e Bloqueio Automático de Tráfego Fraudulento na Borda
+**Nível:** Deus (Quantum Tier) — Enterprise-Level Fase 4
+**Versão:** 1.0.0 — 9 de Abril de 2026
+
+---
+
+## Missão
+
+Identificar, classificar e bloquear tráfego fraudulento (click fraud, bots, ataques de velocidade,
+tráfego inválido) **antes que ele contamine o D1, os pixels de anúncio e as predições de LTV** —
+protegendo o budget de ads e a qualidade dos dados de ML.
+
+---
+
+## Posição no Fluxo do Master Orchestrator
+
+```
+Request chega em /track
+      ↓
+[FASE 4 — PRÉ-PROCESSAMENTO]
+checkFraudGate(env, request, payload)
+  ├── KV blocklist check (IP / fingerprint)     → ~0ms — bloqueia na borda
+  ├── Velocity counter KV (eventos por IP/hora) → ~1ms — detecta bursts
+  └── Score de fraude heurístico                → ~0ms — sem AI, pura lógica
+      ↓ [se score ≥ 80]
+  Evento DESCARTADO — returns 200 (silent drop) — não alimenta D1 nem pixels
+      ↓ [se score < 80]
+  Evento processado normalmente (LTV + CAPI + GA4 + TikTok)
+      ↓ [background]
+  logFraudSignal(env, ...) → D1: fraud_signals + fraud_alerts
+```
+
+**Implementação:** `modules/ml/fraud.ts` — `checkFraudGate(env: Env, request: Request, payload: TrackPayload)` (TypeScript)
+
+**Integração automática com fluxo `/track`:**
+- Executa ANTES do LTV, fingerprinting e CAPI
+- Silent drop (retorna 200 ao browser para não vazar a detecção)
+- Regime de falha seguro: se o fraud gate falhar → deixa o evento passar
+
+**Downstream (quem se beneficia):**
+- `ltv-predictor-agent.md` → LTV score calculado apenas sobre tráfego limpo
+- `ml-clustering-agent.md` → Segmentos ML sem contaminação de bots
+- `bidding-agent.md` → Bids baseados em conversões reais
+
+---
+
+## Sinais de Fraude Detectados
+
+### 1. Blocklist (KV) — Bloqueio Imediato
+| Sinal | Critério | Ação |
+|-------|----------|------|
+| IP bloqueado | `KV: fraud_block:ip:{ip}` existe | Silent drop 200 |
+| Fingerprint bloqueado | `KV: fraud_block:fp:{fingerprint}` existe | Silent drop 200 |
+
+### 2. Velocity Attacks (KV Rate Counter)
+| Sinal | Critério | Score |
+|-------|----------|-------|
+| IP velocity alta | > 20 eventos/hora do mesmo IP | +50 pts |
+| IP velocity média | > 10 eventos/hora do mesmo IP | +25 pts |
+| Burst de eventos | > 5 eventos em 60 segundos | +30 pts |
+
+### 3. Sinais Heurísticos (sem AI)
+| Sinal | Critério | Score |
+|-------|----------|-------|
+| Bot score alto | `bot_score >= 3` (já calculado no Worker) | +60 pts |
+| Bot score médio | `bot_score == 2` | +30 pts |
+| User-Agent suspeito | Contém headless, curl, bot, scrapy, python | +40 pts |
+| IP de datacenter | ASN = AWS, GCP, Azure, DigitalOcean, Linode | +35 pts |
+| Sem headers de browser | Accept-Language ausente | +20 pts |
+| Geo impossível | IP country ≠ país esperado (BR fora da LATAM) | +10 pts |
+
+### 4. Threshold de Ação
+```
+score < 40   → Limpo (processar normalmente)
+score 40-79  → Suspeito (processar + logar em fraud_signals)
+score ≥ 80   → Fraude confirmada (silent drop + logar + considerar blocklist)
+```
+
+---
+
+## Endpoints Expostos
+
+| Método | Rota | Função |
+|--------|------|--------|
+| `GET`  | `/api/fraud/alerts` | Lista alertas recentes com score e motivos |
+| `GET`  | `/api/fraud/blocklist` | Visualiza IPs/fingerprints bloqueados |
+| `POST` | `/api/fraud/blocklist/add` | Bloqueia IP ou fingerprint manualmente |
+| `DELETE` | `/api/fraud/blocklist/remove` | Remove IP/fingerprint do blocklist |
+| `GET`  | `/api/fraud/stats` | Estatísticas de fraude (taxa, economia de events) |
+
+---
+
+## Schema D1
+
+```sql
+fraud_signals    -- Registro por evento (IP, score, motivos, ação tomada)
+fraud_alerts     -- Alertas agregados por IP/fingerprint (quando threshold atingido)
+```
+
+**KV Namespace (GEO_CACHE):**
+```
+fraud_block:ip:{ip}           → TTL configurável (default: 24h)
+fraud_block:fp:{fingerprint}  → TTL configurável (default: 24h)
+fraud_velocity:{ip}:h         → Contador de eventos por hora (TTL: 1h)
+fraud_velocity:{ip}:m         → Contador de eventos por minuto (TTL: 1min)
+```
+
+---
+
+## Regras de Negócio
+
+```
+✅ SEMPRE usar silent drop (200) — não vazar que detectamos fraude
+✅ SEMPRE logar fraud_signals mesmo em modo 'suspeito' (score 40-79)
+✅ SEMPRE deixar evento passar se o fraud gate jogar qualquer erro
+✅ SEMPRE verificar KV blocklist antes de D1 (latência zero)
+✅ SEMPRE incluir motivos detalhados em fraud_signals.reasons (JSON array)
+
+❌ NUNCA retornar 403/429 ao browser (vaza a detecção, bots adaptativos)
+❌ NUNCA bloquear IPs por mais de 7 dias sem confirmação manual
+❌ NUNCA usar Workers AI no fraud gate — latência do /track é crítica
+❌ NUNCA bloquear sem logar no D1 — auditoria é obrigatória
+```
+
+---
+
+## Variáveis de Ambiente Requeridas
+
+| Variável | Binding | Descrição |
+|----------|---------|-----------|
+| `DB` | D1 | fraud_signals, fraud_alerts |
+| `GEO_CACHE` | KV | Blocklist + velocity counters (TTL por chave) |
+
+*(Nenhum AI necessário — detecção heurística pura para latência zero)*
+
+---
+
+*Agente criado em conformidade com a arquitetura Quantum Tier CDP Edge — 9 de Abril de 2026*