chore: import gti-maquina-comercial history via subtree

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com> git-subtree-dir: gti-maquina-comercial git-subtree-mainline: 93ca82979e git-subtree-split: b77484946f
2026-09-28 15:50:08 -03:00
parent 93ca82979e b77484946f
commit f5af038e19
110 changed files with 27501 additions and 0 deletions
@@ -0,0 +1,75 @@
+# Captura de Leads
+
+A captura procura empresas por **UF + cidades + nichos** nas fontes selecionadas,
+pontua cada lead (score/classificação) e grava tudo no banco local com
+deduplicação automática — um lead capturado uma vez nunca é duplicado, em nenhuma
+execução futura.
+
+O jeito normal de usar é pela **aba "Capturar Leads" do aplicativo**
+(GTI-Comercial.exe). Este documento cobre os detalhes e o uso por linha de comando.
+
+## Fontes
+
+| Fonte | Custo | Observações |
+|---|---|---|
+| `cnpj-base` | grátis | **Principal.** Base oficial da Receita Federal extraída por UF (~97% com telefone). |
+| `brasilapi` | grátis | Mesma base CNPJ, enriquecida online via BrasilAPI (mais lenta). |
+| `overpass` | grátis | OpenStreetMap por área da cidade (bounding box automática via geocode). |
+| `nominatim` | grátis | Busca textual no OpenStreetMap. |
+| `wikidata` | grátis | Empresas registradas no Wikidata (volume baixo). |
+| `google-places` | paga | Exige `GOOGLE_MAPS_API_KEY` no `.env`. |
+| `mock` | — | 3 leads fictícios para testar o fluxo. |
+
+## Base CNPJ por estado
+
+Cada UF precisa de uma extração única (~40–60 min) que gera
+`prospeccao/cnpj/estabelecimentos-<UF>.csv` a partir dos zips brutos da Receita
+(`prospeccao/cnpj/rfb-raw/`, Brasil inteiro, já baixados). A interface oferece o
+botão **"Extrair base agora"** quando a UF escolhida ainda não tem base; na linha
+de comando:
+
+```bash
+node scripts/extrair-base-cnpj.mjs --uf=SP
+```
+
+A extração cobre **todos os municípios da UF** — depois dela, qualquer cidade do
+estado pode ser capturada na hora, sem re-extração. Um checkpoint em disco permite
+retomar de onde parou se o processo for interrompido.
+
+## Deduplicação e pontuação
+
+- Chave de duplicidade: **CNPJ válido → WhatsApp válido → empresa+cidade**.
+- **Score de Qualidade** (0-100, "os dados são confiáveis?"): +30 WhatsApp válido,
+  +20 CNPJ válido, +20 empresa válida, +5 cidade, +10 nicho, +10 CNAE, +5 website.
+- **Score Comercial** (0-100, "qual a chance de comprar?"): aderência do nicho
+  (alta 40 / média 30 / baixa 20, configurada por nicho em `prospeccao/config.json`)
+  + website 15 + e-mail 10 + WhatsApp válido 15 + CNPJ válido 20.
+- **Score Geral** = 60% comercial + 40% qualidade — é o valor usado para ordenar
+  a tela de Tratamento.
+- **Classificação**: 90-100 Excelente, 75-89 Bom, 55-74 Médio, 35-54 Baixo,
+  0-34 Muito Baixo. A **Prioridade comercial** (P1-P4, mostrada na tela) deriva
+  direto dela: Excelente/Bom ⇒ P1 (atacar já), Médio ⇒ P2 (na semana), Baixo ⇒ P3,
+  Muito Baixo ⇒ P4 (só em campanhas específicas).
+- Cada nicho tem produtos GTI recomendados automaticamente (ERP, G-Delivery,
+  G-Chat, Sistema de Ponto) que aparecem no card do lead. Se o catálogo de
+  aderência/produtos do `config.json` mudar, rode `npm run recalc-scores` para
+  recalcular todos os leads já capturados.
+
+## Linha de comando (uso avançado)
+
+```bash
+node scripts/capturar-leads.mjs --sources=mock
+node scripts/capturar-leads.mjs --sources=cnpj-base --uf=BA --cities="Ilheus,Itabuna"
+node scripts/capturar-leads.mjs --sources=cnpj-base,overpass --uf=BA --cities=all --segments=all
+node scripts/capturar-leads.mjs --help
+```
+
+Parâmetros úteis: `--segments=a,b,c` (nichos pelo nome), `--segment-limit=N`,
+`--city-limit=N`, `--max=N` (resultados por consulta nas fontes de API),
+`--query-limit=N` (teto total de consultas).
+
+## Ritmo e boas práticas (fontes OpenStreetMap)
+
+Os servidores públicos do Overpass/Nominatim têm limites de uso. O app já aplica
+espera entre consultas (`OVERPASS_REQUEST_DELAY_MS`), failover entre endpoints e
+cooldown após falhas — falha de uma cidade não derruba a captura, só pula.