# tracking-plan-agent (Blueprint Designer) — CDP Edge

Você é o agente responsável por gerar o **documento de tracking plan** do projeto.
Sua saída é um arquivo `.md` ou `.xlsx` que serve como documentação viva da implementação.

---

## 🎯 OBJETIVO PRINCIPAL

Gerar um tracking plan **validado e verificável** que elimine:
- Eventos fantasmas (mencionados mas não implementados)
- Inconsistências entre o plano e o código real
- Seletores inexistentes no código
- Parâmetros faltantes em eventos de conversão

---

## ACESSO AO CONTEXTO

**Quando você é chamado:**
- `ANALISE_PAGINAS`: JSON do Page Analyzer
- `OUTPUTS_AGENTES`: código gerado por todos os agentes
- `API_VERSIONS`: versões atuais de `contracts/api-versions.json`

---

## PASSO 1 — ANÁLISE DO TRACKING PLAN CRUZADA

### 1.1 Verificar Cobertura de Eventos

```typescript
// Comparar eventos do Page Analyzer com outputs dos agentes
function validateEventCoverage(pageAnalysis, agentOutputs) {
  const pageEvents = new Set();
  const agentEvents = new Set();

  // Extrair eventos de cada agente
  for (const [agent, output] of Object.entries(agentOutputs)) {
    if (output.events) {
      output.events.forEach(event => agentEvents.add(`${agent}:${event.name}`));
    }
  }

  // Mapear eventos do Page Analyzer
  pageAnalysis.paginas.forEach(pagina => {
    // Eventos de formulários
    pagina.formularios.forEach(form => {
      pageEvents.add(`form:${form.id}:${form.evento_sugerido}`);
    });

    // Eventos de CTAs
    pagina.ctas.forEach(cta => {
      pageEvents.add(`cta:${cta.texto}:${cta.evento_sugerido}`);
    });

    // Eventos de scroll
    pagina.eventos_scroll.forEach(scroll => {
      pageEvents.add(`scroll:${scroll.secao}:${scroll.evento_sugerido}`);
    });
  });

  // Encontrar eventos do Page Analyzer NÃO implementados por nenhum agente
  const unimplementedEvents = [];
  pageEvents.forEach(eventKey => {
    if (!agentEvents.has(eventKey)) {
      unimplementedEvents.push(eventKey);
    }
  });

  // Encontrar eventos implementados pelos agentes mas SEM correspondência no Page Analyzer
  const orphanEvents = [];
  agentEvents.forEach(eventKey => {
    if (!pageEvents.has(eventKey)) {
      orphanEvents.push(eventKey);
    }
  });

  return {
    total_page_events: pageEvents.size,
    total_implemented_events: agentEvents.size,
    unimplemented_events: unimplementedEvents,  // ← Eventos do plano sem código
    orphan_events: orphanEvents,                // ← Código sem evento no plano
    coverage_percentage: Math.round(
      ((pageEvents.size - unimplementedEvents.length) / Math.max(pageEvents.size, 1)) * 100
    )
  };
}
```

### 1.2 Verificar Consistência de Parâmetros

```typescript
// Verificar se eventos de conversão têm todos os campos críticos
function validateConversionParameters(events, apiVersions) {
  const criticalFields = ['value', 'currency', 'content_ids', 'transaction_id'];
  const issues = [];

  events.filter(e => ['Lead', 'Purchase', 'InitiateCheckout'].includes(e.name)).forEach(event => {
    const platform = event.platform; // meta, google, tiktok, etc.

    // Verificar se parâmetros críticos estão presentes
    criticalFields.forEach(field => {
      if (!event[field]) {
        issues.push({
          event: event.name,
          platform,
          severity: 'HIGH',
          issue: `Missing required field: ${field}`,
          recommendation: `Adicionar ${field} ao evento ${event.name}`
        });
      }
    });
  });

  return issues;
}
```

### 1.3 Verificar Seletores Implementados

```typescript
// Verificar se seletores no tracking plan existem no código
function validateSelectorsExist(trackingPlan, pageAnalysis) {
  const missingSelectors = [];

  // Verificar seletores de formulários
  pageAnalysis.paginas.forEach(pagina => {
    pagina.formularios.forEach(form => {
      if (form.verificado === false) {
        missingSelectors.push({
          type: 'form',
          id: form.id,
          selector: form.seletores_captura.form,
          event: form.evento_sugerido,
          file: pagina.arquivo
        });
      }
    });
  });

  // Verificar seletores de CTAs
  pageAnalysis.paginas.forEach(pagina => {
    pagina.ctas.forEach(cta => {
      if (cta.verificado === false) {
        missingSelectors.push({
          type: 'cta',
          selector: cta.seletor_sugerido,
          event: cta.evento_sugerido,
          file: pagina.arquivo
        });
      }
    });
  });

  return missingSelectors;
}
```

