# Integração: tempo e desastres do Brasil (Defesa Civil SC, INMET, CPTEC, Google, S2ID)

Este guia liga o Nexus às fontes **oficiais e locais** de tempo e desastres, com
**prioridade brasileira**. O destaque é a **Defesa Civil de Santa Catarina**, que tem
estações de sensor perto do condomínio e informa **chuva medida de verdade** e **nível
dos rios** — coisa que previsão nenhuma dá. As outras fontes entram como consenso e
reserva. Tudo é **grátis** (só o Google pede uma chave, opcional).

> **Sem jargão:** "fonte" = de onde o sistema pega o dado do tempo. "Previsão" = o que
> vai acontecer (INMET, CPTEC, Google). "Medição" = o que já está acontecendo agora
> (Defesa Civil SC: choveu X mm, o rio está em Y metros). O Nexus junta as duas.

O que cada fonte entrega:

| Fonte | O que dá | Precisa de chave? |
|---|---|---|
| **Defesa Civil SC** (`dcsc`) | Chuva **medida** + **nível de rio** + temperatura/vento locais | Não |
| **INMET** (`inmet`) | Previsão do município + **avisos oficiais** | Não |
| **CPTEC/INPE** (`cptec`) | Previsão diária (temperatura máx/mín, chuva) | Não |
| **Google Weather** (`google`) | Atual + previsão hora a hora (chuva mm, vento) | Sim (Google) |
| **Open-Meteo** (`open-meteo`) | Atual + previsão hora a hora | Não |
| **OpenWeather** (`openweather`) | Condições atuais | Sim (OpenWeather) |
| **S2ID / Defesa Civil Nacional** (`s2id`) | Se a cidade está em **emergência/calamidade federal** | Não |

---

## Passo 1 — Descobrir os "códigos" da sua cidade

O condomínio fica em **Porto Belo/SC** (ajuste se for outra cidade). Você vai precisar de
até 4 informações. Anote num bloco de notas.

**1.1 Latitude e longitude** (as coordenadas do condomínio)

Abra o Google Maps, clique com o botão direito no condomínio → o primeiro número é a
**latitude**, o segundo é a **longitude**. Ex.: `-26.78` e `-48.67`.

✅ **Deu certo se** você tem dois números, um começando com `-26` e outro com `-48`.

**1.2 Geocode IBGE do município** (um número de 7 dígitos — para o INMET e o S2ID)

Abra no navegador (troque o nome da cidade):

```
https://servicodados.ibge.gov.br/api/v1/localidades/municipios?nome=Porto%20Belo
```

Procure o campo `"id": 4213500`. Esse número é o **geocode**. (Porto Belo = `4213500`.)

✅ **Deu certo se** apareceu um `id` de 7 dígitos começando com `42` (o 42 é SC).

**1.3 Código de cidade do CPTEC** (um número — para o CPTEC)

Abra no navegador (troque o nome):

```
http://servicos.cptec.inpe.br/XML/listaCidades?city=porto+belo
```

Vai aparecer uma lista tipo `<cidade><nome>Porto Belo</nome><uf>SC</uf><id>NNNN</id>`.
Anote o `<id>`.

✅ **Deu certo se** apareceu a sua cidade com um `<id>` numérico.

**1.4 Estação da Defesa Civil SC** (opcional — o sistema acha a mais próxima sozinho)

Não precisa fazer nada: deixando em branco, o Nexus escolhe **a estação mais próxima**
da latitude/longitude do passo 1.1. (Perto de Porto Belo, a mais próxima é a **DCSC-00159,
"Penha"**, a ~3 km, que informa chuva e nível de rio.)

---

## Passo 2 — Ligar as fontes no arquivo `.env`

No servidor, abra o arquivo `api\.env` (Bloco de Notas). Cole o bloco abaixo **trocando
os valores** pelos que você anotou. As linhas que você não tem, deixe em branco.

