# Integração com o SolarMan (usina solar)

Este guia liga o painel de **Energia** do Nexus à sua conta do **SOLARMAN Smart**
(o app da sua usina fotovoltaica). Depois de configurar, o sistema mostra sozinho:
se a usina está **online**, a **potência agora**, a **geração de hoje/mês/total**,
e avisa quando a usina **cai** ou fica **sem gerar** durante o dia.

> Em miúdos: é a **sua conta** do SolarMan lendo os **seus dados**. O sistema
> **só lê** — nunca desliga inversor nem muda nada na usina.

---

## Antes de começar

Você vai precisar de:
- O **e-mail e a senha** que você usa no app/site **SOLARMAN Smart**.
- O **Google Chrome** no seu computador (para o Passo 2).
- Acesso ao servidor onde o Nexus roda (`C:\wamp64\www`).

> ### Por que a senha sozinha não basta
>
> O site do SolarMan pede um **captcha** (aquele deslizador de "confirme que você
> não é um robô") toda vez que alguém entra com e-mail e senha. Captcha existe
> justamente para impedir que um programa faça login sozinho — e o sistema é um
> programa. Se ele tentar, o SolarMan responde com erro.
>
> A saída é simples e é a mesma que o próprio site usa: **você** faz o login uma
> vez, como pessoa, resolvendo o captcha. Nesse momento o SolarMan te entrega um
> **crachá de longa duração** (o "refresh_token"). Você copia esse crachá para o
> sistema, e ele passa a se virar sozinho — sem senha e sem captcha — por cerca de
> **6 meses**. Quando estiver perto de vencer, o sistema te avisa.

---

## Passo 1 — Coloque seu login no arquivo `.env`

1. No servidor, abra **`C:\wamp64\www\api\.env`** com o Bloco de Notas.
2. Procure a parte **SolarMan** (ou cole no fim) e preencha:

   ```
   SOLARMAN_ENABLED=true
   SOLARMAN_USER=seuemail@exemplo.com
   SOLARMAN_PASS=sua_senha_do_solarman
   SOLARMAN_STATION_ID=
   SOLARMAN_BASE_URL=https://globalhome.solarmanpv.com
   SOLARMAN_REFRESH_TOKEN=
   ```

3. Salve. O `SOLARMAN_REFRESH_TOKEN` você preenche no Passo 2.

> Deixe `SOLARMAN_STATION_ID=` **vazio** — o sistema descobre a usina sozinho. Se
> você tiver mais de uma usina e quiser fixar uma, coloque o número dela aqui
> (o teste do Passo 3 mostra o número).

✅ **Deu certo se:** o arquivo salvou e `SOLARMAN_ENABLED=true` está lá.

---

## Passo 2 — Pegue o "crachá" (refresh_token) no navegador

Leva um minuto. É no **seu computador**, não no servidor.

1. Abra o **Google Chrome** e vá em **https://globalhome.solarmanpv.com**
2. **Antes de logar**, aperte a tecla **F12**. Vai abrir um painel do lado (é o
   painel de desenvolvedor — não se assuste, você não vai quebrar nada).
3. Nesse painel, clique na aba **Network** (ou "Rede").
4. Agora **faça o login normalmente**: e-mail, senha e o captcha do deslizador.
5. Assim que entrar, olhe a lista que apareceu no painel Network. Procure uma linha
   chamada **`token`** e clique nela.
   - Se a lista estiver enorme, digite `token` na caixinha de filtro do painel.
6. Do lado, clique na aba **Response** (ou "Resposta"). Vai aparecer um texto com
   várias coisas entre chaves.
7. Ache o pedaço **`"refresh_token":"eyJhbGciOi..."`** e **copie o texto longo que
   está entre as aspas** (só o texto, sem as aspas). Ele é bem comprido — umas 15
   linhas. Copie **inteiro**.
8. No **servidor**, abra o Prompt de Comando (Menu Iniciar → digite `cmd`) e cole:

   ```
   C:\wamp64\bin\php\php8.3.28\php.exe C:\wamp64\www\api\scripts\solarman_token.php COLE_O_TEXTO_AQUI
   ```

9. O programa confere o crachá com o SolarMan e mostra até quando ele vale.
10. Ele vai imprimir uma linha `SOLARMAN_REFRESH_TOKEN=...`. **Copie essa linha
    inteira** para o `.env` (substituindo a que está vazia) e salve.

✅ **Deu certo se:** apareceu `[OK] O SolarMan aceitou o token` e a validade
(algo como "180 dias").

❌ **"Isso não parece um token JWT"** → você copiou só um pedaço. Volte ao passo 7 e
copie o texto **inteiro**, do `eyJ` até o último caractere antes das aspas.

❌ **"O SolarMan recusou o token"** → o site invalidou esse crachá (acontece se você
saiu da conta). Faça login de novo e pegue outro.

---

## Passo 3 — Teste a conexão

1. Menu Iniciar → **cmd** → abra o Prompt de Comando.
2. Cole e Enter:

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

✅ **Deu certo se:** aparecer `[ OK ] Login`, o **nome e a potência** da usina
(kWp), o **estado (ONLINE/OFFLINE)**, a **geração** de hoje/mês/total e a lista de
**alertas** e **inversores**.

❌ Se aparecer `[FALHA] Login`, confira e-mail/senha. Se aparecer erro de conexão,
sua conta pode ser de outro servidor — troque a linha `SOLARMAN_BASE_URL` para
`https://home.solarmanpv.com` e teste de novo.

---

## Passo 4 — Ligue o módulo no sistema

1. Entre no Nexus como administrador.
2. **Configurações → Módulos**.
3. Ligue a chave **"Usina solar SolarMan"**.

✅ **Deu certo se:** a chave ficou verde.

---

## Passo 5 — Veja o painel

1. No menu, abra **Início → Energia**.

✅ **Deu certo se:** aparece o card **Usina solar** com "Online", a potência de
agora, a geração de hoje/mês, e (se houver) os alertas do inversor.

> Também dá para colocar essa tela no **Mural** (o telão): ela já entra na rotação
> automaticamente e pode ser liberada num link público de TV.

---

## Passo 6 — Deixe atualizar sozinho

O mesmo "trabalhador" das contas (**energy_sync**) atualiza a usina a cada ~30 min.
Se ainda não estiver agendado:

1. Menu Iniciar → **cmd** → botão direito → **Executar como administrador**.
2. Cole e Enter:

   ```
   C:\wamp64\www\api\scripts\install_workers.bat
   ```

✅ **Deu certo se:** na conferência final, **energy_sync** aparece `[PRESENTE]`.

---

## Os avisos automáticos

Com o módulo ligado, o sistema te avisa (pelos canais que você já usa — Pushover,
WhatsApp, notificação) quando:
- a **usina cai** (fica offline) — **exceto à noite**, quando o inversor desliga e
  ficar offline é o normal;
- a usina está **online mas gerando 0 W** durante o dia (inversor pode ter travado);
- acontece uma **falha grave no inversor** — e **só se tiver acontecido agora**
  (últimas 24 h, veja abaixo).

---

## Passo 7 — Escolha o que é alerta e o que é só registro

Alguns eventos são **rotina** em certos inversores ("PV Isolation Protection",
"DC Bus Unbalance"). Se todo evento virar notificação, você para de olhar as
notificações — e aí a que importa passa batido.

1. No menu, vá em **Início → Energia**.
2. Clique em **⚙ Ajustes da usina** (canto superior direito).
3. Na tabela **"Quais eventos viram alerta"**, marque os que são **só registro**.
   Eles continuam no histórico da usina, mas não notificam ninguém.
4. Na tabela **"Inversores em uso"**, desmarque um inversor que você **trocou**.
   Dica: é aquele cuja coluna "Última comunicação" mostra "há N dias".
5. **Salvar ajustes.**

✅ **Deu certo se:** o evento marcado ganha a etiqueta **"não notifica"** e a tela de
Energia deixa de mostrá-lo em vermelho **na hora** (não precisa esperar meia hora).

> **Por que os alertas antigos não voltam mais.** O SolarMan não tem uma lista de
> "alertas ativos" — ele devolve o **histórico** dos últimos eventos. O sistema
> antigo lia essa lista e re-enviava tudo de 12 em 12 horas, então um problema de
> três dias atrás, já resolvido, continuava te acordando. Agora só notifica evento
> **recente** (24 h por padrão; mude com `SOLARMAN_ALERT_MAX_AGE_H` no `.env`).

---

## Deu problema?

- **"A usina fica mandando alerta que eu não pedi"** → veja o **Passo 7**. E rode o
  diagnóstico abaixo: ele lista cada evento e diz, um por um, **se vai notificar e
  por quê** (nível baixo / evento antigo / silenciado por você / SIM).

  ```
  C:\wamp64\bin\php\php8.3.28\php.exe C:\wamp64\www\api\scripts\energy_diag.php solar
  ```

- **"falta o SOLARMAN_REFRESH_TOKEN"** → você pulou o **Passo 2**. A senha sozinha
  não autentica (o site exige captcha). Volte lá e pegue o crachá.
- **"o portal EXIGE CAPTCHA no login por senha (AUTH_SLIDE_ERROR)"** → o crachá
  venceu ou foi invalidado (você saiu da conta no site). Repita o **Passo 2** e
  cole o novo `SOLARMAN_REFRESH_TOKEN`.
- **"SolarMan: acesso vence em N dias"** (aviso automático) → é o crachá chegando ao
  fim dos ~6 meses. Repita o **Passo 2**. Nada quebra até lá.
- **Quero saber exatamente o que o servidor respondeu** → rode o diagnóstico:

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

  Ele mostra a configuração que está valendo, o que foi enviado e o **texto cru** da
  resposta do SolarMan — sem adivinhação.
- **Erro de conexão / usina não encontrada** → troque `SOLARMAN_BASE_URL` entre
  `https://globalhome.solarmanpv.com` e `https://home.solarmanpv.com`.
- **Aparece "OFFLINE" mas a usina está funcionando** → pode ser o datalogger sem
  internet no momento; confira a rede da usina. O sistema volta ao normal sozinho.
- **Quero desligar** → em **Módulos**, desligue a chave (ou `SOLARMAN_ENABLED=false`).

---

## É seguro?

- Sua senha fica **só no `.env` do servidor**.
- O sistema **só lê** estado e geração. **Não controla** a usina.