AutoTigrinho/RULES.md

RULES.md — Regras de Desenvolvimento do AutoTigrinho

Este documento define as regras que qualquer agente de IA ou desenvolvedor deve seguir ao modificar, estender ou corrigir este sistema. Violar estas regras pode quebrar funcionalidades existentes.

---

1. Estrutura do Projeto

AutoTigrinho/app/
├── main.py               # Código principal — todo o loop e lógica
├── iniciar.sh            # Launcher — setup de venv, deps e Xvfb
├── .env                  # Configurações — NÃO hardcodificar valores aqui
├── requirements.txt      # Dependências Python — sempre usar --upgrade --force-reinstall
├── botaoparaclicar.png   # Template de imagem para detecção
├── log.txt               # Log de execução — gerado em runtime
├── venv/                 # Ambiente virtual Python — recriado em outra máquina
└── bin/                  # Xvfb local para modo headless — gerado automaticamente

Regra: todos os arquivos acima devem permanecer na raiz do projeto. Não criar pastas adicionais sem motivo explícito.

---

2. Ordenação e Organização de Código em main.py

O arquivo main.py não deve ser reestruturado livremente. A ordem das seções é:

1. Shebang + docstring (linhas 1-6)
2. Imports (linhas 8-17) — stdlib primeiro, terceiros depois
3. load_dotenv() (linha 19)
4. Constantes carregadas do .env (linhas 21-31)
5. Função _carregar_periodos() + PERIODOS_SESSAO (linhas 34-43)
6. Funções utilitárias (dentro_horario, encontrar_botao, gerar_intervalo_aleatorio)
7. Funções de UI (vis_largura, terminal_width, largura, center, banner, painel_config, cabecalho_sessao, rodape_clique, log)
8. Função main()
9. if __name__ == "__main__": main()

Regra: nunca remover ou reordenar as constantes do .env da seção 4. Sempre adicionar novas constantes nessa mesma seção, mantendo a ordem lógica (intervalos, limites, detectores).

---

3. Variáveis de Ambiente — Regras Obrigatórias

Todas as configurações devem ser lidas via os.getenv() e devem ter um valor padrão sensato. Nunca hardcodificar valores de configuração diretamente no código.

Nomenclatura das variáveis

INTERVALO_*    → valores em SEGUNDOS (int)
MAXIMO_*       → valores limites inteiros (int)
CONFIANCA      → valor float entre 0.0 e 1.0
PERIODO_N_*    → strings no formato "HH:MM" ou vazias

Formato dos períodos

# Correto: range completo dentro de um dia
PERIODO_1_INICIO=09:00
PERIODO_1_FIM=12:00

# Correto: períodos que cruzam meia-noite NÃO são suportados
# PERIODO_X_INICIO=23:00  ← PERIODO_X_FIM=01:00  NÃO FUNCIONA

# Correto: desativar um período deixando campos vazios
PERIODO_3_INICIO=
PERIODO_3_FIM=

Regra: períodos que cruzam meia-noite não são suportados pela lógica atual de datetime.strptime().time(). Se necessário implementar, modificar dentro_horario() com lógica de comparação de datetime completo (não só .time()).

Padrão ao adicionar nova variável de ambiente

1. Adicionar linha no .env com valor padrão e comentário opcional
2. Adicionar constante no topo de main.py seção 4: NOME = tipo(os.getenv("NOME", "default"))
3. Adicionar entrada em painel_config() para exibir no painel inicial
4. Usar a constante, nunca os.getenv() diretamente em outros pontos

---

4. Fluxo de Execução — Ordem de Verificações

O loop while True em main() (linha 240) segue esta ordem estrita:

while True:
    1. Verificar dentro_horario(PERIODOS_SESSAO)
       └─ FORA dos períodos  →  clique global + continue
       └─ DENTRO dos períodos → prossegue para 2

    2. Verificar primeiro_clique
       └─ True  →  dorme INTERVALO_PRIMEIRO_CLIQUE, depois False

    3. Chamar encontrar_botao()
       └─ ENCONTROU  →  pyautogui.click(), incrementa contadores, falhas=0
       └─ NÃO ENCONTROU  →  incrementa falhas, dorme INTERVALO_MINIMO_CLIQUE, continue (re-tenta)

    4. Verificar MAXIMO_CLIQUES_POR_SESSAO
       └─ Atingido  →  finaliza sessão, loop de espera com clique global, depois continue

    5. Dorme intervalo aleatório (INTERVALO_MINIMO_CLIQUE ~ INTERVALO_MAXIMO_CLIQUE)

