Gustavo
d330bb5ff0
Tracks the app that was already in place (capture, treatment, outreach, WhatsApp integration, server, frontend, tests, docs) so future feature work can branch and use isolated worktrees.
97 lines
6.0 KiB
Markdown
97 lines
6.0 KiB
Markdown
# Máquina Comercial Pessoal
|
|
|
|
Aplicação local para uma pessoa capturar, qualificar, tratar, exportar e contatar leads. Os dados ficam em SQLite no próprio computador e o WhatsApp funciona por uma sessão de dispositivo vinculado.
|
|
|
|
## Instalação e acesso
|
|
|
|
Requisitos: Node.js 24 ou superior e npm.
|
|
|
|
```powershell
|
|
npm install
|
|
npm start
|
|
```
|
|
|
|
Abra `http://127.0.0.1:3910`. O acesso inicial é `admin` / `admin`; abra **Configurações > Alterar minha senha**, informe `admin` como senha atual e defina uma nova senha com ao menos 8 caracteres. Essa opção está disponível para qualquer usuário autenticado. No Windows também é possível executar `INICIAR-MAQUINA-PESSOAL.bat` ou gerar o launcher com `npm run build:launcher`.
|
|
|
|
Variáveis opcionais ficam em `.env`. Consulte `.env.example`. A porta padrão é `3910` e pode ser alterada com `APP_PORT`.
|
|
|
|
## Fluxo operacional
|
|
|
|
1. Em **Capturar Leads**, escolha UF, cidades, nichos e fontes.
|
|
2. Execute a captura e acompanhe o progresso.
|
|
3. Em **Tratar Leads**, filtre e priorize a base.
|
|
4. Use a ação de WhatsApp na primeira coluna para abrir o envio manual já preenchido com o lead real.
|
|
5. Exporte o filtro atual em CSV e XLS quando precisar trabalhar fora da aplicação.
|
|
|
|
## Conexão WhatsApp
|
|
|
|
1. Abra **Configurações** como administrador.
|
|
2. Clique em **Conectar / gerar QR**.
|
|
3. No celular, abra **WhatsApp > Dispositivos conectados > Conectar dispositivo**.
|
|
4. Leia o QR exibido na aplicação e aguarde o estado **Conectado**.
|
|
|
|
Os estados da conexão incluem parado, iniciando, QR necessário, autenticando, conectado, reconectando, desconectado e erro. **Desconectar** interrompe a conexão preservando a sessão. **Sair e esquecer sessão** remove o vínculo local e exigirá um novo QR.
|
|
|
|
O envio manual exige número com DDI e DDD, cadastro ativo desse número no WhatsApp, mensagem revisada e conexão pronta. O histórico distingue aceite local, confirmação do servidor, entrega e leitura; "aceito" ainda não significa que a mensagem foi entregue.
|
|
|
|
## Automação e segurança comercial
|
|
|
|
- A automação inicia desligada e deve ser ativada conscientemente pelo administrador.
|
|
- Configure um limite diário baixo e mantenha os intervalos de envio.
|
|
- Faça contato apenas em horários adequados e com uma finalidade legítima.
|
|
- Adicione imediatamente à lista de bloqueio quem pedir para não receber mensagens.
|
|
- Não faça spam, disparos indiscriminados nem compre listas de contatos.
|
|
- A conexão usa integração não oficial por dispositivo vinculado. Mudanças no WhatsApp podem interromper o funcionamento e uso abusivo pode causar bloqueio da conta.
|
|
|
|
Templates automáticos são simples: serviço, mensagem e estado ativo. O catálogo inicial usa o serviço neutro **Meu serviço**; adapte sua oferta no mecanismo de configuração de serviços antes de ativar automações.
|
|
|
|
## Dados locais
|
|
|
|
O banco, exportações, logs e autenticação do WhatsApp ficam em `data/`. A sessão vinculada fica em `data/runtime/whatsapp-auth`. Toda essa pasta é ignorada pelo Git.
|
|
|
|
Faça backup do banco indicado por `APP_DB_PATH` antes de manutenção ou migração. Nunca compartilhe `.env`, banco, logs ou a pasta de autenticação.
|
|
|
|
## Comandos
|
|
|
|
```powershell
|
|
npm start # servidor local
|
|
npm test # suíte automatizada
|
|
npm run capture # captura por linha de comando
|
|
npm run download-rfb # baixa/retoma os 21 ZIPs necessarios (~6 GB)
|
|
npm run extract -- --uf=BA # baixa o que faltar e extrai a base CNPJ da UF
|
|
npm run recalc-scores # recalcula os scores
|
|
npm run outreach # executa automação, quando habilitada
|
|
npm run build:launcher # gera o launcher Windows
|
|
```
|
|
|
|
O botão **Baixar e extrair base** faz o mesmo fluxo em um clique. O downloader escolhe o snapshot público mais recente, mantém arquivos `.part` para retomada e valida tamanho e estrutura EOCD/diretório central dos ZIPs antes da extração. Um snapshot novo exige por padrão 8 GiB livres; ao retomar o mesmo snapshot, ZIPs finais confirmados e `.part` com metadata reduzem esse requisito, preservando uma margem mínima de 2 GiB para extração. O conjunto completo anterior fica em `.rfb-backup` até o novo snapshot ser validado. Se o índice ficar offline com o conjunto atual incompleto, o backup é validado e restaurado; finals e manifesto incompletos são movidos para `.rfb-incomplete*`, e `.part` permanece disponível quando a restauração não troca de snapshot. Para extrair somente com os arquivos locais já completos, use `npm run extract -- --uf=BA --no-download`.
|
|
|
|
## Estrutura
|
|
|
|
```text
|
|
public/ interface web
|
|
prospeccao/config.json nichos e serviço neutro inicial
|
|
scripts/ comandos operacionais e build do launcher
|
|
src/capture/ captura de leads
|
|
src/treatment/ consultas e dashboard
|
|
src/outreach/ templates, limites e automação
|
|
src/whatsapp/ sessão local e envio
|
|
src/server/ servidor, autenticação e rotas
|
|
launcher/ launcher Windows
|
|
data/ banco e estado local ignorados
|
|
```
|
|
|
|
## Solução de problemas
|
|
|
|
- **A tela não abre:** confirme `npm install`, rode `npm start` e acesse `http://127.0.0.1:3910`.
|
|
- **Porta ocupada:** defina outra `APP_PORT` no `.env` e reinicie.
|
|
- **QR não aparece:** clique em **Conectar / gerar QR**. Se o QR expirou ou a tentativa ficou presa, **Atualizar QR** reinicia o pareamento e solicita um QR novo.
|
|
- **WhatsApp desconectado:** tente conectar novamente. Se a sessão estiver inválida, use **Sair e esquecer sessão** e vincule de novo.
|
|
- **Mensagem recusada:** confira conexão, número com DDI/DDD, limite diário e lista de bloqueio.
|
|
- **Captura sem resultados:** confirme a base CNPJ da UF, as fontes escolhidas e `GOOGLE_PLACES_API_KEY` caso use Google Places.
|
|
- **Launcher não compila:** instale o .NET SDK ou execute a aplicação diretamente com `npm start`.
|
|
|
|
## Boas práticas
|
|
|
|
Mantenha o servidor em `127.0.0.1`, use senhas individuais, preserve a automação desligada até revisar templates e limites, e respeite privacidade, consentimento e pedidos de opt-out.
|