docs: add README and RULES documentation files

Add comprehensive project documentation including README.md with installation instructions, configuration reference, and usage guide. Add RULES.md defining development standards, code organization requirements, and environment variable conventions for contributors.
2026-09-09 13:56:23 -03:00
parent 8c4b3d9701
commit b375120fb2
2 changed files with 476 additions and 0 deletions
@@ -0,0 +1,146 @@
+# AutoTigrinho 🤖
+
+Sistema de cliques automáticos baseado em **reconhecimento de imagem**. O bot detecta visualmente um botão na tela e clica nele em intervalos configuráveis, respeitando horários e períodos definidos pelo usuário.
+
+---
+
+## Requisitos
+
+- Python 3.10+
+- Ambiente gráfico (DISPLAY) — em servidores headless o script usa Xvfb automaticamente
+
+---
+
+## Instalação
+
+```bash
+./iniciar.sh
+```
+
+O `iniciar.sh` executa automaticamente:
+
+1. Verifica/cria o ambiente virtual (`venv/`)
+2. Instala/atualiza as dependências do `requirements.txt`
+3. Verifica a existência do `.env` e da imagem do botão
+4. Configura Xvfb se não houver ambiente gráfico
+5. Inicia o programa
+
+---
+
+## Configuração
+
+Edite o arquivo `.env` para ajustar o comportamento:
+
+### Intervalos de clique
+
+| Variável | Descrição | Padrão |
+|---|---|---|
+| `INTERVALO_MINIMO_CLIQUE` | Tempo mínimo entre cliques durante uma sessão (s) | `10` |
+| `INTERVALO_MAXIMO_CLIQUE` | Tempo máximo entre cliques durante uma sessão (s) | `30` |
+| `INTERVALO_PRIMEIRO_CLIQUE` | Espera antes do primeiro clique de uma sessão (s) | `10` |
+| `INTERVALO_ENTRE_SESSOES` | Tempo de espera entre o fim de uma sessão e o início da próxima (s) | `60` |
+| `INTERVALO_CLIQUE_GLOBAL` | Intervalo para clique de keep-alive em qualquer estado (s) | `900` (15 min) |
+
+### Controle de sessões
+
+| Variável | Descrição | Padrão |
+|---|---|---|
+| `MAXIMO_CLIQUES_POR_SESSAO` | Número de cliques por sessão antes da pausa | `20` |
+| `MAXIMO_FALHAS` | Limite de falhas de detecção antes de encerrar | `5` |
+| `CONFIANCA` | Confiança mínima da correspondência de imagem (0.0 a 1.0) | `0.8` |
+
+### Períodos de funcionamento
+
+Até **10 períodos** podem ser configurados. Fora desses intervalos o sistema permanece ativo mas **não executa sessões**, apenas cliques de keep-alive.
+
+```ini
+PERIODO_1_INICIO=09:00
+PERIODO_1_FIM=12:00
+
+PERIODO_2_INICIO=14:00
+PERIODO_2_FIM=18:00
+
+PERIODO_3_INICIO=    ← deixe vazio para desativar
+PERIODO_3_FIM=
+```
+
+### Aparência
+
+| Variável | Descrição | Padrão |
+|---|---|---|
+| `LARGURA_TERMINAL` | Largura da interface em caracteres | `60` |
+
+---
+
+## Como funciona
+
+### Sessões
+
+Uma **sessão** é um bloco de até `MAXIMO_CLIQUES_POR_SESSAO` cliques consecutivos. Quando esse limite é atingido:
+
+1. A sessão é finalizada e contabilizada
+2. O sistema entra em modo de espera por `INTERVALO_ENTRE_SESSOES` segundos
+3. A cada `INTERVALO_CLIQUE_GLOBAL` segundos durante essa espera, um **clique de keep-alive** é executado
+4. Ao terminar a espera, uma nova sessão é iniciada automaticamente
+
+### Clique de keep-alive (global)
+
+Independentemente do estado — **dentro ou fora dos períodos**, **durante espera entre sessões** — o sistema executa um clique de manutenção a cada `INTERVALO_CLIQUE_GLOBAL` segundos. Isso evita timeout de sessão em aplicações que exigem atividade contínua.
+
+### Detecção de botão
+
+O sistema usa **OpenCV** com template matching (`TM_CCOEFF_NORMED`) para encontrar a posição do botão na tela. O template deve ser fornecido como `botaoparaclicar.png` na raiz do projeto. Quando o botão não é encontrado, o sistema re-tenta automaticamente a cada `INTERVALO_MINIMO_CLIQUE` segundos até conseguir detectar e clicar.
+
+### Controle de horário
+
+- Dentro de um período configurado → sessões são executadas normalmente
+- Fora de todos os períodos → aguarda `INTERVALO_CLIQUE_GLOBAL` segundos, executa um clique de keep-alive e volta a verificar
+
+### Modo headless (sem DISPLAY)
+
+Em servidores ou máquinas sem ambiente gráfico, o `iniciar.sh` tenta instalar e usar o **Xvfb** (X virtual framebuffer) automaticamente, sem necessidade de sudo.
+
+---
+
+## Estrutura de arquivos
+
+```
+AutoTigrinho/app/
+├── main.py               # Código principal
+├── iniciar.sh            # Script de inicialização e setup
+├── .env                  # Configurações
+├── botaoparaclicar.png   # Imagem do botão (template)
+├── requirements.txt      # Dependências Python
+├── log.txt               # Log de execução
+└── venv/                 # Ambiente virtual Python
+```
+
+---
+
+## Log de execução
+
+Todas as ações são registradas em `log.txt` com timestamp:
+
+```
+[2026-09-09 15:00:00] Sessão 1 iniciada
+[2026-09-09 15:00:10] Clicando em (450, 320)...
+[2026-09-09 15:01:15] Aguardando 15s até o próximo ciclo...
+[2026-09-09 15:05:00] Sessão 1 finalizada: 20 cliques
+[2026-09-09 15:05:00] Aguardando 900s até a Sessão 2...
+[2026-09-09 15:20:00] [Espera] Clicando em (450, 320)...
+```
+
+---
+
+## Interromper
+
+Pressione **CTRL+C** para parar o programa a qualquer momento. O total de cliques realizados é exibido no encerramento.
+
+---
+
+## Dicas
+
+- A imagem `botaoparaclicar.png` deve ser um recorte **apenas do botão**, sem fundo ou com fundo transparente (PNG com canal alpha é suportado)
+- Ajuste `CONFIANCA` conforme necessário: valores mais baixos detectam com menos precisão, valores mais altos exigem correspondência exata
+- Use `INTERVALO_MINIMO_CLIQUE` e `INTERVALO_MAXIMO_CLIQUE` para simular comportamento humano (intervalos aleatórios)
+- O `pyautogui.FAILSAFE` está ativado: mova o mouse para um dos cantos da tela para abortar imediatamente