Mapeamento de Banco de Dados — `checkins`

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

1. Visão Geral da Modelagem de Check-ins

A tabela checkins armazena o histórico e o estado em tempo real das solicitações de confirmação de presença (Check-in Antecipado ou Presencial) submetidas pelos motoristas para um determinado agendamento (appointment_id).

2. Atributos Físicos da Tabela `checkins`

Coluna	Tipo SQL	Constraints	Descrição / Regra de Negócio
`id`	`BigInteger`	`PRIMARY KEY`, `autoincrement=True`	Identificador único do check-in
`appointment_id`	`BigInteger`	`FOREIGN KEY (appointments.id)`, `NOT NULL`, `INDEX`	Agendamento associado
`terminal_id`	`BigInteger`	`FOREIGN KEY (terminals.id)`, `NOT NULL`, `INDEX`	Terminal onde o check-in foi efetuado
`user_tax_id`	`VARCHAR(14)`	`NOT NULL`, `INDEX`	CPF do motorista solicitante
`status`	`VARCHAR(20)`	`NOT NULL`, Default `'PENDING'`, `INDEX`	Estado atual (`PENDING`, `PROCESSING`, `APPROVED`, `REJECTED`, `EXPIRED`, `CANCELLED`)
`location_lat`	`FLOAT`	`NULLABLE`	Latitude capturada do dispositivo mobile no envio
`location_lng`	`FLOAT`	`NULLABLE`	Longitude capturada do dispositivo mobile no envio
`rejection_reason`	`TEXT`	`NULLABLE`	Motivo cadastrado pelo operador no Web App caso o check-in seja rejeitado
`approved_by_user_id`	`BigInteger`	`FOREIGN KEY (companies_users.id)`, `NULLABLE`	Operador de terminal que aprovou a solicitação
`rejected_by_user_id`	`BigInteger`	`FOREIGN KEY (companies_users.id)`, `NULLABLE`	Operador de terminal que rejeitou a solicitação
`checked_in_at`	`TIMESTAMPTZ`	`NOT NULL`, Default `now()`	Timestamp em que o motorista confirmou o check-in
`resolved_at`	`TIMESTAMPTZ`	`NULLABLE`	Timestamp da aprovação, rejeição ou expiração
`expires_at`	`TIMESTAMPTZ`	`NULLABLE`	Horário limite de expiração se o terminal não responder

3. Máquina de Estados de Check-in

stateDiagram-v2
    [*] --> PENDING: Motorista submete no Mobile App
    PENDING --> PROCESSING: Operador abre solicitação no Web App
    PROCESSING --> APPROVED: Operador Clica em "Aprovar" (Emite Ticket)
    PROCESSING --> REJECTED: Operador Clica em "Rejeitar" (Informa Motivo)
    PENDING --> EXPIRED: APScheduler atinge expires_at sem ação
    PENDING --> CANCELLED: Agendamento ou Motorista cancela
    APPROVED --> [*]
    REJECTED --> [*]
    EXPIRED --> [*]

4. Regras de Integridade e Trava de Concorrência

`RN-CHK-DB-001`: Trava de Check-in Ativo Único

Um agendamento só pode ter 1 (um) registro em checkins com status IN ('PENDING', 'PROCESSING'). Tentativas de criar um novo check-in para um agendamento com solicitação pendente retornará HTTP 400 (CHECKIN_ALREADY_EXISTS).

`RN-CHK-DB-002`: Emissão Automática de Ticket em Aprovação

Quando o status de um check-in é atualizado para APPROVED, a transação SQL cria obrigatoriamente um novo registro na tabela tickets contendo o snapshot dos dados do agendamento antes de efetivar o db.commit().

1. Visão Geral da Modelagem de Check-ins​

2. Atributos Físicos da Tabela checkins​

3. Máquina de Estados de Check-in​

4. Regras de Integridade e Trava de Concorrência​

RN-CHK-DB-001: Trava de Check-in Ativo Único​

RN-CHK-DB-002: Emissão Automática de Ticket em Aprovação​