Outbound — ionCLASS → Hardware Accelero

O que é este documento — o detalhe do fluxo OUTBOUND (FLUXO B): tudo que o backend do ionCLASS empurra para o hardware Accelero — agendar visita recorrente, liberar saída antecipada, abrir a catraca do aluno pronto, revogar autorizações e espelhar veículos. Cobre o livro-razão (ledger), a idempotência pelo identificador de correlação (X-Correlation-Id), a política de retry, o gate de consentimento biométrico (LGPD) e o discriminador de tipo enviado ao Accelero.

Para a visão geral das duas direções e da abstração de driver, veja Visão geral. O sentido oposto (hardware → backend) está em Inbound.

1. O livro-razão (ledger)

Toda ação que precisa mexer nas permissões do hardware passa por um único ponto que cria uma linha no livro-razão e enfileira a entrega. Ele:

Busca a configuração da escola. Sem config, ou escola não integrada (inativa, sem sistema de controle de acesso, ou sistema que exige URL do controle sem URL preenchida) → no-op: nada é enfileirado, retorna vazio, loga skip. É o significado literal de "a escola não integra".
Cria uma linha pending no livro-razão com um identificador de correlação fresco (UUID v4) — a chave de idempotência que o hardware vê em todas as tentativas (viaja como X-Correlation-Id) — carimbando o sistema de controle de acesso (autoritativo, vindo da config), a ação, a entidade e o payload.
Enfileira a entrega assíncrona correspondente à ação:

Ação	Efeito no hardware
Agendar visita	cadastra a pessoa como visita recorrente
Autorizar liberação	libera a saída (janela pontual ou grant imediato)
Revogar visita	remove/desativa a autorização
Registrar veículo	espelha a placa (Cartão LPR)
Revogar veículo	remove a placa

Payload da fila é mínimo (ids/refs). O payload completo que o Accelero recebe (pessoa: nome/CPF/foto; janela; type) é montado no momento do envio, a partir da entidade — sempre o estado atual quando a entrega roda.

1.1 Estados do ledger e retry

A entrega define tentativas e backoff a partir da configuração de integração (3 tentativas, backoff [60, 300, 900] s, timeout 30 s). A cada rodada:

Antes do envio — carimba status = retry com o número da tentativa.
A tentativa faz um POST ao hardware; grava o carimbo da última tentativa, o código de status e o corpo da resposta (≤ 4096 chars) na linha. Falha → reprograma pelo backoff.
Sucesso — status = success, carimbo de sucesso, limpa a pendência de sincronização (só a pessoa autorizada tem essa flag; passe/aluno não), audita.
Falha final (retries esgotados) — status = failed, mantém a pendência de sincronização na pessoa autorizada (o admin vê o alerta), audita.

A linha do livro-razão evolui no lugar (só data de criação, sem carimbo de atualização); a trilha das transições vive na auditoria, correlacionada pelo identificador de correlação (X-Correlation-Id).

1.2 Retry manual

Retry disparado pelo admin numa chamada failed: reseta a linha para pending, zera os contadores de retry preservando o identificador de correlação (o hardware segue vendo a mesma operação idempotente) e re-enfileira a entrega. Superfície no Painel administrativo.

2. Fluxo enfileiramento → entrega → hardware → ledger (ASCII)

 Ação de negócio (aprovação, transição, sweep…)
        │  entidade.pendência de sincronização = true  (quando a entidade tem a flag; na própria transação)
        ▼
 Enfileiramento da chamada outbound (ação, entidade, escola, payload)
        │  escola não integra ────────────────► no-op (vazio, skip log)
        │  cria linha pending (identificador de correlação fresco = idempotency key)
        │  enfileira a entrega
        ▼
  ── fila ────────────────────────────────────────────────────────
 Entrega assíncrona      tentativas / backoff ← configuração de integração
        │  status=retry (nº da tentativa)
        ▼
 Monta o payload a partir da entidade  (+ gate LGPD ao agendar visita)
        ▼
 Adaptador Accelero  → POST base_url/<path>
        │  header X-Accelero-Signature = HMAC-SHA256(body, chave de saída)
        │  header X-Correlation-Id     = identificador de correlação
        ▼
   success? ── sim ─► status=success, limpa a pendência de sincronização
        │
        └─ não ─► falha ─► backoff/retry
                     └─ retries esgotados ─► status=failed (mantém a pendência de sincronização)

