# Credenciais no InControl — cadastro pelo Nexus (passo a passo fácil)

Este guia explica o **cadastro de credenciais** (cartão, senha, controle remoto e
placa) direto na ficha da pessoa, dentro do Nexus. Elas são **espelhadas no
InControl** automaticamente — a ideia é que toda a gestão fique aqui, e o InControl
sirva só de ponte para os leitores.

> A **biometria (digital)** ainda **não** está aqui: ela exige um diálogo ao vivo com
> o leitor (a pessoa encosta o dedo no aparelho). Fica para uma próxima etapa.

---

## Antes de começar

- A pessoa já precisa existir no sistema (em **Pessoas**).
- Se ela já estiver **vinculada ao InControl**, a credencial vai para lá na hora.
  Se ainda **não** estiver, você pode cadastrar mesmo assim — ela é enviada quando
  a pessoa for espelhada.

✅ **Deu certo se:** você abre a ficha de uma pessoa e vê o botão **"Credenciais"** no
topo.

---

## Passo 1 — Prepare 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_pessoa_credencial.sql
```

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

---

## Passo 2 — Cadastrar uma credencial

1. No menu, vá em **Cadastros → Pessoas** e abra a pessoa.
2. Clique em **🔑 Credenciais** (no topo da ficha).
3. Escolha o **tipo** e preencha:
   - **Cartão / TAG:** o código em **hexadecimal** *ou* **decimal** (um só basta) e o
     tamanho (**26** ou **34 bits** — o padrão da maioria é 34).
   - **Senha (PIN):** 4 a 12 dígitos (o que a pessoa digita no teclado do leitor).
   - **Controle remoto:** o código + quais **botões** liberam.
   - **Placa:** a placa do veículo (esta é a credencial de placa *no InControl*; a
     leitura de placa por câmera do sistema é outra coisa, fica em **Veículos**).
4. **Adicionar credencial.**

✅ **Deu certo se:** a credencial aparece na lista, com a etiqueta **"Espelhada"**
(verde). Se aparecer **"Só local"** (amarelo), o envio ao InControl ainda não
aconteceu — veja "Deu problema?".

> **Segurança:** os códigos e o PIN ficam guardados no sistema (para poder reenviar ao
> InControl quando você troca um leitor, por exemplo) e são sempre exibidos
> **mascarados** (••••1234). Só quem tem a permissão de gerenciar credenciais vê a tela.

---

## Passo 3 — Remover uma credencial

Na lista, clique em **Remover**. Ela sai **do sistema e do InControl** (o sistema pede
confirmação antes).

---

## Deu problema?

- **A credencial ficou "Só local" (amarela).** O envio ao InControl falhou (ex.: o
  InControl estava fora do ar). A credencial está salva aqui; será reenviada na
  próxima sincronização. Se persistir, confira se o módulo InControl está no ar.
- **"A tabela de credenciais ainda não existe".** É o **Passo 1** — rode a migração.
- **Não vejo o botão "Credenciais".** Sua conta precisa da permissão de **gerenciar
  credenciais** (portaria, administração ou administrador do sistema).
- **A remoção diz "não foi confirmada no InControl".** O Nexus removeu a credencial
  daqui, mas o controlador não confirmou. Isso pode acontecer porque o caminho exato
  de exclusão de credencial ainda está sendo validado (ver a nota técnica abaixo) —
  confira no InControl e, se necessário, remova por lá.

---

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

- **Fonte da verdade é o Nexus.** A credencial vive em `pessoa_credencial`; o
  InControl é espelho (best-effort), igual a pessoas e grupos.
- **Corpo do `POST /v1/credencial/` confirmado por HAR** (cartão): `nivel`, `tipo`, e o
  bloco do tipo (`cartao`/`senha`/`controle_remoto`/`placa`), com `pessoa.id`. O
  `CredentialSync::buildBody` monta exatamente essa estrutura.
- **⚠ A EXCLUSÃO de credencial é caminho INFERIDO.** O HAR fornecido não capturou a
  remoção. O sistema tenta `POST /v1/credencial/batch_delete` e, se falhar,
  `DELETE /v1/credencial/{id}` — best-effort. **Para fixar o caminho certo, capture um
  HAR removendo uma credencial no InControl e ajuste `InControlService::deleteCredential`.**
  (Mesma disciplina do Omada/CELESC: não inventar endpoint — confirmar por HAR.)
- **O bloco `senha`** (PIN) também precisa de validação: o HAR capturado era de cartão,
  então mandamos as chaves prováveis (`senha`/`codigo`); confirme num HAR de criação de
  senha.