Gestão de Envios e Configuração de Tipos (Web App)

Pilar: 02 — Funcionalidades Core / Web App
Status: 🟢 Implementado
Última Revisão Técnica: 2026-08-09
Módulos Conectados: gatein-server (app/api/web/submissions.py, app/api/web/submission_types.py), gatein-web (src/screens/Submissions/, src/screens/SubmissionTypes/)

---

1. Visão Geral e Arquitetura do Módulo

O painel administrativo do Web App provê dois submódulos principais para a gestão de envios:

1. Configuração de Tipos de Envio (SubmissionType): Permite que administradores e operadores do terminal criem formulários dinâmicos com regras de anexo e campos personalizados.
2. Painel de Monitoramento de Envios (Submission): Permite a listagem paginada, busca avançada por CPF de motorista e visualização detalhada das informações e anexos transmitidos pelos motoristas no app mobile.

---

2. Permissões e Controle de Acesso (RBAC)

O acesso aos endpoints de Web Submissions é protegido pelas permissões do módulo submissions:

• submissions:read: Permite visualizar os tipos de envio e os envios recebidos pela empresa (CompanyUser).
• submissions:write: Permite criar, atualizar (upsert) e excluir (soft-delete) tipos de envio.

---

3. Contratos de API e Schemas Web

3.1 Endpoints de Tipos de Envio (/api/web/submission-types)

Método	Endpoint	Permissão RBAC	Descrição / Operação
GET	/submission-types	submissions:read	Lista todos os tipos de envio ativos da empresa logada
PUT	/submission-types	submissions:write	Cria ou atualiza (upsert por ref) um tipo de envio
DELETE	/submission-types/{ref}	submissions:write	Realiza soft-delete (is_active=False) do tipo de envio pela referência

Schema de Requisição para Upsert (SubmissionTypeSchema):

{
  "title": "Comprovante de Descarregamento",
  "ref": "comprovante_descarregamento",
  "allow_edit": true,
  "accepts_attachment": true,
  "multiple_attachments": true,
  "allowed_formats": ["image", "pdf"],
  "attachment_required": true,
  "fields": [
    {
      "id": "numero_lacre",
      "label": "Número do Lacre",
      "type": "text",
      "multiline": false,
      "required": true,
      "placeholder": "Digite o número do lacre..."
    },
    {
      "id": "temperatura_container",
      "label": "Temperatura Medida (°C)",
      "type": "number",
      "multiline": false,
      "required": false
    }
  ]
}

3.2 Endpoints de Envios Recebidos (/api/web/submissions)

Método	Endpoint	Permissão RBAC	Descrição / Operação
GET	/submissions	submissions:read	Lista/Pesquisa os envios recebidos com suporte a filtro por CPF (tax_id), limit e offset
GET	/submissions/{submission_id}	submissions:read	Retorna os detalhes completos de um envio específico (dados de campos + anexos)

Exemplo de Resposta de Listagem (GET /submissions):

{
  "success": true,
  "data": [
    {
      "id": 1042,
      "user_tax_id": "12345678901",
      "user_name": "João da Silva",
      "type_title": "Comprovante de Descarregamento",
      "status": "SENT",
      "attachments_count": 2,
      "fields_count": 2,
      "created_at": "2026-08-09T20:15:00Z",
      "edited_at": null
    }
  ],
  "total": 1,
  "limit": 50,
  "offset": 0
}

---

4. Regras de Negócio de Servidor (RN-SUB-WEB)

• RN-SUB-WEB-001 (Validação de Consistência no Upsert): Ao cadastrar ou alterar um SubmissionType, o servidor rejeita tipos sem ao menos um campo marcado como "required": true OU que não possuam accepts_attachment: true e attachment_required: true.
• RN-SUB-WEB-002 (Normalização de Ref e Title): A referência (ref) é convertida automaticamente para minúsculas sem espaços extras e sanitizada antes da persistência.
• RN-SUB-WEB-003 (Limpeza de CPF na Busca): O parâmetro tax_id na busca de envios remove automaticamente pontos e hífens (., -) para executar busca parcial via LIKE SQL.
• RN-SUB-WEB-004 (Tenant Isolation): Todas as consultas (db.query(Submission)) aplicam obrigatoriamente a trava company_id == current_user.company_id para impedir vazamento de dados entre empresas.