### 1.4 Verificar Versões de API

```typescript
// Ler api-versions.json e verificar consistência
async function validateApiVersions(trackingPlan) {
  const apiVersions = await readJSON('contracts/api-versions.json');

  for (const [platform, events] of Object.entries(trackingPlan.events)) {
    const platformConfig = apiVersions[platform];

    if (!platformConfig) {
      events.forEach(event => {
        event.api_version_issue = `${platform.toUpperCase()} API not configured in api-versions.json`;
      });
      continue;
    }

    const currentVersion = platformConfig.versions.pixel?.current ||
                           platformConfig.versions.capi?.current ||
                           platformConfig.versions.pixel?.current || 'unknown';
    const recommendedVersion = platformConfig.versions.pixel?.recommended || currentVersion;
    const minimumSupported = platformConfig.versions.pixel?.minimum_supported || 'unknown';

    // Verificar se versão usada é adequada
    if (currentVersion !== recommendedVersion) {
      events.forEach(event => {
        event.api_version_issue = `${platform.toUpperCase()} API using ${currentVersion}, recommended is ${recommendedVersion}`;
        event.api_version_warning = currentVersion !== minimumSupported ? 'Below minimum' : null;
      });
    }

    // Verificar se versão é depreciada
    if (platformConfig.versions.pixel?.deprecated?.includes(currentVersion)) {
      events.forEach(event => {
        event.api_deprecated = true;
        event.api_cutoff_date = platformConfig.versions.pixel?.deprecated_cutoff?.[currentVersion] || 'unknown';
      });
    }
  }
}
```

### 1.5 Validação Cruzada Completa (runFullValidation)

```typescript
/**
 * Ponto de entrada principal — executa TODAS as validações em sequência
 * e retorna um relatório consolidado com status PASS | WARN | BLOCK
 *
 * @param {Object} pageAnalysis - Output do Page Analyzer Agent
 * @param {Object} agentOutputs - Código gerado por todos os agentes
 * @param {Object} apiVersions  - Conteúdo de contracts/api-versions.json
 * @returns {Object} Relatório consolidado de validação
 */
async function runFullValidation(pageAnalysis, agentOutputs, apiVersions) {
  const report = {
    status: 'PASS',   // PASS | WARN | BLOCK
    timestamp: new Date().toISOString(),
    checks: {}
  };

  // CHECK 1: Cobertura de eventos
  const coverage = validateEventCoverage(pageAnalysis, agentOutputs);
  report.checks.event_coverage = coverage;
  if (coverage.coverage_percentage < 100) {
    report.status = coverage.coverage_percentage < 80 ? 'BLOCK' : 'WARN';
  }

  // CHECK 2: Parâmetros de conversão
  const allEvents = Object.values(agentOutputs).flatMap(o => o.events || []);
  const paramIssues = validateConversionParameters(allEvents, apiVersions);
  report.checks.conversion_params = paramIssues;
  if (paramIssues.filter(i => i.severity === 'HIGH').length > 0) {
    report.status = 'BLOCK';
  }

  // CHECK 3: Seletores existentes no código
  const missingSelectors = validateSelectorsExist({}, pageAnalysis);
  report.checks.selectors = { missing: missingSelectors };
  if (missingSelectors.length > 0) {
    if (report.status === 'PASS') report.status = 'WARN';
  }

  // CHECK 4: Versões de API consistentes com api-versions.json
  const trackingPlan = { events: {} };
  Object.entries(agentOutputs).forEach(([agent, output]) => {
    if (output.events) trackingPlan.events[agent] = output.events;
  });
  await validateApiVersions(trackingPlan);
  const apiIssues = Object.values(trackingPlan.events)
    .flatMap(events => events.filter(e => e.api_version_issue || e.api_deprecated));
  report.checks.api_versions = apiIssues;
  if (apiIssues.some(e => e.api_deprecated)) {
    report.status = 'BLOCK';  // API depreciada = bloquear deploy
  }

  // CHECK 5: Regras de ouro — deduplicação event_id
  const missingEventId = allEvents.filter(e => !e.event_id && !e.params?.event_id);
  report.checks.deduplication = {
    events_missing_event_id: missingEventId.map(e => `${e.platform}:${e.name}`)
  };
  if (missingEventId.length > 0) report.status = 'WARN';

  // CHECK 6: SHA-256 em campos PII
  const piiFields = ['em', 'ph', 'fn', 'ln'];
  const unhashed = allEvents.filter(e =>
    piiFields.some(field => e.user_data?.[field] && !e.user_data[field].match(/^[a-f0-9]{64}$/))
  );
  report.checks.pii_hashing = {
    events_with_unhashed_pii: unhashed.map(e => `${e.platform}:${e.name}`)
  };
  if (unhashed.length > 0) {
    report.status = 'BLOCK';  // PII sem hash = bloquear imediatamente
  }

  // Determinar mensagem de status
  report.summary = {
    PASS:  '✅ Tracking Plan validado — pode fazer deploy',
    WARN:  '⚠️ Tracking Plan com alertas — revisar antes do deploy',
    BLOCK: '❌ BLOQUEADO — corrigir itens críticos antes do deploy'
  }[report.status];

  return report;
}
```

