Mapeamento de Banco de Dados — appointments
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/activities.py,app/api/web/appointments.py)
1. Visão Geral da Modelagem de Agendamentos (appointments)
A tabela appointments gerencia a entidade operacional de Agendamento de Carga ou Descarga em um Terminal (terminal_id). É o modelo mais consumido no aplicativo mobile e no painel operacional de pátio.
2. Atributos Físicos da Tabela appointments
| Coluna | Tipo SQL | Constraints | Descrição / Regra de Negócio |
|---|---|---|---|
id | BigInteger | PRIMARY KEY, autoincrement=True | ID interno do agendamento |
terminal_id | BigInteger | FOREIGN KEY (terminals.id), NOT NULL, INDEX | Terminal onde ocorrerá o atendimento |
ref | VARCHAR(100) | NULLABLE, INDEX | Código de referência externo (ex: ORD-2026-9948) |
layout_ref | VARCHAR(50) | NULLABLE | Identificador do layout JSON de exibição do card |
user_tax_id | VARCHAR(14) | NULLABLE, INDEX | CPF do motorista escalado |
status | VARCHAR(20) | NOT NULL, Default 'ACTIVE', INDEX | Estado atual (PLANNED, ACTIVE, CHECKED-IN, IN_PROGRESS, PAUSED, COMPLETED, CANCELLED, DELETED) |
summary | VARCHAR(150) | NULLABLE | Resumo descritivo da carga ou produto |
license_plate | VARCHAR(10) | NULLABLE, INDEX | Placa do veículo cadastrado |
window_start | TIMESTAMPTZ | NULLABLE | Horário previsto de início da janela de atendimento |
window_end | TIMESTAMPTZ | NULLABLE | Horário previsto de término da janela de atendimento |
start_tolerance | INTEGER | NOT NULL, Default 0 | Tolerância antecipada permitida em minutos |
end_tolerance | INTEGER | NOT NULL, Default 0 | Tolerância de atraso permitida em minutos |
custom_data | JSONB | NULLABLE | Dados dinâmicos adicionais utilizados no preenchimento de campos de layout |
last_ping_at | TIMESTAMPTZ | NULLABLE | Data do último ping/presença do motorista |
deactivated_at | TIMESTAMPTZ | NULLABLE | Data em que o agendamento foi desativado/concluído |
is_active | BOOLEAN | NOT NULL, Default true, INDEX | Flag de desativação lógica |
created_at | TIMESTAMPTZ | NOT NULL, Default now() | Timestamp de criação |
updated_at | TIMESTAMPTZ | NOT NULL, Default now() | Timestamp de atualização |
3. Constraints e Índices de Performance
unique_appointment_ref_per_company:UniqueConstraint('terminal_id', 'ref')garantindo que o Terminal não crie dois agendamentos com a mesma referência de Ordem de Carga.idx_appointment_terminal_ref: Índice composto(terminal_id, ref)para acelerar a busca via API pública.idx_appointments_user_tax_id_status: Índice composto otimizado para a busca por motorista na rotaGET /mobile/activities.
4. Tabela de Logs e Auditoria (appointments_logs)
Todas as mutações de agendamento (criação, edição, check-in, envio de push, alteração de status) gravam registros na tabela appointments_logs:
| Coluna | Tipo SQL | Constraints | Descrição |
|---|---|---|---|
id | BigInteger | PRIMARY KEY, autoincrement=True | ID do log |
company_id | BigInteger | FOREIGN KEY (companies.id), NOT NULL | ID da empresa Terminal |
appointment_id | BigInteger | FOREIGN KEY (appointments.id), NOT NULL | ID do agendamento afetado |
event | Enum (AppointmentEvent) | NOT NULL | Evento (created, updated, checkin_cancelled, notification_sent, viewed, clicked) |
message | TEXT | NULLABLE | Descrição legível da ação |
json | JSONB | NULLABLE | Snapshot do payload ou metadados de auditoria |
created_at | TIMESTAMPTZ | NOT NULL, Default now() | Timestamp do log |
5. Regras de Negócio (RN-APT-DB-XXX)
RN-APT-DB-001: Invalidação de Check-in em Mudança de Status
Se o status de um agendamento for alterado para CANCELLED via API do Terminal, qualquer check-in em andamento na tabela checkins vinculado a esse appointment_id é automaticamente marcado como CANCELLED e cancelado no APScheduler.