DESKTOP-F2O4A80\UserandClaude
b8d10b210c
App local (Node + SQLite) para captura, tratamento e exportacao de leads comerciais, com dashboard de gestao, login/usuarios e integracao Z-PRO. Co-Authored-By: Claude <noreply@anthropic.com>
90 lines
3.9 KiB
Markdown
90 lines
3.9 KiB
Markdown
# GTI Máquina Comercial
|
||
|
||
Aplicativo local do Grupo GTI para **capturar** e **tratar** leads B2B em qualquer
|
||
estado/cidade do Brasil, com foco na base oficial de CNPJs da Receita Federal.
|
||
|
||
## Como usar (dia a dia)
|
||
|
||
1. Dê dois cliques em **`GTI-Comercial.exe`** (ou em `INICIAR-GTI.bat`).
|
||
2. O navegador abre em `http://127.0.0.1:3900` com duas abas:
|
||
- **📡 Capturar Leads** — escolha estado, cidades, nichos e fontes e rode a captura
|
||
com progresso ao vivo. Se a base CNPJ do estado ainda não existe, o botão
|
||
"Extrair base agora" prepara tudo (~40–60 min, uma única vez por estado).
|
||
- **📊 Tratar Leads** — dashboard com totais e rankings por cidade/nicho, navegador
|
||
de leads com filtros (qualidade, WhatsApp, exportado...) e o botão
|
||
**Gerar relatório / exportação** que produz os arquivos para envio.
|
||
|
||
Tudo roda somente neste computador (porta local 127.0.0.1). Nenhum dado sai da máquina,
|
||
exceto as consultas às fontes públicas durante a captura.
|
||
|
||
## Exportações disponíveis
|
||
|
||
| Tipo | Para quê |
|
||
|---|---|
|
||
| 📊 Planilha (CSV + Excel) | Lista completa com score — números como texto, sem notação científica |
|
||
| 🗂️ Z-PRO Oportunidades (JSONL) | Um payload `createOpportunity` por linha, pronto para importar |
|
||
| 📨 Z-PRO Disparo em massa (CSV) | `dataInput` para `BulkSendMessageWithVariable` + instruções |
|
||
|
||
Leads exportados ficam marcados — o filtro "ainda não exportados" evita reenvio.
|
||
Os IDs padrão do Z-PRO (pipeline/etapa/responsável) ficam no ⚙️ Configurações.
|
||
|
||
> O `.xls` gerado é uma tabela HTML (o Excel avisa sobre o formato ao abrir — é normal,
|
||
> basta confirmar). Use o `.csv` se preferir.
|
||
|
||
## Qualidade dos leads (score)
|
||
|
||
Score: +35 telefone válido, +25 CNPJ válido, +25 empresa válida, +5 cidade,
|
||
+5 nicho, +5 CNAE. **Bom ≥ 85**, médio 60–84, ruim < 60. Empresa vazia, com lixo
|
||
ou começando com número é sempre **ruim** (regra crítica). Duplicidade: CNPJ →
|
||
WhatsApp → empresa+cidade.
|
||
|
||
## Fontes de captura
|
||
|
||
- **Base CNPJ (Receita Federal)** — principal: todas as empresas ativas da UF, ~97% com telefone.
|
||
- **OpenStreetMap** (Overpass e Nominatim) — grátis, complementar.
|
||
- **Wikidata** — grátis, volume baixo.
|
||
- **BrasilAPI** — enriquecimento opcional da base CNPJ.
|
||
- **Google Places** — paga; preencha `GOOGLE_MAPS_API_KEY` no `.env`.
|
||
|
||
## Novo estado (ex.: expandir para Sergipe)
|
||
|
||
1. Na aba Captura, escolha **SE — Sergipe**.
|
||
2. Clique em **Extrair base agora** e aguarde (usa os zips já baixados em
|
||
`prospeccao/cnpj/rfb-raw/`).
|
||
3. Pronto: capture qualquer cidade de SE normalmente. Nada muda na interface.
|
||
|
||
Os zips brutos da Receita (7 GB, Brasil inteiro) já estão no projeto. Para atualizá-los
|
||
no futuro (a Receita publica mensalmente): `bash scripts/baixar-base-rfb.sh`.
|
||
|
||
## Uso avançado (linha de comando)
|
||
|
||
```bash
|
||
npm start # sobe o servidor
|
||
npm test # roda os testes
|
||
node scripts/capturar-leads.mjs --sources=cnpj-base --uf=BA --cities="Ilheus"
|
||
node scripts/extrair-base-cnpj.mjs --uf=SP # extrai base de outra UF
|
||
```
|
||
|
||
## Estrutura do projeto
|
||
|
||
```
|
||
GTI-Comercial.exe inicia tudo (servidor + navegador)
|
||
scripts/ entradas de linha de comando
|
||
src/ código do servidor, fontes de captura, exportações
|
||
public/ interface (HTML/CSS/JS)
|
||
data/gti.db banco local (SQLite) com todos os leads
|
||
data/exports/ arquivos de exportação gerados
|
||
prospeccao/cnpj/ base CNPJ extraída por UF + zips brutos da Receita
|
||
docs/ playbook comercial, LGPD e referência da API Z-PRO
|
||
```
|
||
|
||
## Requisitos
|
||
|
||
- Windows com **Node.js 24+** (https://nodejs.org)
|
||
- Para extrair novas UFs: `unzip` (vem com o Git para Windows) ou o `tar` nativo do Windows
|
||
|
||
## Log e problemas
|
||
|
||
- Log do servidor: `data/server.log`
|
||
- Se a tela não abrir: rode `node scripts/servidor.mjs` num terminal e veja a mensagem.
|