Skip to content

Latest commit

 

History

History
261 lines (181 loc) · 11.2 KB

README.md

File metadata and controls

261 lines (181 loc) · 11.2 KB

Automação de Scripts

O que essa ferramenta faz, em resumo

Você tem vários scripts .bat (integrações, backups, processamentos, etc.) que precisam rodar automaticamente: alguns a cada X minutos, outros em horários fixos, outros só dentro de um período do dia.

Em vez de criar uma tarefa separada no Agendador de Tarefas do Windows para cada script (o que vira uma bagunça quando você tem 20, 50, 100 integrações), você cria uma única tarefa no Windows, que roda a cada 1 minuto e chama este programa. Este programa então olha um arquivo de configuração (config.ini) e decide, a cada minuto, quais scripts realmente precisam rodar naquele momento.

Resumindo o fluxo:

Windows (a cada 1 minuto)
        │
        ▼
  este programa
        │
        ├── verifica config.ini
        ├── decide o que precisa rodar agora
        ├── roda os scripts necessários
        └── anota no log o que aconteceu

Você só mexe em duas coisas no dia a dia: a pasta scripts (onde ficam os .bat) e o arquivo config/config.ini (onde você diz quando cada um deve rodar).


Antes de começar: o que precisa estar instalado

  • Windows (é para isso que a ferramenta foi feita)
  • Python 3.11 ou mais novo instalado no computador/servidor
  • Permissão para criar e rodar arquivos .bat na máquina

Se você não sabe se o Python está instalado, abra o Prompt de Comando (pesquise "cmd" no menu Iniciar) e digite:

python --version

Se aparecer um número de versão (ex: Python 3.12.4), está tudo certo. Se der erro, é preciso instalar o Python antes (baixe em python.org e, na instalação, marque a opção "Add python.exe to PATH").

Esta ferramenta não precisa de nenhuma instalação extra além do Python em si — nada de bibliotecas, nada de configurar banco de dados, nada disso.


As pastas que você vai usar

AutomacaoScripts/
│
├── scripts/              ← coloque aqui os .bat das suas integrações
├── config/
│   └── config.ini        ← aqui você diz quando cada script deve rodar
├── logs/                 ← aqui aparecem os registros do que rodou, com sucesso ou erro
│
├── state/                ← pastas internas de controle, não precisa mexer aqui
├── main.py                ← o "botão de ligar" do sistema
└── (outras pastas internas do programa, também não precisam de atenção)

Você só precisa se preocupar com scripts/, config/config.ini e logs/. O resto é "maquinário interno" que o programa cuida sozinho.


Passo 1 — Colocar seus scripts na pasta certa

Copie todos os arquivos .bat das suas integrações para dentro da pasta scripts/.

Exemplo: se você tem um script que faz backup, o arquivo backup.bat deve estar em:

AutomacaoScripts\scripts\backup.bat

Passo 2 — Dizer quando cada script deve rodar

Abra o arquivo config/config.ini com o Bloco de Notas (ou qualquer editor de texto simples). Ele tem duas partes: [FAIXAS] e [TAREFAS].

A parte [TAREFAS] — a mais importante

É aqui que você lista os scripts e diz a regra de horário de cada um. Existem 3 jeitos de configurar:

1. A cada X minutos, o dia todo

processamento.bat=10

Isso roda processamento.bat a cada 10 minutos, o tempo todo, sem parar.

2. Em horários fixos do dia

backup.bat=08:00,12:00,18:00

Isso roda backup.bat exatamente às 8h, ao meio-dia e às 18h. Cada horário só dispara uma vez por dia — não tem risco de rodar duas vezes seguidas.

3. A cada X minutos, mas só dentro de um período do dia

Primeiro você define o período (a "faixa") lá em cima, na seção [FAIXAS]:

[FAIXAS]
comercial=08:00-18:00

E depois usa essa faixa na tarefa:

[TAREFAS]
integracao.bat=FAIXA:comercial|60

Isso roda integracao.bat a cada 60 minutos, mas só entre 8h e 18h. Fora desse período, ele não dispara.

Exemplo de arquivo config.ini completo

[FAIXAS]
comercial=08:00-18:00
manha=08:00-12:00
integral=06:00-22:00
noturno=18:00-23:59

[TAREFAS]
processamento.bat=10
backup.bat=08:00,12:00,18:00
integracao.bat=FAIXA:comercial|60
sincronizacao.bat=FAIXA:manha|10
relatorio.bat=FAIXA:integral|120
notificacao.bat=FAIXA:noturno|30

Dicas importantes:

  • O nome do script na configuração precisa ser idêntico ao nome do arquivo dentro de scripts/ (incluindo o .bat).
  • Cada tarefa fica em uma linha só, no formato nome_do_arquivo.bat=regra.
  • Você pode ter quantas faixas e quantas tarefas quiser.
  • Linhas que começam com ; são apenas comentários (anotações), o programa ignora.

Passo 3 — Testar manualmente antes de automatizar

Antes de deixar o Windows chamando isso sozinho, é bom rodar uma vez à mão para ver se está tudo certo.

Abra o Prompt de Comando, entre na pasta do projeto e rode:

cd C:\AutomacaoScripts
python main.py

(ajuste o caminho C:\AutomacaoScripts para onde você realmente colocou a pasta)

Se não aparecer nenhum erro na tela, deu certo. Para conferir o que aconteceu, olhe a pasta logs/ — vai ter um arquivo chamado algo como execucao_05-09-2026.log com o resumo do que rodou.

Se algum script configurado ainda não devia rodar (porque não chegou o horário/intervalo dele), tudo bem — o programa só vai anotar "nenhum arquivo pendente para execução" e não fará nada, o que é o comportamento esperado.

O que fazer se der erro

