Gustavo
4f736562f3
This work already existed uncommitted in the main working tree (not authored by this branch) and is required as a runtime dependency for the campaign outreach port (zpro-client, templates, outreach routes/UI). Copied in as-is, untouched, so this feature branch has a working baseline; the original uncommitted state in the main checkout is left exactly as it was.
193 lines
7.5 KiB
Markdown
193 lines
7.5 KiB
Markdown
# GTI Maquina Comercial
|
|
|
|
Aplicativo local do Grupo GTI para capturar, qualificar, tratar e acionar leads B2B via WhatsApp. O sistema roda no computador do usuario, usa SQLite como banco local e integra com Z-PRO/GChat para envio manual ou automatico.
|
|
|
|
URL local padrao: `http://127.0.0.1:3900`
|
|
|
|
Login inicial: `admin` / `admin`
|
|
|
|
## Uso Diario
|
|
|
|
1. Abra `GTI-Comercial.exe` ou `INICIAR-GTI.bat`.
|
|
2. Acesse `http://127.0.0.1:3900` e faca login.
|
|
3. Use a aba `Capturar Leads` para escolher UF, cidades, nichos e fontes.
|
|
4. Use a aba `Tratar Leads` para filtrar, priorizar, abrir detalhes e exportar leads.
|
|
5. Use o botao de WhatsApp na primeira coluna da tabela para iniciar uma mensagem para um lead especifico.
|
|
6. Use `Configuracoes` para ajustar Z-PRO, templates WABA, limites de envio, usuarios e exportacoes.
|
|
|
|
## Principais Recursos
|
|
|
|
- Captura de leads B2B por UF, cidade e nicho.
|
|
- Base CNPJ da Receita Federal como fonte principal.
|
|
- Fontes complementares: OpenStreetMap/Overpass, Nominatim, Wikidata, BrasilAPI e Google Places.
|
|
- Deduplicacao por CNPJ, telefone/WhatsApp ou empresa+cidade.
|
|
- Scores de qualidade e potencial comercial.
|
|
- Dashboard com totais, rankings, funil e maior oportunidade.
|
|
- Tabela de tratamento com filtros, paginação e detalhe completo do lead.
|
|
- Acao rapida de WhatsApp por lead, fixa na primeira coluna da tabela.
|
|
- Envio manual por Z-PRO para numero especifico.
|
|
- Envio oficial por template WABA aprovado.
|
|
- Sincronizacao de templates WABA do GChat.
|
|
- Pre-visualizacao de templates com variaveis resolvidas por lead.
|
|
- Automacao de envio por produto recomendado, com limite diario.
|
|
- Exportacoes para Excel/CSV, oportunidades Z-PRO e disparo em massa.
|
|
- Login local com usuarios `admin` e `comercial`.
|
|
|
|
## Fluxo Comercial
|
|
|
|
1. Capture ou importe a base de leads.
|
|
2. Filtre por cidade, nicho, qualidade, WhatsApp, prioridade ou status de exportacao.
|
|
3. Revise o lead na tabela ou no modal de detalhes.
|
|
4. Clique no botao de WhatsApp do lead para abrir o envio manual com o numero preenchido.
|
|
5. Escolha texto livre ou template oficial.
|
|
6. Se usar template, selecione o modelo salvo e confira a pre-visualizacao.
|
|
7. Envie pelo Z-PRO e acompanhe o log de envios.
|
|
|
|
Ao abrir o envio manual a partir de um lead, o app busca os dados completos desse cliente. Variaveis como `{{cnpj}}`, `{{empresa}}`, `{{businessName}}`, `{{produto}}`, `{{cidade}}`, `{{uf}}`, `{{segmento}}`, `{{whatsapp}}` e `{{email}}` sao preenchidas com os dados reais do lead na pre-visualizacao e no envio.
|
|
|
|
## WhatsApp, Z-PRO e GChat
|
|
|
|
O app suporta dois tipos de envio:
|
|
|
|
| Canal | Uso | Observacao |
|
|
|---|---|---|
|
|
| Nao oficial/texto livre | Mensagem manual simples | Usa endpoint externo do Z-PRO para enviar texto |
|
|
| Oficial/template WABA | Mensagem com template aprovado | Usa template Meta/WABA via Z-PRO |
|
|
|
|
Configuracoes importantes ficam em `Configuracoes`:
|
|
|
|
- Base URL Z-PRO.
|
|
- API ID Z-PRO.
|
|
- Token/Bearer token.
|
|
- Rota do template (`template`, `templateBody` ou equivalente configurado).
|
|
- URL de templates do GChat.
|
|
- Token GChat opcional para sincronizar modelos.
|
|
- Limite diario de envios.
|
|
- Templates automaticos por produto.
|
|
|
|
O seletor de templates WABA permite carregar modelos sincronizados do GChat. O sistema identifica variaveis posicionais como `{{1}}`, `{{2}}`, `{{3}}` no corpo do template e mostra os campos necessarios.
|
|
|
|
## Variaveis Suportadas
|
|
|
|
As mensagens e templates podem usar variaveis internas da Maquina Comercial/GChat:
|
|
|
|
| Variavel | Valor esperado |
|
|
|---|---|
|
|
| `{{name}}` | Nome do contato quando existir; fallback para empresa |
|
|
| `{{empresa}}` | Nome da empresa |
|
|
| `{{businessName}}` | Nome da empresa no padrao GChat |
|
|
| `{{firstName}}` | Primeiro nome |
|
|
| `{{lastName}}` | Sobrenome, quando existir |
|
|
| `{{produto}}` | Produto recomendado/interesse |
|
|
| `{{protocol}}` | Assunto/protocolo; fallback para produto |
|
|
| `{{cidade}}` | Cidade |
|
|
| `{{uf}}` | UF |
|
|
| `{{segmento}}` | Nicho/segmento |
|
|
| `{{cnpj}}` | CNPJ |
|
|
| `{{email}}` | E-mail |
|
|
| `{{phoneNumber}}` | WhatsApp/telefone |
|
|
| `{{whatsapp}}` | WhatsApp/telefone |
|
|
| `{{kanban}}` | Produto/interesse |
|
|
| `{{user}}` | Remetente |
|
|
| `{{userEmail}}` | E-mail do remetente |
|
|
| `{{greeting}}` | Saudacao |
|
|
|
|
Tambem existem placeholders legados: `{empresa}`, `{cidade}`, `{produto}` e `{segmento}`.
|
|
|
|
## Exportacoes
|
|
|
|
| Tipo | Saida | Para que serve |
|
|
|---|---|---|
|
|
| Planilha | CSV + XLS | Analise comercial e tratamento externo |
|
|
| Z-PRO Oportunidades | JSONL | Payloads para criacao de oportunidades |
|
|
| Z-PRO Disparo em massa | CSV | `dataInput` para disparo em massa |
|
|
|
|
Leads exportados ficam marcados. Use o filtro de nao exportados para evitar retrabalho.
|
|
|
|
## Score e Priorizacao
|
|
|
|
O app calcula scores para ajudar o time comercial a decidir quem abordar primeiro.
|
|
|
|
Regras principais:
|
|
|
|
- WhatsApp/telefone valido aumenta a prioridade.
|
|
- CNPJ valido aumenta a confiabilidade.
|
|
- Empresa valida, cidade, nicho, CNAE, website e e-mail melhoram o score.
|
|
- Nichos com maior aderencia comercial recebem mais peso.
|
|
- Leads sem WhatsApp podem continuar cadastrados, mas aparecem com prioridade menor.
|
|
- Duplicidade segue a ordem CNPJ, telefone, empresa+cidade.
|
|
|
|
## Fontes de Captura
|
|
|
|
- Base CNPJ da Receita Federal: fonte principal para empresas ativas por UF.
|
|
- OpenStreetMap/Overpass: fonte aberta complementar.
|
|
- Nominatim: geocodificacao e apoio geografico.
|
|
- Wikidata: fonte aberta de baixo volume.
|
|
- BrasilAPI: enriquecimento de dados cadastrais.
|
|
- Google Places: fonte opcional paga, exige `GOOGLE_MAPS_API_KEY` no `.env`.
|
|
|
|
## Comandos
|
|
|
|
```bash
|
|
npm start
|
|
npm test
|
|
npm run capture
|
|
npm run extract
|
|
npm run recalc-scores
|
|
npm run outreach
|
|
npm run build:launcher
|
|
```
|
|
|
|
Exemplos:
|
|
|
|
```bash
|
|
node scripts/servidor.mjs
|
|
node scripts/capturar-leads.mjs --sources=cnpj-base --uf=BA --cities="Ilheus"
|
|
node scripts/extrair-base-cnpj.mjs --uf=SP
|
|
node scripts/enviar-outreach.mjs
|
|
```
|
|
|
|
## Estrutura
|
|
|
|
```text
|
|
GTI-Comercial.exe Launcher local do app
|
|
INICIAR-GTI.bat Inicializacao alternativa no Windows
|
|
scripts/ Entradas de linha de comando
|
|
src/ Codigo do servidor e regras de negocio
|
|
src/server/ HTTP, rotas, sessoes e autenticacao
|
|
src/capture/ Pipeline de captura
|
|
src/sources/ Fontes de dados
|
|
src/treatment/ Consultas e dashboard de tratamento
|
|
src/export/ Exportacoes Excel/CSV/Z-PRO
|
|
src/outreach/ Z-PRO, templates WABA e automacao WhatsApp
|
|
public/ Interface HTML/CSS/JS
|
|
tests/ Testes automatizados
|
|
data/gti.db Banco SQLite local, nao versionado
|
|
data/exports/ Arquivos exportados, nao versionado
|
|
prospeccao/cnpj/ Base CNPJ e dados brutos da Receita
|
|
docs/ Documentacao complementar
|
|
.env Segredos locais, nao versionado
|
|
```
|
|
|
|
## Requisitos
|
|
|
|
- Windows.
|
|
- Node.js 24 ou superior.
|
|
- Para extrair novas UFs, `unzip`, Git Bash ou `tar` nativo do Windows.
|
|
|
|
## Seguranca e Dados
|
|
|
|
- O banco principal fica em `data/gti.db`.
|
|
- Segredos locais devem ficar no `.env` ou nas configuracoes locais do app.
|
|
- Tokens Z-PRO/GChat nao devem ser commitados.
|
|
- A zona de risco em Configuracoes apaga leads, capturas e exportacoes; a acao e irreversivel.
|
|
- Nao ha backup automatico do banco local.
|
|
|
|
## Problemas Comuns
|
|
|
|
- Se a tela nao abrir, reinicie por `GTI-Comercial.exe` ou `INICIAR-GTI.bat`.
|
|
- Se preferir depurar, rode `node scripts/servidor.mjs` no terminal.
|
|
- Log do servidor: `data/server.log`.
|
|
- Se a sincronizacao de templates GChat falhar com erro de token, gere/salve um token GChat valido novamente.
|
|
- Se um template WABA falhar no Z-PRO, teste outro template aprovado e confira rota, idioma e variaveis obrigatorias.
|