Regra: NÃO alterar esta ordem sem justificativa explícita do usuário. O continue em cada branch é intencional para reiniciar o ciclo de verificações.

---

5. Regras de Logging

Todas as mensagens devem passar pela função log(mensagem, cor):

log("mensagem aqui", COR)

Cores disponíveis

Constante	Cor	Uso recomendado
C_GREEN	Verde	Sucesso, clique executado
C_GREEN + BOLD	Verde negrito	Contador de cliques
C_RED	Vermelho	Erros, botão não encontrado
C_RED + BOLD	Vermelho negrito	Erros críticos, encerramento
C_YELLOW	Amarelo	Avisos, fora de período
C_CYAN	Ciano	Esperas, ciclos
C_GRAY	Cinza	Timestamps e esperas longas
C_MAG	Magenta	Sessões
C_WHITE	Branco	Valores, títulos
C_TITLE	Ciano claro	Banner e títulos de seção

Prefixos de log

Prefixo	Quando usar
[Sessão N]	Qualquer evento durante uma sessão ativa
[Espera]	Cliques de keep-alive (fora de período ou entre sessões)
Sem prefixo	Eventos globais (inicialização, encerramento)

Regra: nunca usar print() diretamente para mensagens de evento — sempre use log(). O print() só deve ser usado para banner(), painel_config(), cabecalho_sessao(), rodape_clique() e mensagens de KeyboardInterrupt.

Formato do arquivo log.txt

O arquivo é escrito com f.write() dentro de log(). Sem ANSI codes, com timestamp completo YYYY-MM-DD HH:MM:SS.

Regra: não alterar o formato de escrita do log.txt sem atualizar o README.

---

6. Regras de Detecção de Botão (encontrar_botao)

def encontrar_botao(imagem_path: str, confianca: float = 0.8):