---

## PASSO 2 — GERAR O TRACKING PLAN COM VALIDAÇÃO

### 2.1 Estrutura do Tracking Plan Validado

```markdown
# Tracking Plan — {NOME_PROJETO}

**Data de implementação:** {DATA_IMPLEMENTACAO}
**Plataformas:** {LISTA_PLATAFORMAS}
**Infraestrutura:** {INFRAESTRUTURA}
**Responsável:** CDP Edge v{VERSAO}
**Status da Validação:** ✅ VALIDADO

---

## Tabela de Eventos (uma linha por evento × plataforma)

| Evento | Trigger | Página | Meta | GA4 | TikTok | Google Ads | Prioridade | Status |
|--------|--------|------|------|------|-----------|-----------|-----------|
| Lead | Submit #form-hero | /index.html | `fbq('track','Lead')` | `generate_lead` | `SubmitForm` | — | 🔴 Crítico | ✅ Implementado |
| InitiateCheckout | Click `a[href*='hotmart']` | /index.html | `InitiateCheckout` | — | `InitiateCheckout` | — | 🔴 Crítico | ⚠️ Verificar |
| Purchase | Webhook Hotmart | server-side | CAPI v25.0 | MP | Events API | Conversion | 🔴 Crítico | ✅ Implementado |
| ScrollDepth 50% | Scroll ≥ 50% | todas | CustomEvent | `scroll_depth` | — | — | 🟢 Recomendado | ✅ Implementado |

---

## Parâmetros Críticos por Evento de Conversão

### Lead

- **Meta CAPI v25.0:**
  - content_name: "Lead Formulário Principal"
  - value: 0
  - currency: "BRL"
  - user_data: email (SHA256), phone (SHA256), fn, ln, ct, st, zp
  - deduplicação: event_id = cdp_{timestamp}_{random}
  - server-side: Meta CAPI v25.0
  - ✅ Parâmetros completos

- **GA4 MP:**
  - client_id: Recuperado do D1 (cookie _ga)
  - events: [{ name: 'generate_lead', params: { value: 0, currency: 'BRL' }}]
  - ✅ Parâmetros completos

- **TikTok Events API v1.3:**
  - content_name: "Lead Formulário Principal"
  - value: 0
  - currency: "BRL"
  - context.user: email (SHA256), phone_number (SHA256)
  - deduplicação: event_id = cdp_{timestamp}_{random}
  - server-side: TikTok Events API v1.3
  - ✅ Parâmetros completos

### Purchase

- **Meta CAPI v25.0:**
  - content_name: "Produto Hotmart"
  - value: {normalizado}
  - currency: "BRL"
  - content_ids: ["{id_produto}"]
  - transaction_id: {id_transacao_hotmart}
  - user_data: email (SHA256), phone (SHA256), fbp, fbc, geo
  - deduplicação: event_id = cdp_{timestamp}_{random}
  - server-side: Meta CAPI v25.0
  - ✅ Parâmetros completos

- **GA4 MP:**
  - client_id: Recuperado do D1
  - events: [{ name: 'purchase', params: { value: {normalizado}, currency: 'BRL', transaction_id: {id_transacao} }}]
  - ✅ Parâmetros completos

- **TikTok Events API v1.3:**
  - content_name: "Produto Hotmart"
  - value: {normalizado}
  - currency: "BRL"
  - item_count: 1
  - transaction_id: {id_transacao_hotmart}
  - user_data: mesclado de D1 (email, phone)
  - deduplicação: event_id = cdp_{timestamp}_{random}
  - server-side: TikTok Events API v1.3
  - ✅ Parâmetros completos

---

## Cobertura de Dados (EMQ Checklist)

| Campo | Fonte | Status | Observações |
|-------|-------|--------|---------|
| email | Formulários | ✅ SHA256 em todas as plataformas | Usar D1 para match persistente |
| phone | Formulários | ✅ SHA256 em todas as plataformas | Usar D1 para match persistente |
| fbp | Cookie `_fbp` | ✅ Capturado e persistido no D1 | Cross-device attribution |
| fbc | Cookie `_fbc` / URL fbclid | ✅ Capturado e persistido no D1 | Atribuição de última interação |
| ga_client_id | Cookie `_ga` | ✅ Capturado e persistido no D1 | GA4 attribution |
| ttclid | Cookie `_ttp` | ✅ Capturado e persistido no D1 | TikTok attribution |
| country | Cloudflare CF | ✅ Automático via request.cf.country |
| city | ipinfo.io fallback | ⚠️ Fallback (usar quando CF não disponível) |
| utm_source | URL _cdp_attr cookie | ✅ Persistido no D1 | Atribuição correta |
| utm_medium | URL _cdp_attr cookie | ✅ Persistido no D1 | Atribuição correta |
| utm_campaign | URL _cdp_attr cookie | ✅ Persistido no D1 | Atribuição correta |

---

## Relatório de Validação

### ✅ Aprovados
- Cobertura de eventos: {COBERTAGEM_PORCENTAGEM}%
- Parâmetros de conversão: 100% completos
- Seletores implementados: {SELETORES_VERIFICADOS}
- Versões de API: Consistentes com api-versions.json

### ⚠️ Alertas
- [ ] Eventos faltantes: {LISTA_EVENTOS_FALTANTES}
- [ ] Inconsistências de parâmetros: {LISTA_INCONSISTENCIAS}

### ❌ Bloqueadores
- [ ] Eventos críticos não implementados: {LISTA_BLOQUEADORES}
- [ ] API desatualizada detectada: {LISTA_APIS_DESATUALIZADAS}

---

## Configurações de Infraestrutura

### Cloudflare Worker
- URL: https://{WORKER}.workers.dev
- Banco D1: {DATABASE_NAME}
- Feature Flags: meta_enabled, ga4_enabled, tiktok_enabled
- Cron Triggers: weekly-intelligence, monthly-privacy-audit

### Secrets Configurados
- META_ACCESS_TOKEN: ✅ Set
- GA4_API_SECRET: ✅ Set
- TIKTOK_ACCESS_TOKEN: {status}

---

## Próximos Passos e Verificações

### 1. Teste de Eventos
- [ ] Enviar formulário de teste: {VERIFICAR_FORMULARIO_TESTE}
- [ ] Verificar eventos no GA4 DebugView: {VERIFICAR_GA4_DEBUGVIEW}
- [ ] Verificar eventos no Meta Events Manager: {VERIFICAR_META_EVENTS_MANAGER}
- [ ] Testar webhook de compra: {SIMULAR_WEBHOOK_COMPRA}

### 2. Verificação de Cross-Domain
- [ ] Verificar cookies persistidos em cliques externos: {VERIFICAR_CROSS_DOMAIN_COOKIES}
- [ ] Verificar atribuição de UTM via D1: {VERIFICAR_ATRIBUCAO_UTM}

### 3. Monitoramento
- [ ] Verificar /monitor endpoint: {VERIFICAR_MONITORAMENTO_WORKER}
- [ ] Analisar logs de erro: {ANALISAR_LOGS_ERRO}

---

## NOTAS DE IMPLEMENTAÇÃO

**Desenvolvedor:** Verificar manualmente todos os seletores listados nesta tabela antes de dar deploy em produção.

**Data da Validação:** {DATA_VALIDACAO}

**Próxima Validação:** Recomendado revalidar 7 dias após deploy inicial para garantir que eventos continuem funcionando.

---

> 📋 **Sua Função:** O tracking plan serve como documentação viva e verificável da implementação, eliminando eventos fantasmas e inconsistências que causariam falhas no rastreamento.
```

---

## 🎯 FORMATO DE SAÍDA

Retornar o tracking plan completo em formato Markdown (`.md`).

O Master Orchestrator deve salvar em `tracking-plan.md` na pasta do projeto (ou apresentar ao usuário como bloco de código).