O adaptador Accelero assina o corpo bruto com a chave de comandos (saída) da escola (chave distinta da chave de entrada) e pula verificação TLS para hosts de IP privado (a controladora vive na LAN da escola; o HMAC é a autenticação real).

3. Agendar visita — visita recorrente + o gate LGPD ⚠️

Uma tentativa de agendar visita para a pessoa por trás da linha. Três tipos de entidade cavalgam a mesma chamada (no hardware, todas são "este adulto pode entrar"; o que muda é a categoria, resolvida no plugin por person_kind):

Pessoa autorizada — pessoa autorizada recorrente (avó, babá, motorista…).
Responsável — responsável aprovado pelo app (person_kind = guardian).
Passe de retirada (companion) — o companion de uma retirada antecipada acompanhada (person_kind = companion): entra como visitante, sem foto (nunca teve — só nome + CPF no passe), liberado à mão pela portaria.

⚠️ Gate de consentimento biométrico (LGPD art. 11)

Aqui vive o gate — e só aqui, para que nenhum ponto de enfileiramento (aprovações, retries manuais) possa esquecê-lo. A regra de compartilhamento de rosto:

O rosto (photo_url) só é enviado quando a própria pessoa (a conta de app dela) tem consentimento biométrico ativo. A foto existe justamente porque a pessoa entrou no app, adicionou e consentiu.
Sem consentimento, a pessoa ainda é registrada por nome + CPF (a portaria consegue achá-la) — só o rosto é retido (photo_url ausente, não "null com flag").
O responsável consente pela própria conta; a pessoa autorizada consente pela conta de app dela; o passe (companion) não tem conta nem foto → nunca compartilha.

O resultado é forçado no payload como photo_allowed, resolvido no envio (não no enfileiramento) e autoritativo independentemente de qual site criou a linha. Tipo Accelero: recurring_visit.

4. Autorizar liberação — liberação pontual ou grant imediato

Uma tentativa de autorizar liberação, com dois tipos de entidade no mesmo trilho (mesma rota, entrega, retry e livro-razão — é um ato no hardware: dar a esta pessoa uma categoria por uma janela):

Passe de retirada — saída antecipada agendada, para uma data + janela → tipo Accelero one_shot_release (date, start_time, end_time, exit_mode).
Aluno — o grant imediato de saída quando o board chega a ready (ver §5) → tipo Accelero immediate_release.

O discriminador de tipo é o campo type enviado ao Accelero, no qual o plugin despacha: recurring_visit (agendar visita), one_shot_release (passe de retirada) e immediate_release (grant do aluno). exit_mode não é campo de tempo — é regra de negócio do passe de retirada (solo/acompanhado) e pertence só ao one_shot_release.

5. A catraca do aluno — grant e revogação de saída

A catraca é default-deny: até o grant rodar, o aluno pode estar "Pronto" no board e ainda travado no leitor.

Grant de saída — enfileira uma autorização de liberação com type = immediate_release quando o aluno chega a ready (pela máquina de estado; no Accelero é o "permitir saída" do Monitor de Chegadas, agora dirigido pela máquina de estado). A janela aberta (TTL) é propriedade da config do plugin (tela do ionCLASS no Accelero), não é mais enviada daqui. O adaptador manda o próprio identificador de correlação da chamada como visit_ref — único por grant, e a alça que o revoke usa para desfazer exatamente este grant.
- Falhas são engolidas por design: o aluno já é ready, o operador já viu o card mover, e o board não pode travar/reverter porque uma escrita de fila falhou. O livro-razão/retry assume a entrega dali; o tratamento de erro protege a máquina de estado.
Revogação de saída — desfaz o grant quando o aluno efetivamente saiu (picked_up, ou off_premises numa saída não sinalizada) ou o ready expira (por um sweep de expiração). Acha a última autorização de liberação do aluno no livro-razão e enfileira uma revogação de visita passando seu identificador de correlação como visit_ref — nomeando qual grant desfazer. Sem grant anterior (escola não integra, ou aluno retirado sem passar por ready) → nada a fazer. Falhas também são engolidas (o TTL do hardware é o backstop).

