# Metodologia de Scoring — Mapeamento de Leads PX3 LAB
## Lançamento Cloud PhotoRF 2.0 | 07/10/2026

**Gerado em:** 2026-09-30
**Total processado:** 5.393 contatos
**Versão do scoring:** v3 (calibrado após análise das tags reais da base)

---

## Fontes de dados utilizadas

| Fonte | Dados puxados | Endpoint |
|-------|--------------|----------|
| GHL Contatos | Nome, email, telefone, tags, custom fields UTM/SDR, dnd, dateUpdated | `GET /contacts/?locationId=...&limit=100` (54 páginas) |
| GHL Oportunidades | Pipeline, stage atual, status | `GET /opportunities/search?location_id=...&limit=100` (36 páginas) |

---

## Campos de custom fields lidos

| Campo | ID GHL | Uso no scoring |
|-------|--------|----------------|
| utm_source | ysHWPzyR0uZ2nd8D9sbi | identificação de origem |
| utm_medium | Hiabk9sp0zIkgLjUYJjR | contexto do canal |
| utm_campaign | H16g1x7tRA8OoHnqiTdp | sinal de campanha ativa |
| sdr__temperatura_lead | lKiTBLRCMYLT2XmzcbFg | classificação manual SDR |
| sdr__resultado_final | 8ekpHqngQqNFZT6JphdK | resultado do atendimento SDR |
| sdr__produto_interesse | mqOExdhEAtRPd5rOl664 | produto de interesse declarado |

---

## Regras de descarte imediato (score -999)

O lead é descartado antes de qualquer scoring se:
1. **DND ativo** (`dnd = true` no GHL)
2. **Tag de descarte** presente: `no-contact`, `bounce`, `unsubscribe`, `invalido`, `spam`, `opt-out`, `cancelado`, `blocked`
3. **Sem email** cadastrado - inviável para campanha de email marketing

Nota: 2.549 dos 2.565 descartados estão sem email. Apenas 16 foram descartados por tag ou DND.

---

## Sistema de pontuação (scores somados)

### Sinais de produto - CloudPhotoRF (mais altos)

| Sinal | Tag/Campo | Pontos | Justificativa |
|-------|-----------|--------|---------------|
| Comprou CloudPhotoRF anterior | `comprou-claud-photorf` | +70 | Cliente confirmado - recompra é o caso mais quente possível |
| Iniciou checkout | `iniciou_fluxo_compra_cloud` | +65 | Intenção de compra máxima, chegou a abrir o pagamento |
| No funil do produto | `cloud photorf` | +40 | Entrou no fluxo específico do produto |
| Em nutrição Cloud PhotoRF | `nutricao_cloud_photorf` | +30 | Recebendo sequência de email sobre o produto |
| Aquecimento concluído | `aquecimento-concluido` | +20 | Completou sequência de aquecimento |

### Sinais de interesse PX3 (complementares)

| Sinal | Tag/Campo | Pontos |
|-------|-----------|--------|
| Prospecção ativa | `prospeccao-ativa` | +15 |
| Tag fotografia | `fotografia` | +15 |

### Recência de interação (dateUpdated)

| Janela | Pontos |
|--------|--------|
| 0-7 dias | +30 |
| 8-30 dias | +20 |
| 31-60 dias | +10 |
| 61-90 dias | +5 |
| 91-180 dias | 0 |
| +180 dias | 0 (sem penalidade - preserva quem tem sinal de produto) |

---

## Thresholds de bucket

| Score | Bucket |
|-------|--------|
| >= 60 | QUENTE |
| 30-59 | MORNO |
| 5-29 | FRIO |
| -10 a 4 | GELADO |
| < -10 ou descarte | DESCARTE |

**Nota:** Os sinais de produto (comprou + checkout) garantem score >= 65 isoladamente, colocando esses leads sempre em QUENTE independentemente de recência. Esta foi uma decisão deliberada: histórico de compra supera qualquer inatividade recente.

---

## O que NÃO foi possível incluir

1. **Abertura/clique de email** - GHL não expõe métricas de engajamento de email via API REST
2. **Visitas à LP espera.px3lab.com.br** - dados do CAPI PageView estão no SQLite do micro-serviço, não no GHL
3. **Dados do Hotmart** - histórico de compras aprovadas estaria em `comprou-claud-photorf` se o workflow GHL estiver funcionando
4. **Social Planner engagement** - sem endpoint de API para isso

---

## Limitações e ressalvas

1. `dateUpdated` no GHL atualiza a cada qualquer mudança no registro, não só interações reais do lead. Pode superestimar recência de quem foi atualizado por importação/automação.
2. Leads com tag `importação odoo` (1.684 contatos) foram importados de sistema externo - sua recência reflete a importação, não interação real.
3. O campo `sdr__temperatura_lead` estava vazio em praticamente todos os contatos, sugerindo que o SDR não preencheu sistematicamente.
4. UTM campaign estava preenchido em apenas 1 contato da base - o enricher pode não ter rodado o backfill completo ou a maioria veio por canais não-UTM.

---

## Reprodução futura

Para replicar este mapeamento em próximos lançamentos:
1. Script em: `/opt/mia/workspace/clientes/px3lab/mapeamento_leads_lancamento_1007/fetch_and_score.py`
2. Atualizar as tags de produto nas constantes `TAGS_PRODUTO_*` conforme o novo lançamento
3. Ajustar thresholds de recência conforme estratégia de cada campanha
4. Rodar: `python3 fetch_and_score.py`