# 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

```ini
# 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)`:

```python
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`)

```python
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)

```python
# 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)

```python
# 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

```python
(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`:

```bash
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 |