6. Revogar visita, registrar e revogar veículo

Revogar visita — remove/desativa o perfil no hardware (responsável bloqueado, autorização expirada/cancelada, companion do passe cancelado). O visit_ref nem sempre é a chave da entidade: para um grant imediato é o identificador de correlação do grant, carregado no payload — cair para a chave da entidade revogaria nada silenciosamente.
Registrar veículo — o plugin acha-ou-cria o responsável como Pessoa por CPF e anexa a placa (Cartão LPR) herdando o acesso do responsável; vehicle_ref (identificador do veículo do responsável) é a alça estável para reconciliar troca de placa e revogar depois. Sem foto (veículo não carrega biometria).
Revogar veículo — o veículo já foi removido quando isto roda, então o vehicle_ref identificador vem do payload enfileirado, não da entidade (que sumiu).

7. Tabela: ação outbound → quando dispara → tipo Accelero

Ação outbound	Quando dispara	Tipo Accelero (`type`)
Agendar visita	Aprovação de pessoa autorizada; vínculo de responsável aprovado pelo app; companion de passe de retirada	`recurring_visit`
Autorizar liberação (pontual)	Aprovação de passe de retirada (saída antecipada)	`one_shot_release`
Autorizar liberação (grant)	Aluno chega a `ready`	`immediate_release`
Revogar visita	Bloqueio de responsável (cascata); suspensão/cancelamento/expiração de autorização; cancelamento de passe; aluno saiu/`ready` expira	revoke de `recurring_visit`/`immediate_release` (por `visit_ref`)
Registrar veículo	CRUD de veículo do responsável (create/update)	— (Cartão LPR)
Revogar veículo	Veículo removido	—

Sweeps de expiração rodam pelo agendador: um sweep de hora em hora enfileira revogar visita para autorizações vencidas que já estavam no hardware; um sweep a cada 5 min dispara a revogação de saída para alunos ready obsoletos. Detalhe das tarefas agendadas em Runbook de tempo real.

8. O livro-razão (ledger) da chamada outbound

Campo	Papel
identificador do sistema	sistema de controle de acesso carimbado da config da escola (autoritativo na resolução da entrega)
ação	agendar visita / autorizar liberação / revogar visita / registrar veículo / revogar veículo
entidade	a entidade por trás da chamada (pessoa autorizada, responsável, passe de retirada, aluno, veículo do responsável)
identificador de correlação	UUID = idempotency key; estável entre retries; vira `visit_ref`/`X-Correlation-Id`
payload	payload mínimo da fila (ids/refs); o corpo real é montado no envio
status	`pending` → `retry` → `success` / `failed`
contadores/carimbos do retry	número da tentativa, próximo retry, última tentativa, sucesso
resposta do hardware	código de status e corpo (≤ 4096)

A linha evolui no lugar; as transições ficam na auditoria.

Ver também

Visão geral — abstração de driver, identidade e o mapa das duas direções
Inbound — o sentido hardware → backend
Ciclo de retirada — onde o grant/revoke da catraca se encaixa
Runbook de tempo real — filas e sweeps de expiração
Painel administrativo — alerta de pendência de sincronização e retry manual

Outbound — ionCLASS → Hardware Accelero ​

1. O livro-razão (ledger) ​

1.1 Estados do ledger e retry ​

1.2 Retry manual ​

2. Fluxo enfileiramento → entrega → hardware → ledger (ASCII) ​

3. Agendar visita — visita recorrente + o gate LGPD ⚠️ ​

⚠️ Gate de consentimento biométrico (LGPD art. 11) ​

4. Autorizar liberação — liberação pontual ou grant imediato ​

5. A catraca do aluno — grant e revogação de saída ​

6. Revogar visita, registrar e revogar veículo ​

7. Tabela: ação outbound → quando dispara → tipo Accelero ​

8. O livro-razão (ledger) da chamada outbound ​

Ver também ​