Modelo de Dados (entidades e relações)

Modelo de dados do backend do H1 Tech (HSBR-Gestao-Ativos-Back), banco ga6. A fonte da verdade é o prisma/schema.prisma — mesmo schema roda em Postgres ou SQL Server (ver Bancos Suportados). Esta página é um mapa de leitura; ao mudar o schema, regenere o entendimento a partir do Prisma.

Convenção do schema

Nomes de tabelas/colunas estão em português, minúsculo com _ (ex.: ordem_separacao). Quase tudo usa id Int @id @default(autoincrement()); exceções: produto (produto_id), zpl (zpl_id), users (user_id), lotes (lote_id) e agrupamento_pacote (PK é o epc, string).

Diagrama ER

O EPC (código RFID de 24/64 chars) costura o modelo: ativo.epc é único e é o que aparece em movimentacao, inventario_itens, agrupamento_item, etc.

Arraste para mover · zoom nos botões (ou Ctrl + scroll) · “Tela cheia” para ampliar

Relações polimórficas (sem FK)

Duas referências são intencionalmente sem foreign key:

• alerta.ref_id → aponta para inventario.id, movimentacao.id, … conforme tipo_alerta.
• campo_personalizado_alvo.alvo_id → aponta para processo.id ou produto.produto_id conforme alvo_tipo.

Por não terem FK, não aparecem como linhas sólidas no diagrama — a integridade é responsabilidade da aplicação.

Entidades por domínio

Catálogo / Ativos

Entidade	O que é	Relações principais
ativo	Tabela central: um registro por ativo etiquetado (EPC único). Valores de campos custom em campos (JSON).	→ zpl (etiqueta_id, cascade), produto, processo, ativo_status; ← agrupamento_item
ativo_status	Lookup de status (status único) referenciado por ativo.status.	← ativo
produto	Catálogo de produtos (codigo_barras único). Valores custom em campos.	← ativo, ordem_separacao_*, inventario_itens_2d, produto_processo_quantidade
zpl	Templates de etiqueta (ZPL). owner_id → users.	← ativo, campo_personalizado
campo_personalizado	Definições de campos custom, escopadas por entidade (e etiqueta_id p/ ativos). Valores vivem nos campos JSON da entidade dona.	→ zpl; ← campo_personalizado_alvo, processo_regra
campo_personalizado_alvo	Associa um campo custom a alvos específicos. alvo_id é polimórfico (sem FK).	→ campo_personalizado (cascade)
lotes	Lista simples de lotes.	— (sem FK)
mapas	Mapas/plantas com pontos (JSON).	— (sem FK)

Processos / Movimentação

Entidade	O que é	Relações principais
processo	Ponto de leitura / etapa do fluxo.	→ nivel; ← movimentacao (origem/destino), ordem_separacao, processo_regra, integracao, produto_processo_quantidade, ativo
nivel	Hierarquia de locais (auto-relação via parent_id).	→ nivel (self); ← processo, inventario, inventario_recorrencia
movimentacao	Evento de movimentação de um EPC entre processos. campos JSON capturados no move.	→ processo (origem/destino), users
processo_regra	Regras do "documento de movimentação" no processo destino (origem permitida / campo obrigatório).	→ processo (×2), campo_personalizado
produto_processo_quantidade	Quantidade esperada por produto×processo (unique).	→ produto, processo

Inventário

Entidade	O que é	Relações principais
inventario	Contagem de inventário (status, esperado/encontrado).	→ nivel, users (leitor/criador), inventario_recorrencia; ← inventario_itens, inventario_itens_2d
inventario_itens	Itens lidos por EPC numa contagem.	→ inventario, users
inventario_itens_2d	Itens por código de barras/2D (por produto + qtd).	→ inventario, produto, users
inventario_recorrencia	Agendamento de inventário recorrente (frequência, próxima execução).	→ nivel, users; ← inventario

Separação (picking)

Entidade	O que é	Relações principais
ordem_separacao	Ordem de separação. 3 papéis de usuário (solicitante/criador/receptor).	→ processo, users (×3); ← ordem_separacao_epcs, ordem_separacao_produtos
ordem_separacao_epcs	EPCs individuais da ordem.	→ ordem_separacao (cascade), produto
ordem_separacao_produtos	Linhas por produto (qtd esperada/separada).	→ ordem_separacao (cascade), produto

Agrupamento (caixas / pacotes)

Entidade	O que é	Relações principais
agrupamento_pacote	Pacote/caixa. PK é o epc (string). parent_id faz a árvore caixa→caixa (auto-relação, SetNull).	→ agrupamento_pacote (self), pacote_tipos (FK composta empresa+tipo); ← agrupamento_item
agrupamento_item	Quais ativos (item_epc) estão em qual caixa (pacote_epc). FKs reais (cascade).	→ agrupamento_pacote, ativo
pacote_tipos	Tipos de pacote por empresa + template ZPL. PK composta (empresa,tipo).	← agrupamento_pacote

Integrações (Integration Hub)

Entidade	O que é	Relações principais
integracao	Regra: ao mover itens PARA um processo, faz POST a uma API externa (async, pós-commit). auth_secret cifrado.	→ processo (cascade); ← integracao_envio
integracao_envio	Log de cada tentativa de entrega (auditoria + reenvio).	→ integracao (cascade)

Usuários / Auth / Config / Alertas

Entidade	O que é	Relações principais
users	Usuários (user_id PK). permissoes JSON, nivel_ids Int[].	← praticamente tudo (movimentação, inventário, ordens, logs, alertas, zpl, refresh_tokens)
refresh_tokens	Tokens de refresh por usuário (token único, revoked).	→ users (cascade)
logs	Trilha de auditoria de rotas.	→ users
alerta	Notificações/alertas. ref_id polimórfico (sem FK). Estado visto/visto_em.	→ users
configuracoes	Configuração de UI (cores, logo, lote de impressão) + flags.	← feature_flags
feature_flags	Flags por configuração (configuracao_id+feature_key unique).	→ configuracoes

Notas de integridade

• Cascades reais: ativo ← zpl (apagar template apaga seus ativos), agrupamento_item ← agrupamento_pacote/ativo, ordem_separacao_* ← ordem_separacao, integracao_envio ← integracao, refresh_tokens ← users, campo_personalizado_alvo ← campo_personalizado.
• Maioria das FKs é NoAction (não apaga em cascata) — apagar um produto/processo/users referenciado falha se houver filhos, por design.
• campos (JSON) em ativo, produto e movimentacao guarda os valores de campos personalizados (chaveados pelo slug de campo_personalizado). Isso substituiu as tabelas/colunas dinâmicas criadas via DDL em runtime (refactor da camada de dados).