```ini
WEATHER_ENABLED=true
WEATHER_LAT=-26.78
WEATHER_LON=-48.67
WEATHER_WINDOW_HOURS=6

# Ordem: brasileiras/locais primeiro
WEATHER_PRIORITY=dcsc,s2id,inmet,cptec,google,open-meteo,openweather

# Defesa Civil SC (chuva medida + nível de rio). Estação em branco = mais próxima.
WEATHER_DCSC_ENABLED=true
WEATHER_DCSC_STATION=

# INMET (previsão + avisos oficiais). UF para os avisos.
WEATHER_INMET_GEOCODE=4213500
WEATHER_INMET_UF=SC

# CPTEC/INPE (troque pelo id do passo 1.3)
WEATHER_CPTEC_CIDADE=

# S2ID / Defesa Civil Nacional (emergência/calamidade federal). Ligue se quiser.
WEATHER_S2ID_ENABLED=true

# Google Weather (opcional; deixe em branco se não tiver chave)
GOOGLE_WEATHER_KEY=
```

Salve o arquivo.

✅ **Deu certo se** o arquivo salvou sem erro e o `WEATHER_ENABLED` está `true`.

> **Módulo pode ser desligado a qualquer momento** em **Configurações → Módulos**
> (chave `weather`), sem mexer no `.env`.

---

## Passo 3 — Conferir se está pegando os dados

O tempo é atualizado por uma tarefa automática (`auto_weather`) a cada ~15 minutos. Para
testar na hora, no servidor abra o **Prompt de Comando** e rode:

```
C:\wamp64\bin\php\php8.3.28\php.exe C:\wamp64\www\nexus\api\scripts\auto_weather.php
```

(ajuste o caminho se o seu for diferente).

✅ **Deu certo se** aparecer uma linha tipo `Tempo ok (fonte dcsc+inmet+...); alertas: 0`.

Se você usa o barramento MQTT, o resultado também é publicado em `nexus/weather` (retido),
já com os campos novos: `obs_rain_mm` (chuva medida), `river_level_m` e `river_trend`.

---

## Passo 4 — Criar um alerta de chuva / rio

1. No menu, abra **Alertas** (`/alerts`) → **Nova regra**.
2. Em **Tipo**, escolha **"Previsão do tempo (chuva, vento, temperatura)"**.
3. Preencha só o que quiser vigiar (o resto deixe em branco):
   - **Chuva ≥ (mm na janela)**: dispara com chuva **prevista OU medida**. Ex.: `20`.
   - **Nível do rio ≥ (m)**: usa a estação da Defesa Civil. Ex.: `3.5`.
   - **Rio subindo**: marque para avisar quando o rio estiver subindo.
   - **Aviso oficial**: marque para avisar em aviso do INMET / reconhecimento federal (S2ID).
4. Escolha os **canais** (WhatsApp, push, e-mail…) e salve.
5. Botão **Prévia** mostra se as condições atuais já bateriam.

✅ **Deu certo se** a regra aparece na lista e a Prévia responde sem erro.

---

## Deu problema?

- **"Tempo ok" mas fonte só mostra `open-meteo`.** As brasileiras podem estar sem
  configuração (geocode/cidade em branco) ou fora do ar no momento — o sistema cai para as
  globais automaticamente. Confira os códigos do Passo 1.
- **Nível do rio vem vazio.** A estação mais próxima pode não medir rio (algumas só medem
  chuva). Aumente o alcance com `WEATHER_DCSC_MAX_KM=80` no `.env`, ou fixe uma estação de
  rio em `WEATHER_DCSC_STATION` (veja a lista de estações abaixo).
- **Não chega alerta.** Verifique: a regra está **ativa**? O **kill-switch** de alertas
  (`/alerts` → botão Pausar) está ligado? Os **canais** têm destinatário em Configurações →
  Alertas? A tarefa `auto_weather` está agendada (veja `deploy/INSTALACAO-TAREFAS.md`)?
- **Google Weather não responde.** Precisa de uma chave do Google Maps Platform com a
  **Weather API** ativada e faturamento habilitado. Sem chave, deixe `GOOGLE_WEATHER_KEY`
  em branco — o resto funciona igual.
- **Nada quebra sem essas fontes.** Se todas caírem, o Nexus continua normal; só não
  dispara alerta de tempo. É tudo "best-effort".

---

## Apêndice técnico — engenharia reversa dos endpoints

Registrado aqui para não se perder (fontes públicas, sem chave; **podem mudar sem aviso** —
por isso tudo é best-effort e a URL fica configurável no `.env`).

### A) Defesa Civil SC — `monitoramento.defesacivil.sc.gov.br`