Abra o arquivo de log e procure por linhas com a palavra Erro. As mensagens são pensadas para serem entendíveis, por exemplo:

  • Arquivo não encontrado: ... → o nome do script no config.ini não bate com o nome do arquivo dentro de scripts/. Confira se está escrito exatamente igual, com a extensão .bat.
  • Faixa 'X' não encontrada → você usou FAIXA:X|... numa tarefa, mas não existe uma faixa chamada X lá em cima, em [FAIXAS]. Confira o nome.
  • Intervalo inválido → o número depois do = (ou depois do |) precisa ser maior que zero.

Passo 4 — Automatizar com o Agendador de Tarefas do Windows

Agora que testou manualmente e funcionou, vamos fazer o Windows chamar isso sozinho, a cada minuto, para sempre.

  1. Aperte Win + R, digite taskschd.msc e aperte Enter (isso abre o Agendador de Tarefas do Windows).
  2. No menu da direita, clique em "Criar Tarefa..." (não use "Criar Tarefa Básica", pois ela tem menos opções).
  3. Na aba Geral:
    • Dê um nome, por exemplo: Automacao de Scripts
    • Marque "Executar estando o usuário conectado ou não"
    • Marque "Executar com privilégios mais altos"
  4. Na aba Disparadores, clique em "Novo...":
    • Em "Iniciar a tarefa", escolha "Diariamente"
    • Marque a caixa "Repetir a tarefa a cada" e escolha 1 minuto
    • Em "durante", escolha "Indefinidamente"
    • Clique OK
  5. Na aba Ações, clique em "Novo...":
    • Em "Programa/script", coloque o caminho completo do Python. Se você criou um ambiente virtual (pasta .venv), use:
      C:\AutomacaoScripts\.venv\Scripts\python.exe
      
      Se não usou ambiente virtual, pode usar só python.exe ou o caminho que apareceu quando você rodou python --version.
    • Em "Adicionar argumentos", coloque:
      main.py
      
    • Em "Iniciar em", coloque:
      C:\AutomacaoScripts
      
    • Clique OK
  6. Na aba Configurações, marque "Não iniciar uma nova instância se outra já estiver em execução" (proteção extra — o programa já se protege sozinho disso, mas não custa reforçar).
  7. Clique OK para salvar a tarefa. O Windows pode pedir a senha do usuário — digite e confirme.

Pronto. A partir de agora, a cada minuto o Windows vai chamar o programa, e ele decide sozinho o que precisa rodar, sem você precisar fazer mais nada.

Como confirmar que está funcionando de verdade

Espere alguns minutos e olhe a pasta logs/. Se o arquivo de log estiver sendo atualizado com novas linhas a cada minuto (mesmo que só dizendo "nenhum arquivo pendente"), a automação está rodando. Quando chegar a hora de algum script configurado, vai aparecer uma linha de EXECUÇÃO no log, com sucesso ou erro.


Onde olhar quando algo não funciona como esperado

Tudo o que acontece fica registrado na pasta logs/, separado por dia:

  • execucao_DD-MM-AAAA.log — resumo geral de tudo que rodou naquele dia (sucessos e erros)
  • erros_DD-MM-AAAA.log — só as linhas de erro, para você achar problemas mais rápido

Se um script demorar demais para terminar (por exemplo, travou esperando alguma integração externa), o programa não fica preso esperando para sempre: depois de 15 minutos ele segue em frente e continua verificando os outros scripts, e só registra o resultado daquele script mais lento quando ele finalmente terminar, no próximo ciclo. Isso é intencional — evita que um script travado pare tudo o resto.

Se um script ficar rodando por mais de 24 horas sem terminar, o programa assume que algo travou de vez, libera o bloqueio dele automaticamente (para permitir novas tentativas) e avisa no log de erro para você investigar manualmente.


Perguntas frequentes

Preciso reiniciar alguma coisa quando eu editar o config.ini? Não. Toda vez que o programa roda (a cada minuto), ele lê o arquivo de novo. Basta salvar e esperar o próximo minuto.

Posso adicionar ou remover scripts a qualquer momento? Sim. Basta colocar/tirar o arquivo .bat da pasta scripts/ e ajustar a linha correspondente no config.ini.

E se eu esquecer de colocar um script que está no config.ini dentro da pasta scripts/? O programa vai anotar um erro no log (Arquivo não encontrado) e simplesmente ignorar aquela tarefa até você corrigir — não trava o resto.

O que significa "IGNORADO (já em execução)" no log? Significa que aquele script já estava rodando (a execução anterior ainda não tinha terminado) quando chegou a hora da próxima. O programa não roda duas cópias do mesmo script ao mesmo tempo — ele espera a atual terminar.

Os logs antigos ficam se acumulando para sempre? Não, logs com mais de 60 dias são apagados automaticamente.


Para quem quiser entender por dentro (opcional, não é necessário para usar)

O projeto é escrito em Python puro, sem dependências externas. A pasta app/ contém o código do programa, organizado assim:

Arquivo/pasta Responsabilidade
scheduler.py Orquestra cada ciclo: verifica o que precisa rodar, dispara, aguarda e registra o resultado
config_loader.py Lê e valida o config.ini
task_factory.py Interpreta a regra de cada tarefa (intervalo, horário fixo ou faixa)
tasks/ As três formas de agendamento (intervalo, horário fixo, faixa + intervalo)
job.py Dispara e monitora a execução de um script
state_manager.py Guarda a última execução de cada tarefa (state/estado.ini)
pending_jobs_manager.py Controla scripts que demoraram demais e ficaram pendentes (state/pendentes.json)
logger.py Escreve os arquivos de log
constants.py Todos os valores fixos e configuráveis do sistema (pastas, nomes de arquivo, tempos, textos de log, expressões regulares)

|