# Departamentos e Zonas de tempo do InControl no Nexus — passo a passo

Este guia mostra como gerenciar, direto no Nexus, dois cadastros do InControl:

- **Departamentos** — unidades organizacionais (setores/blocos) a que as pessoas
  podem pertencer.
- **Zonas de tempo** — faixas de horário por dia da semana que definem **quando** o
  acesso é permitido (os grupos de acesso usam essas zonas).

Os dois são lidos **ao vivo** do InControl (não precisa "importar"): o que você criar,
editar ou excluir aqui reflete no InControl na hora.

> Precisa da permissão de **gerenciar o InControl** (administração ou administrador do
> sistema). Não há migração de banco — é tudo pela ponte do InControl.

---

## Departamentos

1. No menu, **Configurações → Departamentos IC** (ou `/incontrol/departments`).
2. **+ Novo departamento**: informe o **nome** (obrigatório) e, se quiser, número,
   um **departamento pai** (para hierarquia) e uma observação. **Salvar**.
3. Para mudar, clique em **Editar**; para remover, **Excluir** (pede confirmação).

✅ **Deu certo se:** o departamento aparece na lista com a mensagem verde de confirmação.

---

## Zonas de tempo

1. No menu, **Configurações → Zonas de tempo IC** (ou `/incontrol/timezones`).
2. **+ Nova zona de tempo**: dê um **nome** (ex.: `Comercial (Seg–Sex 08–18)`).
3. Para cada **dia da semana**, adicione as **faixas de horário** liberadas
   (início → fim). Ex.: Segunda `08:00` até `18:00`. Um dia **sem faixa** = acesso
   **bloqueado** naquele dia.
   - **+ faixa** adiciona outra janela no mesmo dia (ex.: manhã e tarde separadas).
   - **✕** remove uma faixa.
4. **Salvar e enviar**.

✅ **Deu certo se:** a zona aparece na lista com um resumo do agendamento (ex.:
`Seg 08:00–18:00; Ter 08:00–18:00; …`).

> ⚠ **Confira a primeira zona no InControl.** A forma como o InControl guarda os
> horários e os dias da semana foi descoberta por engenharia reversa (a partir de uma
> captura da tela dele). Está calibrada e testada, mas **na primeira zona que você
> criar, abra a mesma zona no InControl e confira** se os dias e horários bateram. Se
> algo destoar, me avise (é um ajuste rápido de um único ponto de conversão).

---

## Deu problema?

Primeiro, **olhe o log**: **Sistema → Diagnóstico → Log de integrações** (filtro
`InControl`) mostra o motivo real de uma falha.

- **A lista não carrega / "não foi possível ler".** O InControl está fora do ar ou a
  configuração `INCONTROL_*` no `.env` está errada. Veja em **Diagnóstico**.
- **Não consegui salvar.** O InControl recusou a gravação; **nada foi alterado** lá.
  Tente de novo; confira o nome (obrigatório) e se o controlador está no ar.
- **O resumo do agendamento aparece "abra para ver".** A lista do InControl não trouxe
  as faixas (só o nome) — abra a zona em **Editar** para ver/ajustar o agendamento.
- **Uma zona ficou com o horário/dia trocado.** É o ponto de conversão inferido — me
  avise com um exemplo (o que você pôs × o que apareceu no InControl) que eu corrijo.

---

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

- **Entidades de CONFIGURAÇÃO** do InControl (não recursos nossos): lidas ao vivo, com
  gravação passada adiante (best-effort), como o espelho de usuários. Sem tabela local.
- **Departamento — CRUD confirmado por HAR:** `GET /v1/departamento`,
  `GET/PUT /v1/departamento/{id}`, `POST /v1/departamento/` (`{nome}`),
  `POST /v1/departamento/batch_delete` (`{ids:[…]}`). Corpo de edição:
  `{id,nome,numero,departamento_principal,observacao}`.
- **Zona de tempo — CRUD confirmado por HAR:** `GET /v1/zona_tempo`,
  `GET/PUT /v1/zona_tempo/{id}`, `POST /v1/zona_tempo/`, `batch_delete`. Corpo:
  `{nome_zona_tempo, dias:[{descricao, sequencia, ranges:[{data_inicio,data_fim}]}]}`.
- **⚠ Encoding das faixas INFERIDO de UM range de teste no HAR** (Segunda, uma faixa).
  `App\Support\ZoneTime` (puro, testado por `api/scripts/tests_zonatempo.php`) converte
  `HH:MM ↔ ms` (só o HORÁRIO conta; o dia vem da `sequencia`) e o mapa de dias
  (`sequencia` 1=Dom … 7=Sáb; **Segunda=2 confirmado**, o resto é a convenção padrão).
  A tela DECODIFICA as zonas existentes para conferência. **Validar com um HAR de uma
  zona semanal real** e então fixar. (Mesma disciplina do Omada/CELESC: não inventar —
  confirmar.)