Mapeamento de Banco de Dados — drivers e users
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/auth.py,app/api/public/trips.py)
1. Visão Geral da Relação Motorista vs. Conta de Usuário Mobile
O sistema separa a entidade operacional do motorista de carga (Driver) da conta física de acesso ao aplicativo (User):
Driver: Criado automaticamente via integração API ERP ou cadastro de Terminal/Transportador. Contém dados de CNH e validação de frota.User: Criado pelo motorista no aplicativo mobile durante o onboarding. Armazena o hash de senha, o identificador de dispositivo confiável (validated_device) e relaciona-se 1:N com a tabelauser_fcm_tokens.
2. Atributos Físicos da Tabela drivers
| Coluna | Tipo SQL | Constraints | Descrição / Regra |
|---|---|---|---|
id | BigInteger | PRIMARY KEY, autoincrement=True | Identificador físico único do motorista |
tax_id | VARCHAR(14) | NOT NULL, UNIQUE, INDEX | CPF do motorista (apenas números). Chave primária de vínculo |
driver_license_number | VARCHAR(20) | NULLABLE | Número da Carteira Nacional de Habilitação (CNH) |
driver_license_category | VARCHAR(10) | NULLABLE | Categoria da CNH (ex: "E", "D") |
driver_license_expiration | DATE | NULLABLE | Data de validade da CNH |
validated_by | BigInteger | FOREIGN KEY (companies.id), NULLABLE | Empresa que realizou o primeiro cadastro/validação do motorista |
is_active | BOOLEAN | NOT NULL, Default true, INDEX | Flag de desativação lógica |
created_at | TIMESTAMPTZ | NOT NULL, Default now() | Timestamp de cadastro |
updated_at | TIMESTAMPTZ | NOT NULL, Default now() | Timestamp de alteração |
3. Atributos Físicos da Tabela users (Mobile Accounts)
| Coluna | Tipo SQL | Constraints | Descrição / Regra |
|---|---|---|---|
id | BigInteger | PRIMARY KEY, autoincrement=True | ID do usuário mobile |
tax_id | VARCHAR(14) | NOT NULL, UNIQUE | CPF do usuário (coincide com drivers.tax_id) |
name | VARCHAR(100) | NULLABLE | Nome completo do motorista |
phone | VARCHAR(20) | NULLABLE | Telefone celular cadastrado com DDI |
email | VARCHAR(100) | NULLABLE, UNIQUE | E-mail opcional do motorista |
password_hash | VARCHAR(255) | NULLABLE | Hash bcrypt da senha de 6+ caracteres |
validated_device | VARCHAR(100) | NULLABLE | Identificador único (fingerprint) do celular confiável |
driver_id | BigInteger | FOREIGN KEY (drivers.id), NULLABLE | Relacionamento físico com o perfil operacional Driver |
is_active | BOOLEAN | NOT NULL, Default true | Flag de ativação |
4. Tabela de FCM Tokens Multi-Dispositivo (user_fcm_tokens)
Permite que um mesmo motorista receba notificações Push em múltiplos aparelhos caso autenticado simultaneamente:
| Coluna | Tipo SQL | Constraints | Descrição |
|---|---|---|---|
id | BigInteger | PRIMARY KEY, autoincrement=True | ID do registro de token |
user_id | BigInteger | FOREIGN KEY (users.id, CASCADE), NOT NULL | ID do usuário mobile proprietário |
fcm_token | VARCHAR(255) | NOT NULL, UNIQUE, INDEX | Token alfanumérico emitido pelo Google Firebase FCM |
device_os | VARCHAR(10) | NULLABLE | 'android' ou 'ios' |
last_updated | TIMESTAMPTZ | Default now() | Data da última atualização/ping do token |
5. Regras de Negócio de Motoristas (RN-DRV-XXX)
RN-DRV-001: CPF Único Global
Não podem existir dois registros em drivers ou users com o mesmo tax_id. O CPF é a chave primária de identidade do motorista no ecossistema Gatein.
RN-DRV-002: Auto-Upsert de Motorista por API Pública
Ao criar agendamentos (POST /public/appointments) ou viagens (POST /public/trips), se o CPF do motorista não for localizado na tabela drivers, o servidor insere automaticamente o motorista com validated_by = company.id, eliminando a necessidade de pré-cadastro manual.