Aparência
Tarefas Agendadas — sweeps e higiene de estado
O que é este documento — o inventário das tarefas agendadas (cron) do ionCLASS: cada varredura, sua cadência, o que faz e quais efeitos colaterais dispara (broadcast em tempo real, notificação ao responsável, chamada outbound ao hardware). É o mapa de "o que roda sozinho" que mantém o quadro de retirada e as autorizações honestos quando ninguém age. Companheiro operacional do runbook de tempo real (a fila que entrega os broadcasts destas varreduras).
Pré-requisitos operacionais
Nada abaixo roda sem que a infraestrutura de background esteja de pé — e, como o tempo real, degrada em silêncio se cair:
- O agendador precisa estar rodando. Em produção isso é uma entrada de cron única que aciona o agendador a cada minuto, ou um processo de agendamento contínuo sob supervisor/systemd. Sem ele, nenhuma das varreduras abaixo executa — cards ficam presos, autorizações vencidas continuam "válidas" e crachás revogáveis seguem funcionando.
- Horizon/filas de pé. Vários efeitos colaterais são assíncronos: os broadcasts (
StudentStateChanged,StudentRosterChanged), as notificações ao responsável e as chamadas outbound ao controle de acesso saem pela fila. Se o worker está parado, a varredura "roda" mas o efeito não chega. Ver o runbook de tempo real §1 e §4. - Redis saudável — pré-requisito de Horizon e do scaling do Reverb.
⚠️ Convenção de cadência. A cadência aqui é a do agendador. A tarefa só dispara na frequência abaixo se o agendador estiver sendo acionado a cada minuto pelo cron do sistema — a granularidade real nunca é mais fina que isso.
Inventário das varreduras
| Tarefa | Cadência | O que faz | Efeitos colaterais |
|---|---|---|---|
| Expiração de pessoas autorizadas vencidas | de hora em hora | Expira as pessoas autorizadas temporárias cujo período de validade já passou (as pendentes, aprovadas ou com ajustes solicitados passam a vencidas). | Registra na auditoria a expiração. Se a autorização estava aprovada (chegou a ser agendada no hardware), enfileira uma revogação outbound para o crachá parar de funcionar, e a marca como pendente de sincronização até a confirmação. |
| Expiração de liberações de saída antecipada vencidas | de hora em hora | Expira as liberações de saída antecipada cuja data já passou sem uso (as pendentes, aprovadas ou com ajustes solicitados passam a vencidas). | Registra na auditoria; não há credencial de hardware persistente para revogar. |
| Limpeza de vínculos aluno–responsável vencidos | diária, à meia-noite (00:00) | Remove fisicamente os vínculos aluno–responsável temporários cujo período de validade já passou. Vínculos permanentes — pai/mãe titular, sem datas de validade — nunca são tocados. | Para cada vínculo removido, dispara StudentRosterChanged para o app do responsável sumir com o aluno da lista. O acesso já estava negado desde o instante do vencimento (o vínculo vencido deixa de contar como aprovado); esta varredura só limpa a linha morta. |
| Encerramento de sinais de chegada expirados | a cada minuto | Encerra os sinais de chegada ("Estou chegando") que passaram do tempo limite configurado pela escola sem ninguém avançar o card, revertendo os alunos que ainda estavam aguardando. (FR-111) | Reverte o estado dos alunos ainda aguardando e emite os broadcasts correspondentes ao quadro. |
| Reversão de alunos presos em "Pronto" | a cada 5 minutos | Reverte alunos presos em Pronto além do tempo limite configurado (default 60 min) de volta para Na escola. A reversão é condicional na versão do estado de retirada — se a retirada real venceu a corrida, o aluno é ignorado sem efeitos. | Por aluno revertido: revoga o grant de saída no hardware; notifica os responsáveis de que a retirada foi revertida; emite StudentStateChanged com o motivo "tempo de prontidão esgotado" para o monitor dropar o card e alertar; registra na auditoria. |
| Limpeza de tokens de acesso expirados | diária | Remove os tokens de autenticação (Sanctum) expirados há mais de 24h, para não acumular sessões mortas do mobile. | Nenhum efeito de domínio — higiene de dados. |
| Snapshot de métricas do Horizon | a cada 5 minutos | Materializa as séries de métricas que o dashboard do Horizon lê. Sem isso os gráficos ficam permanentemente vazios. | Nenhum efeito de domínio — observabilidade das filas. |
⚠️ Só o que é temporário. A varredura de expiração de pessoas autorizadas atua apenas sobre autorizações temporárias — autorizações permanentes não são expiradas.
Como interagem com a máquina de estados
As duas varreduras de higiene (o encerramento de sinais de chegada expirados e a reversão de alunos presos em Pronto) são o braço automático da máquina de estados da retirada (ver ciclo de retirada): elas fazem transições que nenhum humano disparou, para que o quadro nunca minta.
- Pronto é uma credencial viva. Um aluno em Pronto tem um grant físico na catraca — pode sair. Um Pronto esquecido é, ao mesmo tempo, uma mentira no quadro e uma credencial aberta. Por isso a reversão de alunos presos em Pronto não só volta o estado: revoga o grant e avisa o responsável.
- Optimistic locking, sem atropelo. A reversão corre contra a retirada real — que pode ser confirmação do operador ou a saída lida pelo controle de acesso (a transição de Pronto para Retirado tem dupla origem, protegida por controle de versão do estado). A atualização condicional garante que, se a retirada vence, a varredura perde de forma graciosa e não emite efeito nenhum.
- Motivo no broadcast. O
StudentStateChangedcarrega o motivo "tempo de prontidão esgotado", o que permite ao monitor distinguir "sumiu porque foi retirado" de "sumiu porque estourou o tempo" e alertar de forma diferente.
Como interagem com o ledger outbound
As varreduras de expiração fecham o ciclo de vida de autorizações que já tinham sido empurradas ao hardware (ver integração outbound):
- A expiração de uma pessoa autorizada aprovada enfileira uma revogação outbound no ledger — o mesmo canal usado no fluxo normal de revogação — e a marca como pendente de sincronização até a confirmação. Uma autorização que nunca foi aprovada/agendada não gera outbound (não há nada para revogar no controle de acesso).
- A reversão de alunos presos em Pronto revoga o grant de saída, também pela camada de hardware.
- As chamadas outbound são assíncronas (fila): a varredura enfileira; a entrega ao controle de acesso depende do worker estar de pé.
Ao operar
- Se cards ficam presos em Aguardando ou Pronto: cheque primeiro se o agendador está de pé (nenhuma das varreduras de encerramento/reversão roda sem ele) e, em seguida, se o worker de fila está processando (o efeito pode estar enfileirado e não entregue).
- Se um crachá revogado continua abrindo a catraca depois de uma autorização vencer: a expiração pode ter rodado (autorização marcada como vencida) mas a revogação outbound pode estar presa na fila — inspecione o Horizon e o ledger outbound.
- Ajuste de tempo de Pronto:
IONCLASS_READY_TIMEOUT_MINUTES(env) controla o corte usado pela reversão de alunos presos em Pronto; o timeout do sinal de chegada é configurado por escola.