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:93ca82979egit-subtree-split:b77484946f
This commit is contained in:
Gustavo
Claude Sonnet 5
@@ -0,0 +1,192 @@
|
||||
# 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.
|
||||
Reference in New Issue
Block a user