# 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úmeros que aparecem em mais de um lead (ex.: contabilidade que registra o próprio telefone para clientes) ficam bloqueados para envio automático e manual até você revisar e liberar em **Configurações**. - 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.