• Usa OpenCV cv2.matchTemplate com método TM_CCOEFF_NORMED
• Suporta PNG com canal alpha (transparência) — o alpha é convertido em máscara
• Retorna (centro_x, centro_y) se max_val >= confianca, senão None
• O centro é calculado como max_loc + (w//2, h//2) — não usar max_loc diretamente
• A screenshot é convertida de RGB (PIL) → BGR (OpenCV) via cv2.cvtColor(screenshot_np, cv2.COLOR_RGB2BGR)

Regra: não alterar o método de template matching, a lógica de máscara alpha ou o cálculo do centro sem motivo explícito.

---

7. Regras de Sessão

Estados da variável numero_sessao

• Inicia em 1
• Incrementado apenas no bloco de finalização de sessão (linha 309)
• Usado em todos os logs de sessão

Estados de cliques_na_sessao

• Inicia em 0
• Incrementado apenas em pyautogui.click() bem-sucedido (linha 283)
• Resetado para 0 ao finalizar sessão e ao sair dos períodos

Estados de falhas_consecutivas

• Incrementado quando encontrar_botao() retorna None (linha 291)
• Resetado para 0 a cada clique bem-sucedido E ao sair dos períodos
• NÃO causa mais encerramento automático — o sistema re-tenta indefinidamente

---

8. Regras de Clique Global / Keep-Alive

O clique global é executado em dois pontos distintos do código:

Ponto A — Fora dos períodos (linhas 248-259)

# dorme INTERVALO_CLIQUE_GLOBAL, depois tenta detectar e clicar
time.sleep(INTERVALO_CLIQUE_GLOBAL)
pos_global = encontrar_botao(IMAGEM_BOTAO, CONFIANCA)
if pos_global:
    pyautogui.click(gx, gy)

Ponto B — Entre sessões (linhas 316-339)

# loop while que divide o INTERVALO_ENTRE_SESSOES em ciclos de INTERVALO_CLIQUE_GLOBAL
while tempo_restante > 0:
    tempo_ate_clique = min(tempo_restante, INTERVALO_CLIQUE_GLOBAL)
    time.sleep(tempo_ate_clique)
    # ... tenta detectar e clicar

Regra: o intervalo de keep-alive é sempre INTERVALO_CLIQUE_GLOBAL. O nome INTERVALO_CLIQUE_ESPERA está obsoleto — não reintroduzi-lo.

---

9. Regras de Interface Terminal

Funções de UI existentes

Função	Propósito
banner()	Cabeçalho inicial
painel_config()	Painel de configuração — adicionar entradas aqui se nova variável
cabecalho_sessao(num)	Cabeçalho de sessão
rodape_clique()	Barra de progresso visual pós-clique
center(text, pre, pos)	Centraliza texto com prefixo/sufixo cor

Adicionar nova entrada no painel

(COR,   "Label da configuração",   f"{CONSTANTE}s"),  # note a vírgula final

Inserir no dicionário itens dentro de painel_config(), mantendo a ordem lógica.

Adicionar nova lista abaixo do painel

Se houver dados adicionais para exibir (como os períodos), adicionar após o loop de renderização de itens e antes de def cabecalho_sessao().

---

10. Regras do iniciar.sh

• Usa set -e — qualquer comando que falhar encerra o script
• Ordem das etapas: Python check → venv → activate → pip upgrade → .env check → imagem check → deps → Xvfb → run
• NÃO modificar a lógica de setup do Xvfb — a extração do .deb é frágil e específica de Debian/Ubuntu
• Se o .env não existir, o script cria um .env mínimo e sai com erro — não prossegue
• requirements.txt é sempre reinstalado com --force-reinstall para evitar erros de arquitetura

---

11. Regras para Modificações

✅ Sempre permitido

• Adicionar novas variáveis de configuração no .env e main.py
• Adicionar novas entradas no painel_config()
• Adicionar novas mensagens de log seguindo o padrão existente
• Ajustar valores padrão de constantes
• Adicionar novos períodos no .env (até 10)

⚠️ Permitido com cuidado

• Modificar dentro_horario() — testar períodos que cruzam meia-noite
• Modificar a lógica de keep-alive — manter INTERVALO_CLIQUE_GLOBAL como intervalo base
• Ajustar CONFIANCA — valores muito baixos geram falsos positivos

❌ Nunca fazer

• Remover pyautogui.FAILSAFE = True
• Remover _RE_ANSI e a remoção de ANSI do log.txt
• Remover try/except no log() — o log deve nunca crashar o programa
• Remover o continue nos branches do loop principal — quebra o fluxo
• Remover o time.sleep(INTERVALO_MINIMO_CLIQUE) no branch de botão não encontrado — causa CPU 100%
• Alterar o método de template matching sem discussão explícita
• Introduzir dependências novas sem atualizar requirements.txt
• Mudar a ordem das seções de main.py
• Adicionar sys.exit() ou raise em pontos que não sejam o topo do main()

🔴 Requer aprovação explícita do usuário

• Qualquer mudança que altere o fluxo de sessões
• Qualquer remoção ou substituição de funcionalidade existente
• Qualquer alteração em iniciar.sh

---

12. Padrão para Adicionar Nova Funcionalidade

1. Adicionar variável no .env com valor padrão e comentário
2. Adicionar constante em main.py seção 4
3. Adicionar entrada em painel_config()
4. Implementar lógica no main()
5. Adicionar logs apropriados com cores corretas
6. Atualizar README.md com a nova configuração/funcionalidade
7. Verificar sintaxe: python3 -m py_compile main.py

---

13. Regras de Teste e Verificação

Após qualquer modificação em main.py:

python3 -m py_compile main.py    # deve retornar "Syntax OK"

Verificar também:

• Nenhuma referência a constantes removidas
• Nenhuma duplicação de código (especialmente CONFIANCA, IMAGEM_BOTAO, LOG_FILE)
• PERIODOS_SESSAO é carregado uma única vez no topo do arquivo

---

14. Glossário de Termos

Termo	Significado no código
Sessão	Bloco de cliques consecutivos até MAXIMO_CLIQUES_POR_SESSAO
Keep-alive	Clique de manutenção executado fora de sessão ativa
Período	Faixa de horário (HH:MM → HH:MM) em que sessões são permitidas
Fora do período	Momento em que o sistema só executa cliques globais, não sessões
Clique global	Clique de keep-alive executado a cada INTERVALO_CLIQUE_GLOBAL segundos em qualquer estado
Template matching	Algoritmo OpenCV que busca a imagem botaoparaclicar.png na tela
Confiança	Threshold de correspondência (0.0 a 1.0) para aceitar uma detecção
Failsafe	pyautogui.FAILSAFE = True — mover mouse no canto aborta o programa