# Preparação dos dados — passo a passo

## Parte A — 2022

O histórico de 2022 é gerado uma vez e depois fica estático no site.

### 1. Instale Python 3.11+

No terminal, dentro da pasta do projeto:

```bash
python -m venv .venv
```

Ative o ambiente e instale:

```bash
pip install -r tools/requirements-prep.txt
```

### 2. Gere os limites dos bairros

```bash
python tools/preparar_geometria.py --uf CE
```

Esse comando baixa a malha oficial de bairros do IBGE e cria arquivos em:

```text
data/geometries/CE/<municipio>.geojson
```

Também cria `data/index/CE.json`.

### 3. Gere a apuração histórica por bairro

Presidente, primeiro turno:

```bash
python tools/preparar_2022.py --uf CE --turno 1 --cargo 1 --fotos
```

Governador:

```bash
python tools/preparar_2022.py --uf CE --turno 1 --cargo 3 --fotos
```

Senador:

```bash
python tools/preparar_2022.py --uf CE --turno 1 --cargo 5 --fotos
```

Deputado Federal:

```bash
python tools/preparar_2022.py --uf CE --turno 1 --cargo 6 --fotos
```

Deputado Estadual:

```bash
python tools/preparar_2022.py --uf CE --turno 1 --cargo 7 --fotos
```

O processamento pode demorar porque os arquivos oficiais por seção são grandes. O script usa cache em `.cache/`, então downloads já concluídos não são repetidos.


### Atalho para preparar todos os cargos de 2022

Depois da malha, você pode gerar de uma vez Presidente, Governador, Senador, Deputado Federal e Deputado Estadual/Distrital do 1º turno:

```bash
python tools/preparar_lote_2022.py --uf CE --fotos
```

Para apenas um município e também Presidente/Governador do 2º turno:

```bash
python tools/preparar_lote_2022.py --uf CE --municipio "Fortaleza" --fotos --segundo-turno
```

## Parte B — 2026 ao vivo

### 1. Gere a relação das seções com os bairros

```bash
python tools/preparar_mapeamento_2026.py --uf CE --municipio "Morada Nova"
```

Troque o município conforme necessário.

### 2. Baixe a especificação oficial do BU

```bash
pip install -r collector/requirements.txt
python collector/setup_formato_urna.py
```

O utilitário procura, na página Eleições 2026 do TSE, o pacote “Formato dos arquivos de BU, RDV e assinatura digital” e extrai a ASN.1 usada pelo coletor.

### 3. Configure o simulado

```bash
copy collector\\config.simulado.example.json collector\\config.json
```

No Linux/macOS:

```bash
cp collector/config.simulado.example.json collector/config.json
```

Edite `uf`, a lista `municipalities` e a lista `cargos`. Para preparar todos os municípios já mapeados de uma UF, use `"municipalities": ["*"]`.

### 4. Rode o coletor

```bash
python collector/coletor_2026.py --config collector/config.json --loop
```

A cada ciclo, ele consulta primeiro o EA16 da UF. Somente para seções principais cujo EA16 indique que o arquivo auxiliar já foi gerado (`da`/`ha`), consulta o EA18, baixa e decodifica o BU e agrega os votos. Isso evita sondar milhares de URLs inexistentes e reduz o risco de 404/bloqueio.

### 5. Publicação ao vivo em Cloudflare KV

No painel Cloudflare, crie um namespace KV. No projeto Pages, adicione o binding:

```text
BAIRRO_RESULTS
```

No computador do coletor, defina as variáveis:

```text
CLOUDFLARE_API_TOKEN
CLOUDFLARE_ACCOUNT_ID
CLOUDFLARE_KV_NAMESPACE_ID
```

O endpoint `functions/api/bairros.js` lê o agregado correspondente a ano, turno, cargo, UF e município.

## O que acontece quando uma seção nova chega

```text
EA16 indica chegada do arquivo auxiliar (`da`/`ha`)
       ↓
coletor consulta o EA18 somente da seção disponível
       ↓
coletor identifica o hash mais recente
       ↓
baixa o BU daquela seção
       ↓
decodifica votos do cargo selecionado
       ↓
consulta zona+seção → bairro
       ↓
soma ao bairro
       ↓
publica JSON compacto
       ↓
site atualiza a cor do bairro e o placar A × B
```

## Município sem bairro na base IBGE

Isso não é um erro do site. Se a base de bairros do IBGE não trouxer aquele município, obtenha uma malha oficial municipal. Converta para GeoJSON EPSG:4326 e use propriedades:

```json
{
  "bairro_id": "identificador",
  "bairro": "Nome do bairro",
  "municipio": "Nome do município"
}
```

Salve como:

```text
data/geometries/UF/slug-do-municipio.geojson
```