Pular para o conteúdo principal

Eventos e Ciclo de Vida de Check-in

Pilar: 04 — Banco de Dados e Eventos / Eventos
Status: 🟢 Implementado
Última Revisão Técnica: 2026-08-03
Módulos Conectados: gatein-server (app/api/mobile/checkin.py, app/api/web/checkin.py, app/api/sockets/handlers/checkin.py)

1. Visão Geral dos Eventos de Check-in​

O ciclo de vida de um check-in no Gatein envolve a coordenação de eventos assíncronos entre a API REST, o servidor Socket.IO (namespace /checkin), o hardware físico do terminal, o banco de dados PostgreSQL e o serviço de notificações Push (Google FCM).

2. Eventos de Domínio do Módulo de Check-in​

2.1 Evento: checkin.requested (Solicitação de Check-in)​

  • Origem: Chamada POST /mobile/checkin/{terminal_id} pelo aplicativo mobile.
  • Ação: Valida a presença do terminal no dicionário WebSocket active_terminals. Inicia o handshake em background run_async_checkin().
  • Notificação: Se o terminal estiver offline (não conectado ao Socket.IO), retorna erro síncrono HTTP 503.

2.2 Evento: checkin.handshake_failed (Falha / Timeout)​

  • Origem: Servidor Socket.IO atinge timeout de 15 segundos no evento request_checkin ou o hardware do terminal reporta exceção.
  • Ação: Transação de check-in cancelada.
  • Notificação: Dispara Push FCM para o motorista:
    • Título: "Tempo Limite Excedido" ou "Falha no Check-in"
    • Payload data: {"type": "CHECKIN_FAILED"}

2.3 Evento: checkin.approved (Check-in Aprovado)​

  • Origem: Resposta positiva do hardware no handshake Socket.IO ou aprovação manual pelo operador no Web App.
  • Efeitos colaterais:
    1. Transiciona Appointment.status de ACTIVE para CHECKED-IN.
    2. Insere um registro na tabela tickets contendo o snapshot dos dados de liberação em content.
    3. Registra auditoria em appointments_logs com event = 'ticket_created'.
  • Notificação: Dispara Push FCM com type: "CHECKED-IN" ou "CHECKIN_APPROVED" contendo os IDs Sqids do agendamento e do ticket.

2.4 Evento: checkin.cancelled (Cancelamento de Check-in)​

  • Origem: Chamada POST /mobile/checkin/cancel/{appointment_id} ou ação do operador no Web App.
  • Efeitos colaterais:
    1. Reverte o status do agendamento de CHECKED-IN / ON_GOING de volta para ACTIVE.
    2. Registra auditoria em appointments_logs com event = 'checkin_cancelled' e o motivo.
  • Notificação: Dispara Push FCM informando o motorista com type: "CHECKIN_CANCELLED".

3. Matriz de Eventos de Log (AppointmentEvent)​

Evento de Log (AppointmentEvent)Origem da InvocaçãoConteúdo do Campo json
NOTIFICATION_SENTJobs do APScheduler / Handlers{"push_type": "REMINDER_1DAY"} / {"push_type": "CHECKED-IN"}
CHECKIN_CANCELLEDEndpoint /mobile/checkin/cancel{"reason": "Motivo do cancelamento"}
TICKET_CREATEDSucesso no handshake do check-in{"ticket_id": "sqid", "layout_ref": "v1_ticket_gate"}
VIEWEDMobile App via log-events{"source_screen": "CheckinProcessingScreen"}