# Leitores do InControl no Nexus — passo a passo fácil

Este guia mostra como **gerenciar os leitores** (os aparelhos de acesso: facial,
biometria, cartão) direto no Nexus. Eles são **espelhados do InControl**: a lista
e as configurações passam a viver aqui, e o InControl continua sendo a ponte que
fala com o hardware.

> **Novo leitor?** O cadastro de um aparelho novo continua sendo feito **no InControl**
> (ele descobre o aparelho na rede). Depois é só **Importar** aqui — ele aparece na
> lista. Aqui você ajusta as configurações e opera (reiniciar, sincronizar, etc.).

---

## Passo 1 — Preparar o banco (uma vez)

**Se o seu Nexus foi instalado antes de julho/2026**, rode esta migração — troque a
senha do banco quando ele pedir:

```
C:\wamp64\bin\mariadb\mariadb11.4.9\bin\mariadb.exe -h 127.0.0.1 -P 3307 -u guilherme -p controle_veiculos < C:\wamp64\www\api\database\migration_incontrol_dispositivo.sql
```

✅ **Deu certo se:** o comando não imprime nada (no MariaDB, silêncio é sucesso).

---

## Passo 2 — Importar os leitores

1. No menu, vá em **Configurações → Leitores InControl** (ou abra `/incontrol/devices`).
2. Clique em **↧ Importar do InControl**.

✅ **Deu certo se:** a mensagem verde diz quantos leitores foram importados e eles
aparecem na tabela, com o status (Online/Offline, Habilitado, Sincronizado).

> Pode importar quantas vezes quiser — ele **atualiza** os que já existem (não duplica)
> e traz os novos.

---

## Passo 3 — Ver e editar um leitor

1. Clique no **nome** do leitor (ou em **Ver**) para ver os detalhes: modelo, rede,
   firmware, portas (pontos de acesso).
2. Clique em **Editar** para mudar as configurações que o Nexus gerencia:
   **nome, IP, gateway, máscara, porta, login e senha do aparelho, e habilitar/desabilitar**.
3. Antes de salvar, você pode clicar em **Testar conexão** — ele usa o IP/porta/senha
   digitados para ver se o leitor responde.
4. Clique em **Salvar e enviar**. As mudanças vão para o InControl na hora.

✅ **Deu certo se:** a mensagem verde confirma "enviado ao InControl" e os novos valores
aparecem na tela do leitor.

> **Senha do aparelho:** por segurança ela aparece **mascarada** (••••) e, no formulário,
> o campo fica em branco. Deixe em branco para **manter** a senha atual; preencha só se
> for **trocar**.

---

## Passo 4 — Ações no leitor

Na tela de detalhes de cada leitor:

- **↻ Reiniciar** — reinicia o aparelho (fica alguns segundos fora do ar).
- **🔕 Cancelar alarme** — silencia um alarme disparado no leitor.
- **Ocultar das telas** — some o leitor das listas do Nexus **sem apagar** (útil para
  um aparelho desativado). Dá para **Reexibir** depois.

E na lista (topo), o botão **⟳ Sincronismo parcial** manda o InControl **empurrar as
pendências** (pessoas, credenciais, permissões) para **todos** os leitores de uma vez.

---

## Deu problema?

Primeiro, **olhe o log**: **Sistema → Diagnóstico → Log de integrações** (filtro
`InControl`). É lá que aparece o motivo real de uma falha (o leitor não respondeu, o
InControl recusou, etc.).

- **"Não foi possível importar".** O InControl está fora do ar ou a configuração de
  conexão (`INCONTROL_*` no `.env`) está errada. Confira em **Diagnóstico**.
- **Editei mas não salvou / "não foi possível enviar ao InControl".** O envio ao
  controlador falhou; **nada foi alterado** (o Nexus só grava quando o InControl
  aceita). Tente de novo; se persistir, verifique se o InControl está no ar.
- **"Testar conexão" diz que não respondeu.** Confira IP, porta (padrão 37777 nos
  leitores Dahua) e a senha do aparelho. O leitor precisa estar na mesma rede.
- **Um leitor sumiu da lista.** Ou foi **Ocultado** (reexiba na tela dele), ou foi
  removido no InControl. Importe de novo para reconciliar.
- **Não vejo o menu "Leitores InControl".** Sua conta precisa da permissão de gerenciar
  o InControl (administração ou administrador do sistema).

---

## Nota técnica (para quem mantém o sistema)

- **Fonte da verdade da GESTÃO é o Nexus** (tabela `incontrol_dispositivo`); o InControl
  é a ponte com o hardware. Import = pull (reconciliação por `incontrol_id`); edição =
  `GET` fresco do objeto → sobrepõe os campos editáveis → `PUT /v1/dispositivo/{id}`.
- **Caminhos confirmados por HAR:** `GET /v1/dispositivo`, `GET/PUT /v1/dispositivo/{id}`,
  `GET /v1/dispositivo/testar_conexao?ip&porta&modelo&senha&login`,
  `GET /v1/dispositivo/sincronismo_parcial` (GLOBAL, sem id),
  `PUT /v1/dispositivo/{id}/reiniciar` (corpo = objeto completo),
  `GET /v1/dispositivo/{id}/cancelar_alarme`.
- **⚠ CRIAÇÃO de dispositivo NÃO foi capturada no HAR** — o leitor nasce na descoberta de
  rede do InControl. Por isso aqui não há "novo leitor"; ele aparece ao importar. (Mesma
  disciplina do Omada/CELESC: não inventar endpoint — confirmar por HAR.)
- A senha do aparelho é PII sensível (como as credenciais): guardada para re-empurrar/
  testar, sempre exibida mascarada, só quem tem `incontrol.manage` vê.