Carry over pre-existing WABA outreach automation WIP

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.
2026-08-01 10:12:25 -03:00
parent 0894ab68b3
commit 4f736562f3
33 changed files with 3537 additions and 342 deletions
@@ -1,89 +1,192 @@
-# GTI Máquina Comercial
+# GTI Maquina 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.
+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.

-## Como usar (dia a dia)
+URL local padrao: `http://127.0.0.1:3900`

-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.
+Login inicial: `admin` / `admin`

-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.
+## Uso Diario

-## Exportações disponíveis
+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.

-| Tipo | Para quê |
+## 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 |
 |---|---|
-| 📊 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 |
+| `{{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 |

-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.
+Tambem existem placeholders legados: `{empresa}`, `{cidade}`, `{produto}` e `{segmento}`.

-> O `.xls` gerado é uma tabela HTML (o Excel avisa sobre o formato ao abrir — é normal,
-> basta confirmar). Use o `.csv` se preferir.
+## Exportacoes

-## Qualidade dos leads (score)
+| 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 |

-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.
+Leads exportados ficam marcados. Use o filtro de nao exportados para evitar retrabalho.

-## Fontes de captura
+## Score e Priorizacao

- **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`.
+O app calcula scores para ajudar o time comercial a decidir quem abordar primeiro.

-## Novo estado (ex.: expandir para Sergipe)
+Regras principais:

-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.
+- 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.

-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`.
+## Fontes de Captura

-## Uso avançado (linha de comando)
+- 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                                             # sobe o servidor
-npm test                                              # roda os testes
+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            # extrai base de outra UF
+node scripts/extrair-base-cnpj.mjs --uf=SP
+node scripts/enviar-outreach.mjs
 ```

-## Estrutura do projeto
+## Estrutura

-```
-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
+```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 com **Node.js 24+** (https://nodejs.org)
- Para extrair novas UFs: `unzip` (vem com o Git para Windows) ou o `tar` nativo do Windows
+- Windows.
+- Node.js 24 ou superior.
+- Para extrair novas UFs, `unzip`, Git Bash ou `tar` nativo do Windows.

-## Log e problemas
+## Seguranca e Dados

- Log do servidor: `data/server.log`
- Se a tela não abrir: rode `node scripts/servidor.mjs` num terminal e veja a mensagem.
+- 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.