- **GraphQL público**, sem autenticação: `POST https://monitoramento.defesacivil.sc.gov.br/graphql`
  com `Content-Type: application/json`.
- Operação usada: **`Tags_data`** com `tags_data(clients: ["secretaria-de-defesa-civil"])`.
  Retorna ~160 estações (`qualle_meteorologia`), cada uma com:
  - `codigo`, `name.general`, `position { bacia latitude longitude regiao }`, `timestamp`;
  - `data.rio.rio_nivel.value` (m) + `rio_nivel_tendencia.value`;
  - `data.chuva.acumulado.{min005,h001,h003,h006,h012,h024,…}.value` (mm acumulados);
  - `data.temperatura.atual.value`, `data.umidade.atual.value`,
    `data.vento.{velocidade_maxima,velocidade_media,direcao}.value`.
- O Nexus pede uma **query reduzida** (só esses campos), escolhe a estação configurada ou a
  mais próxima e, por sensor, a estação mais próxima que reporta aquele dado.
- Outras operações existentes (não usadas para alerta): `Radares` (imagens de radar em GeoTIFF)
  e `Historic` (série temporal por estação). Provedor: **Qualle** (`tile-service.quallecontrol.com.br`).

### B) INMET — `apiprevmet3.inmet.gov.br`

- Previsão por município: `GET https://apiprevmet3.inmet.gov.br/previsao/{geocodeIBGE}`
  → JSON `{ "{geocode}": { "AAAA-MM-DD": { "manha|tarde|noite": { temp_max, temp_min,
  resumo, int_vento, … } } } }`.
- Avisos oficiais: `GET https://apiprevmet3.inmet.gov.br/avisos/ativos` (filtramos por UF).

### C) CPTEC/INPE — `servicos.cptec.inpe.br`

- Previsão diária: `GET http://servicos.cptec.inpe.br/XML/cidade/{id}/previsao.xml`
  (XML ISO-8859-1) → `<previsao><dia><tempo><maxima><minima><iuv>`.
- Busca de id de cidade: `GET .../XML/listaCidades?city={nome sem acento}`.

### D) Google Weather API — `weather.googleapis.com`

- Atual: `GET /v1/currentConditions:lookup?key=…&location.latitude=…&location.longitude=…&unitsSystem=METRIC`.
- Previsão horária: `GET /v1/forecast/hours:lookup?...&hours=N` → `forecastHours[]` com
  `precipitation.qpf.quantity` (mm), `precipitation.probability.percent`, `wind.speed.value`.

### E) S2ID / Defesa Civil Nacional — `s2id.mi.gov.br`

- Reconhecimentos federais (SE/ECP): `GET https://s2id.mi.gov.br/rest/portal/reconhecimentos`
  → GeoJSON `features[].properties { protocolo, uf, geocodigo, municipio, cobrade, resiliente }`.
  O `protocolo` termina em `AAAAMMDD` (data do reconhecimento). Filtramos pelo `geocodigo` do
  município e ignoramos reconhecimentos antigos (`WEATHER_S2ID_MAX_DIAS`).
- Tabela de códigos de desastre: `GET https://s2id.mi.gov.br/rest/cobrades`.
- Resumo por estado: `GET https://s2id.mi.gov.br/rest/portal/detalhaestado?uf=SC&cobrade=…`.

### F) CEMADEN — observação

O portal do **CEMADEN** (`gov.br/cemaden`) publica riscos geo-hidrológicos, mas na captura
analisada ele só serviu **páginas** (Plone/HTML), sem um endpoint JSON limpo de alertas.
Fica como **fonte futura** (precisaria dos endpoints do mapa/alertas do CEMADEN). O
**RecomGov** (SERPRO) que apareceu na captura é recomendação de serviços gov.br — não é dado
de desastre e foi descartado.

### Estações de rio da Defesa Civil SC perto de Porto Belo (referência)

| Código | Nome | Dist. aprox. | Mede |
|---|---|---|---|
| DCSC-00159 | Penha | ~3 km | chuva, nível de rio |
| DCSC-00030 | Ilhota | ~21 km | chuva, nível de rio |
| DCSC-00160 | Balneário Camboriú (Hospital) | ~25 km | chuva, vento, umidade, pressão |
| DCSC-00061 | Camboriú | ~26 km | chuva, nível de rio |