Mapeamento de Banco de Dados — submission_types e submissions

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

---

1. Visão Geral do Modelo Relacional

O módulo de Envios é sustentado por duas tabelas relacionais no PostgreSQL:

1. submission_types: Armazena os modelos de formulários e regras configurados pelas empresas (Tenants).
2. submissions: Registra as submissões enviadas individualmente pelos motoristas no aplicativo mobile.

---

2. Atributos Físicos da Tabela submission_types

Coluna	Tipo SQL	Constraints	Descrição / Regra
id	BigInteger	PRIMARY KEY, autoincrement=True	Identificador único numérico
company_id	BigInteger	FOREIGN KEY (companies.id), NOT NULL, INDEX	Empresa proprietária do tipo de envio
title	VARCHAR(100)	NOT NULL	Título do tipo exibido para o motorista
ref	VARCHAR(50)	NOT NULL	Identificador de referência amigável (ex: dacte_comprovante)
allow_edit	BOOLEAN	NOT NULL, Default true	Indica se o motorista pode alterar a submissão pós-envio
accepts_attachment	BOOLEAN	NOT NULL, Default false	Se permite anexos no envio
multiple_attachments	BOOLEAN	NOT NULL, Default false	Se aceita múltiplos arquivos
allowed_formats	JSONB	Default []	Formatos autorizados. Ex: ["image", "pdf"]
attachment_required	BOOLEAN	NOT NULL, Default false	Se ao menos 1 anexo é obrigatório
fields	JSONB	Default []	Estrutura de campos do formulário dinâmico
is_active	BOOLEAN	NOT NULL, Default true	Status de ativação (usado para Soft-delete)
created_at	TIMESTAMPTZ	NOT NULL, Default now()	Timestamp de criação
updated_at	TIMESTAMPTZ	NOT NULL, Default now()	Timestamp de alteração

Estrutura do JSONB na Coluna fields:

[
  {
    "id": "numero_lacre",
    "label": "Número do Lacre",
    "type": "text",
    "multiline": false,
    "required": true,
    "regex": null,
    "placeholder": "Informe o lacre..."
  }
]

---

3. Atributos Físicos da Tabela submissions

Coluna	Tipo SQL	Constraints	Descrição / Regra
id	BigInteger	PRIMARY KEY, autoincrement=True	Identificador do envio
company_id	BigInteger	FOREIGN KEY (companies.id), NOT NULL, INDEX	Empresa destinatária do envio
submission_type_id	BigInteger	FOREIGN KEY (submission_types.id), NULLABLE	Referência ao tipo de envio (pode ser null se tipo for apagado ou tipo padrão)
user_tax_id	VARCHAR(14)	NOT NULL, INDEX	CPF do motorista remetente
user_name	VARCHAR(100)	NULLABLE	Nome do motorista no momento do envio
type_title	VARCHAR(100)	NOT NULL	Título snapshot do tipo de envio
status	VARCHAR(20)	NOT NULL, Default 'SENT'	Estado do envio: 'SENT', 'EDITED', 'CANCELLED'
field_data	JSONB	Default {}	Chave-valor das respostas dos campos
attachments	JSONB	Default []	Metadados e URLs dos anexos armazenados no R2
edited_at	TIMESTAMPTZ	NULLABLE	Data da última edição realizada
cancelled_at	TIMESTAMPTZ	NULLABLE	Data de cancelamento do envio
is_active	BOOLEAN	NOT NULL, Default true	Status de visibilidade
created_at	TIMESTAMPTZ	NOT NULL, Default now()	Timestamp do envio
updated_at	TIMESTAMPTZ	NOT NULL, Default now()	Timestamp de atualização

Estrutura do JSONB na Coluna attachments:

[
  {
    "url": "https://pub-r2.gatein.app/submissions/3a7b9c1d-8f2e-4b9a.jpg",
    "type": "image",
    "name": "foto_comprovante.jpg"
  }
]

---

4. Índices e Restrições de Integridade

• unique_submission_type_ref_per_company: Restrição única composta (company_id, ref) que previne a criação de múltiplos tipos com a mesma referência para a mesma empresa.
• idx_submission_type_lookup: Índice composto (company_id, ref) para buscas ultrarrápidas de tipo por empresa.
• idx_submissions_company_tax_id: Índice composto (company_id, user_tax_id) otimizado para o painel web filtrar envios de um motorista específico em uma empresa.
• idx_submissions_user_tax_id: Índice no campo user_tax_id acelerando a listagem de histórico no aplicativo mobile do motorista.