Dicionário de dados

Atualizado a 30/10/2026 · 160 tabelas e 1619 campos que se transferem

Este é o registo das estruturas e dos formatos dos dados que a sua empresa leva quando muda de prestador ou pede a cópia integral dos dados (termos de utilização, cláusulas 9.6 e 17.8). Como pedir, os prazos e o que custa estão em Mudança de prestador e saída de dados.

A estrutura é a mesma para todas as empresas e é lida das próprias bases de dados. Quando a plataforma muda uma tabela, este registo muda com ela.

Formatos

SQL (PostgreSQL 17). Um ficheiro com a criação de cada tabela e os seus dados, sem o código da plataforma.
CSV, um ficheiro por tabela, com o nome da tabela e codificação UTF-8. A primeira linha tem os nomes dos campos, pela ordem da tabela na base da sua empresa. Os valores seguem o formato de texto do PostgreSQL. Um valor em falta é um campo vazio, sem aspas.
Os campos JSON levam texto JSON. As listas seguem o formato de lista do PostgreSQL, por exemplo {a,b}.
Os ficheiros (fotografias, PDF, assinaturas desenhadas no ecrã, documentos carregados) vão numa pasta à parte, no formato em que estão guardados, com um índice que liga cada ficheiro ao registo a que pertence. Os campos que guardam o caminho de um ficheiro estão indicados abaixo.
Os identificadores ligam os registos entre si. Quando um campo aponta para outra tabela, a descrição diz qual, por exemplo (hub_stores.id).

Os dados vão para quem a empresa indicar por escrito, por um canal cifrado. As tabelas e os campos que não se transferem, e porquê, estão no fim da página.

Os mesmos dados saem também pela interface de exportação, página a página, com uma chave que um administrador da empresa cria na plataforma, e pelo Exportar tudo da Administração, num ZIP — salvo as conversas com o assistente de ajuda, que nem um administrador da empresa lê na plataforma e por isso só vêm na cópia integral.

O canal de denúncias (as denúncias, com o estado, as datas e o processo pendente, a conversa com os denunciantes, as notas internas, os anexos e o registo dos acessos) não vai na cópia integral, na interface de exportação nem no Exportar tudo: transfere-se pela caixa do canal. Vem cifrado do dispositivo de quem o escreve e só o leem as pessoas designadas para quem foi cifrado — nem o ZarvoHUB nem um administrador da empresa que não seja uma delas têm a chave —, e a lei só as deixa a elas tratar das denúncias. Por isso, cada pessoa designada descarrega, decifradas, as denúncias que lê (Descarregar, numa denúncia, ou Descarregar todas), num ZIP com o formato descrito a seguir (termos de utilização, cláusulas 9.6 e 17.6, alínea m)). Não saem as chaves com que cada denúncia é cifrada para cada pessoa designada (hub_den_embrulhos), porque o ficheiro sai decifrado, nem os avisos que a plataforma lhes envia (hub_den_avisos). A lista das pessoas designadas (sem as chaves privadas, que não se transferem: cláusula 17.7, alínea b)), os pedidos para as designar ou tirar e os textos da empresa para o canal (a confirmação de receção e a nota de privacidade) vão na cópia integral.

A descarga do canal. Um ZIP com uma pasta denuncia-<número> por denúncia (o Descarregar todas junta-as num só ZIP e, se alguma falhar, um por-descarregar.txt diz quais). Cada pasta tem um denuncia.txt para ler, um denuncia.json para outro sistema e uma pasta anexos/ com os ficheiros decifrados, no formato original. O denuncia.json (UTF-8) tem: formato (zarvohub-denuncia-1), descarregado_em, descarregado_por, numero, estado, as datas (recebida_em, em_analise_em, resposta_final_em, concluida_em, resultado_pedido_em, resultado_dado_em, apagar_em), processo_pendente e processo; denuncia (o texto, a area, o quando, o onde, a identificacao, com o nome e o contacto, se o denunciante se identificou, e a parte apagada: parte_apagada_em, parte_apagada_por e motivo); conversa e notas_internas (cada mensagem com id, de, em, final, texto, nao_abre, editada_em, editada_por e motivo); anexos (cada um com ficheiro, nome, tipo, tamanho, de, nota_interna, mensagem, criado_em, nao_abre, apagado_em, apagado_por e motivo); lida_por (as pessoas que a leem); e acessos (cada um com em, quem e acao). As datas vêm em ISO 8601, com o fuso. As tabelas da categoria «m», abaixo, descrevem como o canal está guardado na base, cifrado; o que sai é este ficheiro.

Contas e organização

`hub_atividade` Atividade das contas

Uma linha por conta e por módulo, com a última vez que a pessoa esteve nesse módulo (a página aberta e à vista). Serve para o suporte e a segurança do serviço: de cinco em cinco minutos, o resumo — nome de utilizador, nome, perfil, se a conta está ativa, a hora do último acesso e o módulo — vai para a base de gestão do ZarvoHUB, que só guarda o último retrato. Uma sessão «ver como» nunca conta como atividade da pessoa. Apaga-se com a conta.

user_id identificador (UUID) · uuid · obrigatório: Conta a que a atividade pertence (hub_users.id).
modulo texto · text · obrigatório: Módulo em que a pessoa esteve: «hub» (a administração), «rh», «tesouraria», «documentos», «registos», «tickets», «vendas», «despesas» ou «pessoal» (a Área pessoal).
visto_em data e hora, com fuso · timestamp with time zone · obrigatório: Última vez que a pessoa esteve nesse módulo (no máximo uma atualização por minuto).

`hub_convites` Convites de acesso

Uma linha por convite para uma pessoa escolher ela própria a palavra-passe da sua conta, enviado por email ou como link copiado por quem convida. O token do convite não vai na cópia; os convites com mais de 30 dias apagam-se (a auditoria guarda o histórico).

id identificador (UUID) · uuid · obrigatório: Identificador do convite.
user_id identificador (UUID) · uuid · obrigatório: Conta convidada (hub_users.id).
email texto · text: Email para onde o convite foi enviado; vazio nos convites por link.
created_by identificador (UUID) · uuid: Conta que fez o convite (hub_users.id).
expires_at data e hora, com fuso · timestamp with time zone · obrigatório: Instante em que o convite deixa de valer (7 dias depois de criado).
used_at data e hora, com fuso · timestamp with time zone: Instante em que o convite foi aceite ou substituído por um mais recente; vazio = por usar.
created_at data e hora, com fuso · timestamp with time zone · obrigatório: Instante de criação do convite.
canal texto · text · obrigatório: Como chegou à pessoa: «email» ou «link» (copiado por quem convida, para contas sem email).

Não vão na cópia: token_hash (dados de segurança do acesso (cláusula 17.7, alínea b))).

`hub_den_designacoes` Pedidos de designação do canal de denúncias

Uma linha por pedido de acrescentar ou tirar uma pessoa das que recebem as denúncias. Depois de haver uma pessoa ativa, o pedido só se aplica com a aprovação de uma pessoa designada que não o propôs.

id número inteiro · bigint · obrigatório: Número sequencial do pedido.
user_id identificador (UUID) · uuid · obrigatório: Conta da pessoa a acrescentar ou a tirar (hub_users.id).
acao texto · text · obrigatório: «acrescentar» ou «tirar».
funcao_publica texto · text: A função que a página pública do canal mostra (ao acrescentar).
proposto_por identificador (UUID) · uuid: Conta do administrador que propôs (hub_users.id).
proposto_em data e hora, com fuso · timestamp with time zone · obrigatório: Instante do pedido.
estado texto · text · obrigatório: «pendente», «aprovada», «recusada» ou «aplicada_logo» (quando ainda não havia quem aprovasse).
decidido_por identificador (UUID) · uuid: Conta da pessoa designada que decidiu (hub_users.id).
decidido_em data e hora, com fuso · timestamp with time zone: Instante da decisão.

`hub_den_responsaveis` Pessoas que recebem as denúncias

Uma linha por pessoa designada para receber as denúncias (a linha fica quando sai, com a data). A chave privada da pessoa está cifrada com a sua frase-passe do canal, que nunca sai do dispositivo dela, e não vai na cópia integral (termos, cláusula 17.7, alínea b)).

user_id identificador (UUID) · uuid · obrigatório: Conta da pessoa (hub_users.id).
funcao_publica texto · text · obrigatório: A função que a página pública do canal mostra.
designado_em data e hora, com fuso · timestamp with time zone · obrigatório: Instante da designação.
designado_por identificador (UUID) · uuid: Conta do administrador que a propôs (hub_users.id).
chave_publica texto · text: A chave pública, para cifrar as denúncias para esta pessoa.
ativo_desde data e hora, com fuso · timestamp with time zone: Instante em que criou as chaves pela primeira vez (desde quando recebe denúncias).
chaves_em data e hora, com fuso · timestamp with time zone: Instante em que criou as chaves atuais.
saiu_em data e hora, com fuso · timestamp with time zone: Instante em que deixou de ser designada.

Não vão na cópia: chaves (dados de segurança do acesso (cláusula 17.7, alínea b))).

`hub_permissions` Catálogo de permissões

Uma linha por permissão que a Plataforma conhece: ver um ecrã ou fazer uma ação num módulo. O catálogo é da Plataforma; o cliente pode mudar o nome, a ordem e a marca de dado sensível.

key texto · text · obrigatório: Código único da permissão (por exemplo «rh.view.colaboradores», «teso.act.pagamento»).
label texto · text · obrigatório: Nome da permissão mostrado no ecrã de perfis.
module texto · text · obrigatório: Módulo a que pertence: «rh», «tesouraria», «documentos», «registos», «tickets», «vendas», «despesas» ou «sistema»; só vale com o módulo licenciado (as de «sistema» valem sempre).
kind texto · text · obrigatório: «view» (ver um ecrã ou um dado) ou «action» (fazer uma ação).
is_cofre verdadeiro ou falso · boolean · obrigatório: Marca a permissão como acesso a dados sensíveis (mostra um cadeado no ecrã); não muda o que a permissão dá.
sort número inteiro · integer · obrigatório: Ordem no ecrã de perfis.

`hub_profile_permissions` Permissões de cada perfil

Uma linha por permissão concedida a um perfil. Os perfis de administrador não precisam de linhas: têm todas.

profile_id identificador (UUID) · uuid · obrigatório: Perfil (hub_profiles.id).
perm_key texto · text · obrigatório: Permissão concedida (hub_permissions.key).

`hub_profiles` Perfis de acesso

Uma linha por perfil: o conjunto de permissões e de regras de âmbito que se atribui a cada conta.

id identificador (UUID) · uuid · obrigatório: Identificador do perfil.
name texto · text · obrigatório: Nome do perfil, único.
description texto · text: Descrição livre do perfil.
default_modules lista de textos · _text: Módulos que o perfil dá às suas contas, copiados para hub_users.modules_access ao criar a conta (por exemplo «rh», «tesouraria», «vendas»).
is_admin verdadeiro ou falso · boolean: Perfil de administrador: tem todas as permissões e todos os módulos licenciados.
scope_stores verdadeiro ou falso · boolean: Se verdadeiro, as contas deste perfil só veem as lojas que lhes forem atribuídas (hub_users.stores_access).
created_at data e hora, com fuso · timestamp with time zone: Instante de criação.
can_view_hr_sensitive verdadeiro ou falso · boolean: Interruptor antigo de dados sensíveis de RH. Não controla nenhum acesso desde 22/09/2026 (o acesso vem das permissões); mantém-se por compatibilidade.
scope_self verdadeiro ou falso · boolean: Se verdadeiro, as contas deste perfil só veem o próprio registo (portal do colaborador).
updated_at data e hora, com fuso · timestamp with time zone · obrigatório: Instante da última alteração; serve para recusar a gravação de quem editou uma versão já ultrapassada.

`hub_rh_funcao_perfil` Perfil de acesso por função

Uma linha por função profissional: o perfil de acesso que a Plataforma dá automaticamente a uma conta criada para um colaborador com essa função.

role_function texto · text · obrigatório: Nome da função, igual ao de hub_rh_employees.role_function.
profile_id identificador (UUID) · uuid · obrigatório: Perfil de acesso atribuído (hub_profiles.id).
updated_at data e hora, com fuso · timestamp with time zone · obrigatório: Instante da última alteração.

`hub_rh_store_hours` Horário e regras das lojas

Horário de cada loja por dia da semana (produção, abertura e fecho, até dois períodos), editado na ficha da loja, e as regras de pessoal das antigas escalas. Uma linha por loja e dia.

id identificador (UUID) · uuid · obrigatório: Identificador da linha.
store_id identificador (UUID) · uuid · obrigatório: Loja (hub_stores.id).
weekday número inteiro · smallint · obrigatório: Dia da semana: 0 = segunda-feira … 6 = domingo.
is_open verdadeiro ou falso · boolean · obrigatório: Se a loja abre nesse dia.
production_start hora do dia · time without time zone: Hora a que começa a produção, antes da abertura ao público; vazio = sem produção antes da abertura.
open_time hora do dia · time without time zone: Hora de abertura ao público.
close_time hora do dia · time without time zone: Hora de fecho ao público (do primeiro período, se o dia tiver dois).
open_staff número inteiro · integer · obrigatório: Número mínimo de pessoas no arranque do dia (produção ou abertura); regra das antigas escalas, já sem ecrã.
close_staff número inteiro · integer · obrigatório: Número mínimo de pessoas no fecho; regra das antigas escalas, já sem ecrã.
close_needs_supervisor verdadeiro ou falso · boolean · obrigatório: Se o fecho exige pelo menos um responsável de turno; regra das antigas escalas, já sem ecrã.
updated_at data e hora, com fuso · timestamp with time zone · obrigatório: Instante da última alteração.
open2_time hora do dia · time without time zone: Abertura do segundo período do dia (horário partido); vazio = um só período.
close2_time hora do dia · time without time zone: Fecho do segundo período do dia.
open_public_staff número inteiro · smallint · obrigatório: Pessoas que entram à hora de abertura ao público quando a produção começa antes (0 a 50; 0 = sem exigência); regra das antigas escalas.

`hub_stores` Lojas e centros de custo

Uma linha por loja, centro de custo ou sede da empresa: identificação, morada, tipo e ligações ao centro de custo e ao supervisor. Nunca se apaga; desativa-se.

id identificador (UUID) · uuid · obrigatório: Identificador da loja ou centro de custo.
code texto · text · obrigatório: Código interno, único.
name texto · text · obrigatório: Nome completo.
city texto · text: Localidade; cópia de «locality», mantida por compatibilidade.
active verdadeiro ou falso · boolean: Falso quando o registo foi desativado.
created_at data e hora, com fuso · timestamp with time zone: Instante em que o registo foi criado.
street texto · text: Rua da morada.
street_number texto · text: Número de porta da morada.
postal_code texto · text: Código postal, no formato 0000-000.
locality texto · text: Localidade da morada.
aliases texto · text: Outros nomes com que a loja aparece nas faturas, separados por vírgulas; a leitura automática usa-os para reconhecer a loja.
opening_date data (um dia) · date: Data de abertura (dia).
is_cost_center verdadeiro ou falso · boolean · obrigatório: Verdadeiro se o registo é um centro de custo (onde se imputam custos).
supervisor_id identificador (UUID) · uuid: Colaborador que supervisiona a loja (hub_rh_employees.id).
short_name texto · text: Nome curto mostrado na plataforma em vez do nome completo; vazio usa o nome completo.
email texto · text: Email da loja.
is_store verdadeiro ou falso · boolean · obrigatório: Verdadeiro se é uma loja (ponto de venda); um registo pode ser loja e centro de custo ao mesmo tempo.
cost_center_id identificador (UUID) · uuid: Centro de custo a que a loja imputa os custos, quando não é centro de custo ela própria (hub_stores.id).
distrito texto · text: Distrito da morada.
concelho texto · text: Concelho da morada.
deactivated_by identificador (UUID) · uuid: Utilizador que desativou o registo (hub_users.id).
deactivated_at data e hora, com fuso · timestamp with time zone: Instante da desativação.
is_sede verdadeiro ou falso · boolean · obrigatório: Verdadeiro no registo que é a sede da empresa; só um pode estar marcado.
updated_at data e hora, com fuso · timestamp with time zone · obrigatório: Instante da última alteração; serve para recusar a gravação de quem editou uma versão já ultrapassada.

`hub_sys_exportacao_chaves` Chaves de exportação

Uma linha por chave de exportação criada por um administrador na Administração, para descarregar os dados da empresa pela interface de exportação — por exemplo, para os entregar a um novo prestador. A chave só se mostra uma vez, ao criá-la; guarda-se o seu resumo, que não vai na cópia. Vale no máximo 7 dias, pode ser revogada antes e deixa de servir se quem a criou deixar de ser administrador.

id identificador (UUID) · uuid · obrigatório: Identificador da chave.
nome texto · text · obrigatório: Nome dado à chave por quem a criou, por exemplo o nome de quem a vai usar.
criada_por identificador (UUID) · uuid: Administrador que criou a chave (hub_users.id).
criada_em data e hora, com fuso · timestamp with time zone · obrigatório: Instante em que a chave foi criada.
expira_em data e hora, com fuso · timestamp with time zone · obrigatório: Instante a partir do qual a chave deixa de servir, no máximo 7 dias depois de criada.
revogada_em data e hora, com fuso · timestamp with time zone: Instante em que a chave foi revogada; vazio se não foi.
revogada_por identificador (UUID) · uuid: Administrador que revogou a chave (hub_users.id).
ultimo_uso_em data e hora, com fuso · timestamp with time zone: Instante do último pedido feito com a chave; vazio se nunca foi usada.
pedidos número inteiro · bigint · obrigatório: Número de pedidos feitos com a chave.

Não vão na cópia: chave_hash (dados de segurança do acesso (cláusula 17.7, alínea b))).

`hub_users` Contas de utilizador

Uma linha por conta que entra na Plataforma: identificação, perfil, módulos, lojas e estado. O resumo da palavra-passe e a contagem de tentativas falhadas não vão na cópia.

id identificador (UUID) · uuid · obrigatório: Identificador da conta.
username texto · text · obrigatório: Nome de utilizador para entrar, único e em minúsculas; numa conta apagada com histórico passa a «apagada-…».
name texto · text · obrigatório: Nome da pessoa, como aparece na Plataforma («Conta apagada» numa conta apagada com histórico).
role texto · text: Papel da primeira versão da Plataforma: «user» ou «admin». Já não decide acessos (vem de hub_profiles.is_admin); as contas novas ficam em «user».
modules_access lista de textos · _text: Módulos que a conta pode abrir: «tesouraria», «rh», «documentos», «registos», «tickets», «vendas», «despesas». Um administrador abre todos os licenciados.
active verdadeiro ou falso · boolean: Conta ativa; falso = desativada (por um administrador ou por saída da empresa) e não entra.
created_at data e hora, com fuso · timestamp with time zone: Instante de criação da conta.
profile_id identificador (UUID) · uuid: Perfil de acesso (hub_profiles.id).
stores_access lista de identificadores · _uuid: Lojas atribuídas à conta (lista de hub_stores.id). Limitam o que vê quando o perfil é por loja (hub_profiles.scope_stores); nos pedidos das lojas, comunicados e checklists limitam sempre quem não é do escritório.
employee_id identificador (UUID) · uuid: Ficha de colaborador ligada à conta (hub_rh_employees.id); cada ficha tem no máximo uma conta.
must_change_password verdadeiro ou falso · boolean: Verdadeiro quando a palavra-passe foi definida por outra pessoa: a conta tem de escolher uma nova na próxima entrada.
deactivated_by identificador (UUID) · uuid: Conta que desativou esta (hub_users.id).
deactivated_at data e hora, com fuso · timestamp with time zone: Instante da desativação.
locked_until data e hora, com fuso · timestamp with time zone: Instante até ao qual a conta está bloqueada por tentativas de entrada falhadas; «infinity» = até um administrador a desbloquear; vazio = sem bloqueio.
updated_at data e hora, com fuso · timestamp with time zone · obrigatório: Instante da última alteração; serve para recusar a gravação de quem editou uma versão já ultrapassada.
email texto · text: Email da conta: recebe o código de confirmação de cada entrada e serve para entrar e recuperar a palavra-passe. Único entre as contas ativas.
deleted_at data e hora, com fuso · timestamp with time zone: Instante em que a conta foi apagada definitivamente; a linha fica anónima (sem nome real, email, perfil nem ficha) para manter o histórico.
deleted_by identificador (UUID) · uuid: Administrador que apagou a conta (hub_users.id).

Não vão na cópia: password_hash (dados de segurança do acesso (cláusula 17.7, alínea b))); failed_login_count (dados de segurança do acesso (cláusula 17.7, alínea b))).

Recursos humanos

`hub_rh_absences` Faltas e baixas

Uma linha por ausência de um colaborador: falta justificada, falta injustificada ou baixa, com o período, os dias que contam e o justificativo.

id identificador (UUID) · uuid · obrigatório: Identificador da ausência.
employee_id identificador (UUID) · uuid: Colaborador ausente (hub_rh_employees.id).
start_date data (um dia) · date · obrigatório: Primeiro dia da ausência.
end_date data (um dia) · date: Último dia da ausência, inclusive. Vazio numa baixa ainda em aberto.
kind texto · text: Tipo: «justificada», «injustificada» ou «baixa».
days número decimal · numeric: Total de dias que contam como ausência: dias de calendário do período, inclusive, mais os dias de descanso de dias_descanso.
reason texto · text: Notas ou motivo da ausência, em texto livre.
sub_kind texto · text: Tipo de baixa, só quando kind é «baixa»: um valor da lista da Plataforma (por exemplo «Doença», «Acidente de Trabalho») ou texto livre.
doc_url texto · text: Caminho do justificativo (atestado, declaração) no armazenamento de ficheiros; o ficheiro vai na cópia com o índice.
created_by identificador (UUID) · uuid: Utilizador que registou a ausência (hub_users.id).
updated_at data e hora, com fuso · timestamp with time zone · obrigatório: Instante da última alteração.
dias_descanso número inteiro · integer · obrigatório: Dias de descanso colados a uma falta injustificada que a lei manda contar também como falta (0 a 7); já incluídos em days. Zero nos outros tipos.
store_id identificador (UUID) · uuid: Loja onde a pessoa estava no primeiro dia da ausência (hub_stores.id), mesmo que depois tenha mudado de loja; vazio só se a ficha não tinha loja.

`hub_rh_assets` Equipamentos atribuídos

Uma linha por equipamento ou objeto entregue a um colaborador (fardamento, chave, tablet…), com o estado e as datas de entrega e devolução.

id identificador (UUID) · uuid · obrigatório: Identificador do registo.
employee_id identificador (UUID) · uuid: Colaborador a quem o equipamento foi entregue (hub_rh_employees.id).
store_id identificador (UUID) · uuid: Loja do colaborador quando o registo foi gravado pela última vez (hub_stores.id).
item texto · text · obrigatório: Descrição do equipamento, em texto livre.
identifier texto · text: Número de série ou etiqueta do equipamento.
state texto · text · obrigatório: Estado: «atribuido», «devolvido», «perdido» ou «danificado».
assigned_date data (um dia) · date: Dia em que o equipamento foi entregue.
returned_date data (um dia) · date: Dia em que o equipamento foi devolvido.
notes texto · text: Notas em texto livre.
created_by identificador (UUID) · uuid: Utilizador que fez o registo (hub_users.id).
created_at data e hora, com fuso · timestamp with time zone: Instante em que o registo foi criado.

`hub_rh_availability` Disponibilidade dos colaboradores

Regras de disponibilidade de cada colaborador por dia da semana, usadas pelas antigas escalas de turnos. Já não têm ecrã na plataforma; os dados que existam ficam guardados.

id identificador (UUID) · uuid · obrigatório: Identificador da regra.
employee_id identificador (UUID) · uuid · obrigatório: Colaborador a que a regra se aplica (hub_rh_employees.id).
weekday número inteiro · smallint · obrigatório: Dia da semana: 0 = segunda-feira … 6 = domingo.
available verdadeiro ou falso · boolean · obrigatório: Se o colaborador está disponível nesse dia; falso = indisponível o dia inteiro.
start_time hora do dia · time without time zone: Início da janela em que está disponível; com o fim também vazio, está disponível todo o dia.
end_time hora do dia · time without time zone: Fim da janela em que está disponível.
valid_from data (um dia) · date: Primeiro dia em que a regra vale; com o último dia também vazio, a regra é permanente.
valid_until data (um dia) · date: Último dia em que a regra vale. Uma regra com datas é temporária e prevalece sobre a permanente nesses dias.
note texto · text: Nota livre sobre a regra.
created_by identificador (UUID) · uuid: Conta que criou a regra (hub_users.id).
created_at data e hora, com fuso · timestamp with time zone: Instante em que a regra foi criada.

`hub_rh_aval_notas` Notas por critério das avaliações

A nota dada a cada critério numa avaliação de desempenho, com a justificação. Uma linha por avaliação e critério.

avaliacao_id identificador (UUID) · uuid · obrigatório: Avaliação a que a nota pertence (hub_rh_avaliacoes.id).
criterio_id identificador (UUID) · uuid · obrigatório: Critério avaliado (hub_rh_aval_criterios.id).
nota número inteiro · integer · obrigatório: Nota inteira de 1 até ao máximo da escala da avaliação, 4 ou 5 (hub_rh_avaliacoes.escala).
justificacao texto · text: Justificação da nota, em texto livre.

`hub_rh_aval_objetivos` Objetivos das avaliações

Objetivos definidos numa avaliação para o semestre seguinte (1 a 5 por avaliação), e o resultado registado na avaliação seguinte.

id identificador (UUID) · uuid · obrigatório: Identificador do objetivo.
avaliacao_id identificador (UUID) · uuid · obrigatório: Avaliação que definiu o objetivo (hub_rh_avaliacoes.id).
descricao texto · text · obrigatório: Descrição do objetivo.
prazo data (um dia) · date: Dia até ao qual o objetivo deve estar cumprido.
ordem número inteiro · integer · obrigatório: Posição do objetivo na lista.
resultado texto · text: Resultado apurado na avaliação seguinte: «cumprido», «parcial» ou «nao_cumprido»; vazio enquanto não for revisto.
resultado_comentario texto · text: Comentário sobre o resultado, em texto livre.
revisto_na_avaliacao_id identificador (UUID) · uuid: Avaliação seguinte que registou o resultado (hub_rh_avaliacoes.id).

`hub_rh_aval_propostas` Propostas de aumento ou promoção

Sinal criado automaticamente para os Recursos Humanos quando um colaborador tem duas avaliações concluídas seguidas com nota de 4,0 ou mais (3,0 nas mais antigas), e a decisão tomada. Não propõe valores.

id identificador (UUID) · uuid · obrigatório: Identificador da proposta.
employee_id identificador (UUID) · uuid · obrigatório: Colaborador a que a proposta diz respeito (hub_rh_employees.id).
avaliacao_id identificador (UUID) · uuid · obrigatório: Avaliação concluída que originou a proposta (hub_rh_avaliacoes.id); no máximo uma proposta por avaliação.
tipo texto · text · obrigatório: Tipo de proposta; hoje sempre «aumento_ou_promocao».
estado texto · text · obrigatório: Situação: «pendente», «aceite», «adiada» ou «recusada».
justificacao texto · text: Motivo automático da proposta, com as duas notas que a originaram.
decidido_por identificador (UUID) · uuid: Conta que decidiu (hub_users.id).
decidido_em data e hora, com fuso · timestamp with time zone: Instante da decisão.
created_at data e hora, com fuso · timestamp with time zone: Instante em que a proposta foi criada.
decisao_justificacao texto · text: Justificação escrita por quem decidiu; se a avaliação de origem for anulada, a proposta pendente é recusada e o motivo fica aqui.
adiada_ate data (um dia) · date: Só numa proposta «adiada»: o dia a partir do qual volta a decidir-se (às pendentes e ao aviso do Hub). Vazio nas adiadas de antes desta data e em todas as outras.

`hub_rh_avaliacoes` Avaliações de desempenho

Uma ficha de avaliação de desempenho de um colaborador: período, nota final, discordância e as assinaturas desenhadas no ecrã. Depois de assinada já não muda; só um administrador a anula, com motivo.

id identificador (UUID) · uuid · obrigatório: Identificador da avaliação.
employee_id identificador (UUID) · uuid · obrigatório: Colaborador avaliado (hub_rh_employees.id).
store_id identificador (UUID) · uuid: Loja do colaborador quando a avaliação foi aberta (hub_stores.id).
avaliador_user_id identificador (UUID) · uuid · obrigatório: Conta de quem avalia (hub_users.id).
avaliador_employee_id identificador (UUID) · uuid: Ficha de colaborador de quem avalia (hub_rh_employees.id); vazio se for um administrador sem ficha.
periodo_de data (um dia) · date · obrigatório: Primeiro dia do período avaliado: o dia a seguir à assinatura da avaliação anterior ou, na primeira, a data de admissão.
periodo_ate data (um dia) · date · obrigatório: Último dia do período avaliado: o dia em que a avaliação foi aberta.
estado texto · text · obrigatório: Situação: «rascunho» (em preenchimento), «trancada» (concluída e assinada, já não muda) ou «anulada» (anulada por um administrador, com motivo).
grelha_id identificador (UUID) · uuid · obrigatório: Versão da grelha usada (hub_rh_aval_grelhas.id).
grelha_snapshot JSON · jsonb · obrigatório: Cópia dos critérios da grelha quando a avaliação foi aberta: lista de objetos com «id», «nome», «descricao», «peso» e «ordem».
nota_final número decimal · numeric: Média das notas ponderada pelos pesos dos critérios, truncada a uma casa decimal; calculada ao concluir.
faixa texto · text: Classificação da nota final: «insuficiente», «razoavel», «bom», «muito_bom» ou «excelente» (esta só na escala de 1 a 5).
contributo_anterior texto · text: Apreciação do gerente da loja anterior, quando o colaborador mudou de loja durante o período (texto livre).
discordancia texto · text: Posição do colaborador quando discorda da avaliação, registada antes de assinar.
assinatura_avaliado_path texto · text: Caminho no armazenamento de ficheiros da assinatura do colaborador (imagem PNG); o ficheiro vai na cópia com o índice. Depois de um apagamento a pedido do titular o caminho fica, mas o ficheiro deixa de existir.
assinatura_avaliador_path texto · text: Caminho no armazenamento de ficheiros da assinatura de quem avalia (imagem PNG); o ficheiro vai na cópia com o índice.
assinado_em data e hora, com fuso · timestamp with time zone: Instante em que a avaliação foi assinada e concluída.
anterior_id identificador (UUID) · uuid: Avaliação concluída anterior do mesmo colaborador (hub_rh_avaliacoes.id), cujos objetivos esta revê; vazio na primeira.
anulada_por identificador (UUID) · uuid: Conta que anulou a avaliação (hub_users.id).
anulada_em data e hora, com fuso · timestamp with time zone: Instante da anulação.
anulada_motivo texto · text: Motivo da anulação.
created_at data e hora, com fuso · timestamp with time zone: Instante em que a avaliação foi aberta.
updated_at data e hora, com fuso · timestamp with time zone: Instante da última alteração.
escala número inteiro · smallint · obrigatório: Nota máxima da escala desta avaliação: 4 (avaliações mais antigas, de 1 a 4) ou 5 (de 1 a 5).

`hub_rh_calendar_events` Eventos do calendário de equipa

Eventos livres registados no calendário de equipa dos Recursos Humanos, de uma loja ou de toda a empresa, com a indicação de quem os pode ver.

id identificador (UUID) · uuid · obrigatório: Identificador do evento.
title texto · text · obrigatório: Título do evento.
event_date data (um dia) · date · obrigatório: Dia do evento ou, num intervalo, o primeiro dia.
end_date data (um dia) · date: Último dia do evento; vazio = um só dia.
store_id identificador (UUID) · uuid: Loja a que o evento diz respeito (hub_stores.id); vazio = toda a empresa.
visibility texto · text · obrigatório: Visibilidade escolhida: «rh» (só RH), «gestor» (gestores de loja) ou «todos». Só os marcados «todos» aparecem aos colaboradores na sua área pessoal; no módulo de RH quem vê o calendário vê os três.
notes texto · text: Notas livres.
created_by identificador (UUID) · uuid: Conta que criou o evento (hub_users.id).
created_at data e hora, com fuso · timestamp with time zone: Instante em que o evento foi criado.
updated_at data e hora, com fuso · timestamp with time zone: Instante da última alteração.

`hub_rh_checklist_items` Tarefas de integração e saída

Uma linha por tarefa a cumprir na entrada ou na saída de um colaborador, criada à mão ou copiada de um modelo, com o prazo e se já foi feita.

id identificador (UUID) · uuid · obrigatório: Identificador da tarefa.
employee_id identificador (UUID) · uuid · obrigatório: Colaborador a que a tarefa diz respeito (hub_rh_employees.id).
template_id identificador (UUID) · uuid: Modelo de onde a tarefa foi copiada (hub_rh_checklist_templates.id). Vazio numa tarefa criada à mão.
kind texto · text: Momento: «onboarding» (integração) ou «offboarding» (saída).
task texto · text · obrigatório: Descrição da tarefa.
responsible texto · text: Quem a deve fazer, em texto livre (por exemplo uma função).
done verdadeiro ou falso · boolean · obrigatório: Verdadeiro quando a tarefa está concluída.
due_date data (um dia) · date: Prazo da tarefa.
done_date data (um dia) · date: Dia em que a tarefa foi marcada como concluída.
sort_order número inteiro · integer: Posição da tarefa na lista (ordem crescente).
created_by identificador (UUID) · uuid: Utilizador que criou a tarefa (hub_users.id).
created_at data e hora, com fuso · timestamp with time zone: Instante em que a tarefa foi criada.

`hub_rh_contabilista_envios` Ficheiro do contabilista — meses enviados

Uma linha por cada vez que alguém marcou um mês do ficheiro para o contabilista como enviado (ou deu como enviadas as correções a um mês anterior que o ficheiro de outro mês levou), com a fotografia dos números de cada colaborador nesse momento. Só se acrescenta: marcar outra vez guarda outra linha e vale a última. É o que permite ao ficheiro dos meses seguintes dizer o que mudou num mês já enviado.

id número inteiro · bigint · obrigatório: Identificador do envio.
mes data (um dia) · date · obrigatório: Mês a que o ficheiro diz respeito (o dia 1 desse mês).
enviado_em data e hora, com fuso · timestamp with time zone · obrigatório: Instante em que o mês foi marcado como enviado.
enviado_por identificador (UUID) · uuid: Utilizador que o marcou (hub_users.id); vazio se a conta deixou de existir.
motivo texto · text · obrigatório: «enviado» (o ficheiro deste mês) ou «correcoes_enviadas» (as correções a este mês, levadas no ficheiro de outro mês).
no_ficheiro_de data (um dia) · date: Nas correções, o mês cujo ficheiro as levou (o dia 1 desse mês); vazio num envio do próprio mês.
fotografia JSON · jsonb · obrigatório: Os números de cada colaborador ativo no mês, como estavam no ficheiro marcado: o n.º interno, o nome, o NIF, a loja, os dias de férias, de baixa, de faltas justificadas e injustificadas, os dias de descanso perdidos, as horas extra por tipo, os acertos noturnos e as horas para o banco de horas.

`hub_rh_documents` Documentos dos colaboradores

Uma linha por documento guardado na ficha de um colaborador (contrato, identificação, recibo, certificado…), com o ficheiro e, nos contratos, se falta a assinatura.

id identificador (UUID) · uuid · obrigatório: Identificador do documento.
employee_id identificador (UUID) · uuid · obrigatório: Colaborador a que o documento pertence (hub_rh_employees.id).
doc_type texto · text: Categoria do documento: um valor da lista da Plataforma (por exemplo «Contrato», «Recibo», «Documento Identificação») ou texto livre.
title texto · text · obrigatório: Título do documento.
url texto · text · obrigatório: Caminho do ficheiro no armazenamento de ficheiros; o ficheiro vai na cópia com o índice. Depois de um apagamento a pedido do titular fica «(ficheiro apagado a pedido do titular)».
issued_date data (um dia) · date: Data de emissão do documento, quando indicada (o ecrã atual não a pede).
expiry_date data (um dia) · date: Data de validade do documento, quando indicada (o ecrã atual não a pede).
notes texto · text: Notas em texto livre.
uploaded_by identificador (UUID) · uuid: Utilizador que carregou o documento (hub_users.id).
created_at data e hora, com fuso · timestamp with time zone: Instante em que o documento foi carregado.
precisa_assinatura verdadeiro ou falso · boolean · obrigatório: Verdadeiro quando o documento espera a assinatura do colaborador (acompanhamento em papel, não é assinatura digital).
assinado_em data (um dia) · date: Dia em que o documento foi dado como assinado.

`hub_rh_employees` Fichas de colaborador

Uma linha por colaborador da empresa, atual ou antigo: identificação, contactos, morada, contrato, função, loja, horário semanal, remuneração e datas de admissão e saída.

id identificador (UUID) · uuid · obrigatório: Identificador do colaborador.
internal_code texto · text: Código interno do colaborador na empresa (número de funcionário); único.
full_name texto · text · obrigatório: Nome completo. Depois de um apagamento a pedido do titular fica «Titular apagado AAAA-MM-DD».
birth_date data (um dia) · date: Data de nascimento.
sex texto · text: Sexo: «M» ou «F».
nif texto · text: Número de identificação fiscal (9 dígitos); não se repete entre fichas ativas.
niss texto · text: Número de identificação da segurança social.
nationality texto · text: País da nacionalidade, em texto.
address texto · text: Morada (rua, número, andar).
email texto · text: Endereço de email de contacto do colaborador.
phone texto · text: Número de telefone de contacto.
emergency_contact texto · text: Contacto para emergências (nome e telefone), em texto livre.
contract_type texto · text: Tipo de contrato: um valor da lista da Plataforma («Sem termo», «Termo certo», «Termo incerto», «Estágio», «Prestação de serviços»); fichas antigas podem ter outros.
trial_end_date data (um dia) · date: Último dia do período experimental.
contract_end_date data (um dia) · date: Fim previsto do contrato, nos contratos a termo.
weekly_hours número decimal · numeric · obrigatório: Horas de trabalho por semana do contrato (40 = tempo inteiro).
store_id identificador (UUID) · uuid: Loja ou local onde trabalha atualmente (hub_stores.id).
role_function texto · text: Função: um valor da lista de funções da Plataforma ou texto livre; o nível hierárquico está em nivel_funcao.
admission_date data (um dia) · date · obrigatório: Data de admissão; numa readmissão passa a ser a da nova entrada.
exit_date data (um dia) · date: Data de saída. Vazia enquanto trabalha; uma data futura é uma saída já marcada.
exit_reason texto · text: Motivo da saída: um valor da lista da Plataforma ou texto livre.
base_salary número decimal · numeric: Vencimento base mensal bruto, em euros.
active verdadeiro ou falso · boolean: Falso quando os dados pessoais foram apagados a pedido do titular; verdadeiro nos restantes casos. A saída vê-se em exit_date.
created_at data e hora, com fuso · timestamp with time zone: Instante em que a ficha foi criada.
updated_at data e hora, com fuso · timestamp with time zone: Instante da última alteração da ficha.
created_by identificador (UUID) · uuid: Utilizador que criou a ficha (hub_users.id).
meal_allowance_day número decimal · numeric: Subsídio de refeição por dia de trabalho, em euros.
expense_allowance número decimal · numeric: Ajudas de custo mensais, em euros.
company_car verdadeiro ou falso · boolean: Verdadeiro quando o colaborador tem carro de função.
days_worked_per_week número decimal · numeric: Dias de trabalho por semana; base do subsídio de refeição no cálculo do custo.
postal_code texto · text: Código postal da morada (formato 0000-000).
locality texto · text: Localidade da morada.
id_doc_type texto · text: Tipo do documento de identificação: um valor da lista da Plataforma (por exemplo «Cartão de Cidadão», «Passaporte») ou texto livre.
id_doc_number texto · text: Número do documento de identificação.
has_disability verdadeiro ou falso · boolean: Verdadeiro quando o colaborador tem necessidades especiais ou deficiência declarada.
id_doc_expiry data (um dia) · date: Data de validade do documento de identificação.
role_supplement número decimal · numeric: Suplemento de função mensal, em euros.
role_supplement_until data (um dia) · date: Último dia em que o suplemento de função é pago. Vazio = sem fim.
iht número decimal · numeric: Retribuição mensal por isenção de horário de trabalho, em euros.
cash_allowance número decimal · numeric: Abono para falhas de caixa mensal, em euros.
manager_id identificador (UUID) · uuid: Chefia direta (hub_rh_employees.id). Campo antigo: o ecrã já não o preenche; a hierarquia vem de nivel_funcao.
internal_notes texto · text: Notas internas dos recursos humanos sobre o colaborador, em texto livre; cada consulta fica registada.
special_needs_note texto · text: Descrição das necessidades especiais, só quando has_disability é verdadeiro.
admission_store_id identificador (UUID) · uuid: Loja onde o colaborador entrou (hub_stores.id); não muda com transferências, só numa readmissão.
exit_store_id identificador (UUID) · uuid: Loja onde estava no momento em que a saída foi registada (hub_stores.id).
pre_admission verdadeiro ou falso · boolean: Verdadeiro enquanto a admissão está em processamento: a ficha existe mas a pessoa ainda não conta no efetivo.
categoria_profissional texto · text: Categoria profissional do contrato, distinta da função: um valor da lista da Plataforma ou texto livre.
iban texto · text: IBAN da conta bancária do colaborador.
meal_allowance_type texto · text: Forma de pagamento do subsídio de refeição: «cartao» (cartão refeição) ou «remuneracao» (junto do vencimento).
photo_path texto · text: Caminho da fotografia do colaborador no armazenamento de ficheiros; o ficheiro vai na cópia com o índice.
marital_status texto · text: Estado civil: «Solteiro/a», «Casado/a», «União de facto», «Divorciado/a» ou «Viúvo/a».
dependents_count número inteiro · integer: Número de dependentes.
distrito texto · text: Distrito da morada.
concelho texto · text: Concelho (município) da morada.
nivel_funcao texto · text: Nível hierárquico a que a função equivale: «loja», «chefia_turno», «subgerente», «gerente», «supervisor», «escritorio» ou «direcao». Decide o organigrama e quem aprova.
dias_descanso lista de números inteiros · _int2: Dias de descanso semanal, de 1 (segunda-feira) a 7 (domingo), entre 1 e 6 dias. Vazio = sábado e domingo. Contam no cálculo dos dias de férias.
ferias_saldo_inicial_ano número inteiro · integer: Para quem já trabalhava na empresa antes de usar a plataforma: o ano a partir do qual as férias se contam aqui. Vazio = desde a admissão.
ferias_saldo_inicial número decimal · numeric: Os dias de férias que transitaram para esse ano, vindos de antes da plataforma (de 0 a 60). Vem preenchido junto com o ano, ou nenhum dos dois.

`hub_rh_exit_forms` Registos de saída

Uma linha por saída registada de um colaborador: data, motivo, aviso prévio e observações. Uma pessoa readmitida e que volte a sair tem mais do que uma.

id identificador (UUID) · uuid · obrigatório: Identificador do registo de saída.
employee_id identificador (UUID) · uuid: Colaborador que saiu (hub_rh_employees.id).
exit_date data (um dia) · date · obrigatório: Data de saída.
reason texto · text: Motivo da saída: um valor da lista da Plataforma ou texto livre.
notice_given texto · text: Aviso prévio, em JSON com «devidos» e «cumpridos» (número de dias); registos antigos podem ter texto livre.
notes texto · text: Observações em texto livre.
created_at data e hora, com fuso · timestamp with time zone: Instante em que a saída foi registada.
created_by identificador (UUID) · uuid: Utilizador que registou a saída (hub_users.id).

`hub_rh_hour_bank` Movimentos do banco de horas

Uma linha por movimento no banco de horas de um colaborador: crédito de horas trabalhadas a mais ou débito de horas gozadas. O saldo é a soma dos movimentos.

id identificador (UUID) · uuid · obrigatório: Identificador do movimento.
employee_id identificador (UUID) · uuid · obrigatório: Colaborador (hub_rh_employees.id).
entry_date data (um dia) · date · obrigatório: Dia a que o movimento se refere; nos movimentos automáticos, o dia trabalhado.
hours número decimal · numeric · obrigatório: Horas do movimento: positivo = crédito, negativo = horas gozadas.
reason texto · text: Motivo, em texto livre; nos movimentos automáticos, «Horas extra para banco de horas».
notes texto · text: Notas em texto livre.
created_by identificador (UUID) · uuid: Utilizador que registou o movimento (hub_users.id); nos automáticos, quem aprovou as horas extra.
created_at data e hora, com fuso · timestamp with time zone: Instante em que o movimento foi criado.
overtime_id identificador (UUID) · uuid: Horas extra que geraram o movimento (hub_rh_overtime.id), quando aprovadas com destino «banco»; o movimento acompanha-as e não se edita à mão.

`hub_rh_movimentos` Transferências e promoções

Uma linha por transferência de loja ou promoção de um colaborador, com a data a partir da qual conta (passada ou futura), o que era antes e o que passou a ser, e quem a registou. Uma anulada fica, com o motivo. É a história da loja, da função e da categoria profissional de cada pessoa; a ficha guarda a de hoje.

id identificador (UUID) · uuid · obrigatório: Identificador do registo.
employee_id identificador (UUID) · uuid · obrigatório: Colaborador (hub_rh_employees.id).
tipo texto · text · obrigatório: «transferencia» (mudança de loja) ou «promocao» (mudança de função ou de categoria profissional).
data_efeito data (um dia) · date · obrigatório: Dia a partir do qual a mudança conta.
loja_de identificador (UUID) · uuid: Numa transferência, a loja de onde saiu (hub_stores.id).
loja_para identificador (UUID) · uuid: Numa transferência, a loja para onde foi (hub_stores.id).
funcao_de texto · text: Numa promoção, a função de antes.
funcao_para texto · text: Numa promoção, a função nova.
nivel_de texto · text: Numa promoção, o nível da função de antes (loja, chefia de turno, gerente…).
nivel_para texto · text: Numa promoção, o nível da função nova.
categoria_de texto · text: Numa promoção, a categoria profissional de antes.
categoria_para texto · text: Numa promoção, a categoria profissional nova.
notas texto · text: Notas em texto livre. Apagado a pedido do titular: vazio.
origem texto · text · obrigatório: Como foi registada: «ecra» (os botões da ficha), «ficha» (a loja mudada por outro caminho, registada sozinha) ou «historico» (uma mudança de loja de antes de 29/10/2026, tirada do histórico da ficha).
criado_por identificador (UUID) · uuid: Conta que a registou (hub_users.id).
criado_em data e hora, com fuso · timestamp with time zone · obrigatório: Instante do registo.
aplicado_em data e hora, com fuso · timestamp with time zone: Instante em que passou à ficha; vazio enquanto a data ainda não chegou.
anulado_em data e hora, com fuso · timestamp with time zone: Instante em que foi anulada; vazio = em vigor.
anulado_por identificador (UUID) · uuid: Conta que a anulou (hub_users.id).
anulado_motivo texto · text: Motivo da anulação, em texto livre. Apagado a pedido do titular: «(apagado a pedido do titular)».

`hub_rh_overtime` Horas extra

Uma linha por registo de trabalho suplementar de um colaborador num dia (horário, divisão das horas por tipo, aprovação e destino) ou por acerto de horas noturnas normais.

id identificador (UUID) · uuid · obrigatório: Identificador do registo.
employee_id identificador (UUID) · uuid: Colaborador que fez as horas (hub_rh_employees.id).
work_date data (um dia) · date · obrigatório: Dia trabalhado; um horário que passa da meia-noite conta todo no dia de início.
hours número decimal · numeric · obrigatório: Total de horas do registo; num acerto noturno, as horas noturnas acrescentadas.
kind texto · text: Tipo de dia no formato antigo: «normal», «descanso» ou «feriado». Mantido por compatibilidade; o atual é day_type.
start_time hora do dia · time without time zone: Hora de início. Vazia num acerto noturno.
end_time hora do dia · time without time zone: Hora de fim; menor que start_time quando passa da meia-noite. Vazia num acerto noturno.
day_type texto · text: Tipo de dia: «util», «descanso» ou «feriado». Vazio num acerto noturno.
h_feriado número decimal · numeric · obrigatório: Horas trabalhadas em dia feriado, fora do período noturno.
h_descanso número decimal · numeric · obrigatório: Horas trabalhadas em dia de descanso, fora do período noturno.
h_noturnas número decimal · numeric · obrigatório: Horas noturnas normais (não suplementares); só preenchidas num acerto noturno.
h_noturnas_extra número decimal · numeric · obrigatório: Horas extra dentro do período noturno definido nos parâmetros de RH (noturno_inicio_min e noturno_fim_min; semeado das 00:00 às 07:00).
h_50 número decimal · numeric · obrigatório: Horas da primeira hora extra de um dia útil, com a primeira majoração (50 % por omissão); no máximo 1 por dia.
h_75 número decimal · numeric · obrigatório: Horas extra seguintes num dia útil, com a segunda majoração (75 % por omissão).
status texto · text · obrigatório: Estado da aprovação: «pendente», «aprovada» ou «recusada».
created_by identificador (UUID) · uuid: Utilizador que registou as horas (hub_users.id).
created_at data e hora, com fuso · timestamp with time zone · obrigatório: Instante em que o registo foi criado.
decided_by identificador (UUID) · uuid: Utilizador que aprovou ou recusou (hub_users.id).
decided_at data e hora, com fuso · timestamp with time zone: Instante da decisão.
decision_reason texto · text: Nota de quem decidiu; obrigatória ao recusar (o motivo da recusa).
approver_user_id identificador (UUID) · uuid: Utilizador designado para aprovar, calculado ao gravar (hub_users.id). Vazio = só administradores decidem.
is_night_adjust verdadeiro ou falso · boolean · obrigatório: Verdadeiro num acerto de horas noturnas normais, que não é trabalho suplementar.
edited_by lista de identificadores · _uuid · obrigatório: Utilizadores que editaram o registo enquanto estava por aprovar (lista de hub_users.id); nenhum deles passa a ser o aprovador designado (os administradores e o Diretor continuam a poder decidir).
destino texto · text · obrigatório: Destino das horas: «pagamento» ou «banco» (vão para o banco de horas e não se pagam).

`hub_rh_pay_items` Outros vencimentos

Uma linha por componente de remuneração de um colaborador além das que estão na ficha (subsídio, prémio, comissão…), mensal ou pontual.

id identificador (UUID) · uuid · obrigatório: Identificador do vencimento.
employee_id identificador (UUID) · uuid: Colaborador (hub_rh_employees.id).
label texto · text · obrigatório: Descrição do vencimento.
amount número decimal · numeric · obrigatório: Valor bruto em euros: por mês se é recorrente, uma única vez se é pontual.
kind texto · text: Tipo: um valor da lista da Plataforma («subsídio», «prémio», «comissão») ou texto livre.
recurring verdadeiro ou falso · boolean: Verdadeiro = pago todos os meses; falso = pagamento pontual.

`hub_rh_pedidos` Pedidos de férias e ausência

Uma linha por pedido de férias ou de ausência feito pelo próprio colaborador no portal. Um pedido aprovado dá origem a um período em hub_rh_vacation_records ou a uma ausência em hub_rh_absences.

id identificador (UUID) · uuid · obrigatório: Identificador do pedido.
employee_id identificador (UUID) · uuid · obrigatório: Colaborador que pede (hub_rh_employees.id).
tipo texto · text · obrigatório: Tipo: «ferias» ou «ausencia».
start_date data (um dia) · date · obrigatório: Primeiro dia pedido.
end_date data (um dia) · date · obrigatório: Último dia pedido, inclusive.
motivo texto · text: Motivo escrito pelo colaborador.
estado texto · text · obrigatório: Estado: «pendente», «aprovado», «recusado» ou «cancelado» (retirado pelo colaborador).
decided_by identificador (UUID) · uuid: Utilizador que aprovou ou recusou (hub_users.id).
decided_at data e hora, com fuso · timestamp with time zone: Instante da decisão.
decisao_nota texto · text: Nota de quem decidiu.
created_by identificador (UUID) · uuid · obrigatório: Conta que fez o pedido (hub_users.id).
created_at data e hora, com fuso · timestamp with time zone · obrigatório: Instante em que o pedido foi feito.

`hub_rh_ponto_avisos` Registo de ponto — avisos à chefia

Uma linha por dia e por pessoa da chefia avisada de que há pedidos de correção do registo de ponto por decidir: quem, o dia e a situação do aviso por email. Não leva o pedido nem o nome de quem pediu; o pedido vive nas correções do ponto.

id número inteiro · bigint · obrigatório: Identificador do aviso.
user_id identificador (UUID) · uuid · obrigatório: Conta da pessoa da chefia avisada (hub_users.id).
dia data (um dia) · date · obrigatório: Dia do aviso (há no máximo um por pessoa e por dia).
criado_em data e hora, com fuso · timestamp with time zone · obrigatório: Instante em que o aviso foi criado.
email_para texto · text: Endereço para onde vai o aviso por email; vazio se a conta não tinha email.
email_estado texto · text · obrigatório: Situação do aviso por email: «sem_email», «por_enviar», «pedido» (entregue ao serviço de email, à espera da resposta), «enviado» ou «falhou».
email_pedido_em data e hora, com fuso · timestamp with time zone: Instante em que o aviso por email foi entregue ao serviço de email.

Não vão na cópia: email_pedido_id (dados de licença, de versão ou registos técnicos que não resultam do uso da empresa (cláusula 17.7, alínea d))); email_erro (dados de licença, de versão ou registos técnicos que não resultam do uso da empresa (cláusula 17.7, alínea d))).

`hub_rh_ponto_correcoes` Registo de ponto — correções

Uma linha por correção de uma marcação: pedida pelo colaborador ou lançada pela chefia, com o motivo e a decisão. Nada se apaga: uma correção aprovada acrescenta uma marcação nova ou anula uma antiga, e fica a correção como prova.

id identificador (UUID) · uuid · obrigatório: Identificador da correção.
employee_id identificador (UUID) · uuid · obrigatório: Colaborador cujo ponto se corrige (hub_rh_employees.id).
tipo texto · text · obrigatório: «acrescentar» (uma marcação que faltou), «alterar» (outra hora ou outro tipo) ou «anular».
marcacao_id identificador (UUID) · uuid: Marcação corrigida (hub_rh_ponto_marcacoes.id); vazio ao acrescentar.
novo_tipo texto · text: «entrada» ou «saida» da marcação nova; vazio ao anular.
novo_momento data e hora, com fuso · timestamp with time zone: Instante da marcação nova; vazio ao anular.
motivo texto · text · obrigatório: Porque se corrige, em texto livre (3 a 500 caracteres).
origem texto · text · obrigatório: «colaborador» (pedida na Área pessoal) ou «chefia» (lançada no RH).
pedido_por identificador (UUID) · uuid · obrigatório: Conta que pediu ou lançou a correção (hub_users.id).
pedido_em data e hora, com fuso · timestamp with time zone · obrigatório: Instante do pedido.
estado texto · text · obrigatório: «pendente», «aprovada», «recusada» ou «cancelada» (pelo próprio, antes da decisão).
decidido_por identificador (UUID) · uuid: Conta que decidiu (hub_users.id); nunca o próprio colaborador.
decidido_em data e hora, com fuso · timestamp with time zone: Instante da decisão; vazio enquanto pendente.
decisao_nota texto · text: Nota de quem decidiu, em texto livre.

`hub_rh_ponto_marcacoes` Registo de ponto — marcações

Uma linha por marcação de entrada ou de saída de um colaborador, com a hora do servidor e a forma como foi feita. As marcações só se acrescentam: nenhuma se altera nem se apaga; uma correção aprovada acrescenta outra.

id identificador (UUID) · uuid · obrigatório: Identificador da marcação.
employee_id identificador (UUID) · uuid · obrigatório: Colaborador (hub_rh_employees.id).
tipo texto · text · obrigatório: «entrada» ou «saida».
momento data e hora, com fuso · timestamp with time zone · obrigatório: Instante da marcação (a hora do servidor; numa correção, a hora aprovada).
registado_em data e hora, com fuso · timestamp with time zone · obrigatório: Instante em que a linha foi gravada.
origem texto · text · obrigatório: Como foi feita: «quiosque» (tablet com PIN), «telemovel_qr» (telemóvel com o QR do tablet), «telemovel» (telemóvel sem QR) ou «correcao».
store_id identificador (UUID) · uuid: Loja da marcação (hub_stores.id): a do tablet, ou a do colaborador.
quiosque_id identificador (UUID) · uuid: Tablet onde se marcou ou cujo QR se leu (hub_rh_ponto_quiosques.id).
user_id identificador (UUID) · uuid: Conta que marcou no telemóvel (hub_users.id); vazio no tablet.
correcao_id identificador (UUID) · uuid: Correção que acrescentou esta marcação (hub_rh_ponto_correcoes.id).

`hub_rh_questionarios` Questionários de saída

Uma linha por questionário de saída pedido para quem saiu por iniciativa própria: para que saída, para onde foi o email e quando, e as respostas, se a pessoa respondeu. O código do endereço pessoal, a referência e o erro do serviço de email não vão na cópia. Apagam-se com os dados do titular, a pedido dele.

id identificador (UUID) · uuid · obrigatório: Identificador do questionário.
employee_id identificador (UUID) · uuid · obrigatório: Colaborador que saiu (hub_rh_employees.id).
exit_date data (um dia) · date · obrigatório: Data da saída a que o questionário se refere.
versao texto · text · obrigatório: Versão das perguntas (por exemplo «v1»); as respostas leem-se pelas perguntas dessa versão.
endereco texto · text · obrigatório: Endereço da empresa na plataforma, de onde se monta o link do email.
email_para texto · text: Endereço para onde foi (ou vai) o email; vazio se a ficha não tinha email.
enviar_a_partir_de data (um dia) · date · obrigatório: Dia a partir do qual o email sai (o da saída, ou o do pedido se a saída já passou).
expira_em data e hora, com fuso · timestamp with time zone: Instante até ao qual o endereço pessoal serve (30 dias depois do envio).
email_estado texto · text · obrigatório: Situação do email: «por_enviar», «pedido» (entregue ao serviço de email, à espera da resposta), «enviado», «falhou», «sem_email» ou «cancelado».
email_pedido_em data e hora, com fuso · timestamp with time zone: Instante em que o email foi entregue ao serviço de email.
enviado_em data e hora, com fuso · timestamp with time zone: Instante em que o email foi enviado.
respostas JSON · jsonb: As respostas, em JSON: o identificador de cada pergunta e a resposta (a opção escolhida, um número de 1 a 5 ou o texto).
respondido_em data e hora, com fuso · timestamp with time zone: Instante da resposta; vazio = por responder.
pedido_por identificador (UUID) · uuid: Conta que pediu o questionário (hub_users.id).
pedido_em data e hora, com fuso · timestamp with time zone · obrigatório: Instante do pedido.

Não vão na cópia: token_hash (dados de segurança do acesso (cláusula 17.7, alínea b))); email_pedido_id (dados de licença, de versão ou registos técnicos que não resultam do uso da empresa (cláusula 17.7, alínea d))); email_erro (dados de licença, de versão ou registos técnicos que não resultam do uso da empresa (cláusula 17.7, alínea d))).

`hub_rh_shift_requirements` Necessidades de cobertura das escalas

Turnos necessários por loja e dia da semana, das antigas escalas de turnos; o último gerador de escalas já não os usava. Os dados que existam ficam guardados.

id identificador (UUID) · uuid · obrigatório: Identificador da linha.
store_id identificador (UUID) · uuid · obrigatório: Loja (hub_stores.id).
weekday número inteiro · smallint · obrigatório: Dia da semana: 0 = segunda-feira … 6 = domingo.
count número inteiro · integer · obrigatório: Número de turnos iguais necessários (1 ou mais).
created_by identificador (UUID) · uuid: Conta que criou a linha (hub_users.id).
created_at data e hora, com fuso · timestamp with time zone: Instante em que a linha foi criada.
start_time hora do dia · time without time zone: Hora de início do turno necessário.
net_minutes número inteiro · integer: Duração do turno sem a pausa, em minutos.
break_minutes número inteiro · integer · obrigatório: Pausa do turno, em minutos.

`hub_rh_shift_templates` Modelos de turno

Modelos de turno (nome e horário) para preencher as antigas escalas, de uma loja ou de todas. Já não eram usados quando as escalas saíram da plataforma; os dados ficam guardados.

id identificador (UUID) · uuid · obrigatório: Identificador do modelo.
store_id identificador (UUID) · uuid: Loja do modelo (hub_stores.id); vazio = modelo para todas as lojas.
label texto · text · obrigatório: Nome do modelo de turno.
start_time hora do dia · time without time zone · obrigatório: Hora de início do horário base.
end_time hora do dia · time without time zone · obrigatório: Hora de fim do horário base; anterior ao início = o turno acaba no dia seguinte.
active verdadeiro ou falso · boolean · obrigatório: Se o modelo está ativo.
created_by identificador (UUID) · uuid: Conta que criou o modelo (hub_users.id).
created_at data e hora, com fuso · timestamp with time zone: Instante em que o modelo foi criado.
day_times JSON · jsonb: Horário diferente por dia da semana: chaves «0» (segunda) a «6» (domingo), cada uma com «start» e «end» (HH:MM); os dias sem chave usam o horário base.

`hub_rh_shift_weeks` Estado semanal das escalas

Estado da escala de cada loja em cada semana, das antigas escalas de turnos. Uma linha por loja e semana; os dados que existam ficam guardados.

store_id identificador (UUID) · uuid · obrigatório: Loja (hub_stores.id).
week_start data (um dia) · date · obrigatório: Segunda-feira da semana.
status texto · text · obrigatório: «rascunho» (em preparação) ou «publicada» (fechada e visível aos colaboradores).
published_by identificador (UUID) · uuid: Conta que publicou a escala (hub_users.id).
published_at data e hora, com fuso · timestamp with time zone: Instante da publicação.

`hub_rh_shifts` Turnos das escalas

Turnos atribuídos a colaboradores, por loja e dia, das antigas escalas de trabalho. Já não têm ecrã na plataforma; os dados que existam ficam guardados.

id identificador (UUID) · uuid · obrigatório: Identificador do turno.
store_id identificador (UUID) · uuid · obrigatório: Loja do turno (hub_stores.id).
employee_id identificador (UUID) · uuid · obrigatório: Colaborador escalado (hub_rh_employees.id).
work_date data (um dia) · date · obrigatório: Dia do turno.
start_time hora do dia · time without time zone · obrigatório: Hora de entrada.
end_time hora do dia · time without time zone · obrigatório: Hora de saída; anterior à entrada = o turno acaba no dia seguinte.
label texto · text: Etiqueta opcional em texto livre, por exemplo «abertura», «fecho» ou «intermédio».
notes texto · text: Notas livres.
created_by identificador (UUID) · uuid: Conta que criou o turno (hub_users.id).
created_at data e hora, com fuso · timestamp with time zone: Instante em que o turno foi criado.
updated_at data e hora, com fuso · timestamp with time zone: Instante da última alteração.
break_minutes número inteiro · integer · obrigatório: Pausa em minutos, descontada ao tempo de presença para calcular as horas de trabalho.

`hub_rh_trainings` Formação dos colaboradores

Uma linha por ação de formação frequentada por um colaborador, com a entidade, as datas, as horas, o custo e se obteve certificado.

id identificador (UUID) · uuid · obrigatório: Identificador do registo de formação.
employee_id identificador (UUID) · uuid · obrigatório: Colaborador formado (hub_rh_employees.id).
title texto · text · obrigatório: Designação da ação de formação.
area texto · text: Área ou temática, em texto livre.
modality texto · text: Modalidade: «Presencial», «Online» ou «Misto».
entity texto · text: Entidade formadora.
start_date data (um dia) · date: Primeiro dia da formação.
end_date data (um dia) · date: Último dia da formação.
hours número decimal · numeric: Duração da formação, em horas.
certified verdadeiro ou falso · boolean · obrigatório: Verdadeiro quando o colaborador obteve certificado.
cost número decimal · numeric: Custo da formação, em euros.
notes texto · text: Notas em texto livre.
created_by identificador (UUID) · uuid: Utilizador que fez o registo (hub_users.id).
created_at data e hora, com fuso · timestamp with time zone: Instante em que o registo foi criado.

`hub_rh_trocas_turno` Pedidos de troca de turno

Pedidos de um colaborador para passar um turno seu a um colega da mesma loja: o colega aceita e a gestão aprova. Guardam uma cópia do turno; já não têm ecrã na plataforma.

id identificador (UUID) · uuid · obrigatório: Identificador do pedido.
shift_id identificador (UUID) · uuid: Turno pedido (hub_rh_shifts.id); vazio se o turno foi apagado.
de_employee_id identificador (UUID) · uuid · obrigatório: Colaborador que cede o turno (hub_rh_employees.id).
para_employee_id identificador (UUID) · uuid · obrigatório: Colega que recebe o turno (hub_rh_employees.id).
store_id identificador (UUID) · uuid · obrigatório: Loja do turno no momento do pedido (hub_stores.id).
work_date data (um dia) · date · obrigatório: Dia do turno no momento do pedido.
start_time hora do dia · time without time zone · obrigatório: Hora de entrada do turno no momento do pedido.
end_time hora do dia · time without time zone · obrigatório: Hora de saída do turno no momento do pedido.
motivo texto · text: Motivo indicado por quem pede.
estado texto · text · obrigatório: «aguarda_colega», «pendente» (o colega aceitou; espera a gestão), «aprovada», «recusada_colega», «recusada» (pela gestão) ou «cancelada» (por quem pediu).
decided_by identificador (UUID) · uuid: Conta que aprovou ou recusou o pedido na gestão (hub_users.id).
decided_at data e hora, com fuso · timestamp with time zone: Instante da decisão da gestão.
decisao_nota texto · text: Nota da gestão sobre a decisão.
created_by identificador (UUID) · uuid · obrigatório: Conta de quem fez o pedido (hub_users.id).
created_at data e hora, com fuso · timestamp with time zone · obrigatório: Instante do pedido.

`hub_rh_vacation_records` Períodos de férias

Uma linha por período de férias gozado ou marcado por um colaborador. Os dias gozados de cada ano e o saldo de férias calculam-se a partir destas linhas.

id identificador (UUID) · uuid · obrigatório: Identificador do período.
employee_id identificador (UUID) · uuid: Colaborador (hub_rh_employees.id).
year número inteiro · integer · obrigatório: Ano a que o período conta no saldo de férias (o ano do primeiro dia).
start_date data (um dia) · date · obrigatório: Primeiro dia de férias.
end_date data (um dia) · date · obrigatório: Último dia de férias, inclusive.
days número decimal · numeric · obrigatório: Dias úteis de férias gastos no período: os dias de trabalho da pessoa, sem feriados; pode ter meios dias.
notes texto · text: Notas em texto livre; num pedido aprovado no portal, a indicação disso e da data.
updated_at data e hora, com fuso · timestamp with time zone · obrigatório: Instante da última alteração; serve para recusar a gravação de quem editou uma versão já ultrapassada.

`hub_rh_vacations` Saldos de férias antigos

Tabela antiga com uma linha por colaborador e ano: dias de férias a que tinha direito e dias gozados. O ecrã já não a usa; os períodos gozados estão em hub_rh_vacation_records e o direito é calculado.

id identificador (UUID) · uuid · obrigatório: Identificador da linha.
employee_id identificador (UUID) · uuid: Colaborador (hub_rh_employees.id).
year número inteiro · integer · obrigatório: Ano civil do saldo.
entitled_days número decimal · numeric · obrigatório: Dias úteis de férias a que o colaborador tinha direito nesse ano.
taken_days número decimal · numeric · obrigatório: Dias de férias gozados nesse ano, escritos à mão.

Tesouraria, e-Fatura e fechos financeiros

`efatura_history` Histórico importado do e-Fatura

Uma linha por documento de compra comunicado à Autoridade Tributária, importado dos ficheiros exportados do portal e-Fatura. Serve para comparar com as faturas registadas e encontrar as que faltam.

id número inteiro · bigint · obrigatório: Identificador da linha.
nif texto · text: NIF do emitente (o fornecedor).
name texto · text: Nome do emitente, tal como no portal.
num texto · text: Número do documento tal como no portal (pode trazer o ATCUD a seguir a « / »); único por NIF.
date data (um dia) · date: Data de emissão do documento (dia).
amount número decimal · numeric: Total do documento com IVA, em euros; negativo nas notas de crédito das importações atuais (linhas de importações antigas podem tê-lo positivo — é «type» que diz se é nota de crédito).
iva número decimal · numeric: Valor do IVA, em euros; negativo nas notas de crédito das importações atuais (linhas de importações antigas podem tê-lo positivo).
type texto · text: Tipo de documento tal como no portal (por exemplo «Fatura», «Fatura-recibo» ou «Nota de crédito»).
imported_at data e hora, com fuso · timestamp with time zone: Instante da importação do ficheiro.

`fatura_rateio` Rateio das faturas por loja

Uma linha por loja ou centro de custo que suporta parte de uma fatura, com a percentagem; as linhas de uma fatura somam 100. Sem rateio, o custo vai para a loja do documento lido.

fatura_id número inteiro · bigint · obrigatório: Fatura repartida (faturas.id).
store_id identificador (UUID) · uuid · obrigatório: Loja ou centro de custo que suporta a parte (hub_stores.id).
pct número decimal · numeric · obrigatório: Percentagem da fatura imputada a esta loja, maior que 0 e até 100.

`faturas` Faturas de fornecedores na tesouraria

Uma linha por fatura ou nota de crédito de fornecedor a pagar ou já paga, lançada à mão ou a partir de um documento lido. É a base dos vencimentos, dos pagamentos e da comparação com o e-Fatura.

id número inteiro · bigint · obrigatório: Identificador da fatura.
supplier_id número inteiro · bigint: Fornecedor (suppliers.id); vazio quando ainda não foi identificado.
num texto · text: Número do documento com a série; único por fornecedor.
date data (um dia) · date: Data de emissão (dia).
due data (um dia) · date: Data de vencimento (dia).
amount número decimal · numeric: Total com IVA, em euros; negativo numa nota de crédito, positivo ou zero nos outros documentos.
descricao texto · text: Descrição livre; «[OCR] nome lido» quando a leitura não reconheceu o fornecedor.
status texto · text: Situação: «pendente» (por pagar, incluindo as pagas em parte) ou «pago».
created_at data e hora, com fuso · timestamp with time zone: Instante em que a fatura foi criada.
document_id identificador (UUID) · uuid: Documento lido de onde a fatura foi lançada (documents.id); vazio nas lançadas à mão.
document_type texto · text: Tipo de documento: «fatura» ou «nota_credito».
amount_net número decimal · numeric: Total sem IVA, em euros, com o mesmo sinal do total.
amount_vat número decimal · numeric: Valor do IVA, em euros, com o mesmo sinal do total.
updated_at data e hora, com fuso · timestamp with time zone · obrigatório: Instante da última alteração; serve também para recusar gravações de quem editou uma versão antiga.
retencao número decimal · numeric · obrigatório: Retenção na fonte (IRS ou IRC), em euros, com o mesmo sinal do total; 0 quando não há. Ao fornecedor paga-se o total menos a retenção; a retenção entrega-se ao Estado até ao dia 20 do mês seguinte ao do pagamento.

`hub_fch_ajustes` Correções de depósitos de numerário

Uma linha por depósito de numerário que alguém corrigiu nos fechos financeiros: passado para outra loja e/ou outro dia (a data estava mal escrita no texto do banco) ou ignorado (linha duplicada). Sem correção, a linha vale pelo texto do banco.

movimento_id número inteiro · bigint · obrigatório: Movimento do banco corrigido (hub_fch_movimentos.id); uma correção por movimento.
store_id identificador (UUID) · uuid: Loja para onde a linha passa; vazio quando a linha é ignorada.
dia data (um dia) · date: Dia a que a linha passa; vazio quando a linha é ignorada.
ignorar verdadeiro ou falso · boolean · obrigatório: Verdadeiro quando a linha é ignorada (por exemplo, uma duplicada).
nota texto · text: Nota livre de quem corrigiu (até 200 caracteres).
criado_por identificador (UUID) · uuid · obrigatório: Conta que fez a correção (hub_users.id).
criado_em data e hora, com fuso · timestamp with time zone · obrigatório: Instante da correção.

`hub_fch_aliases` Apelidos das lojas nos depósitos

Uma linha por apelido de loja que aparece no texto dos depósitos de numerário do banco (por exemplo «camoes») e a loja da empresa a que corresponde. Serve para atribuir cada depósito à sua loja.

id identificador (UUID) · uuid · obrigatório: Identificador do apelido.
alias texto · text · obrigatório: Apelido normalizado (minúsculas, sem acentos nem números de máquina ou talão); único.
store_id identificador (UUID) · uuid · obrigatório: Loja da empresa (hub_stores.id) a que o apelido corresponde.
origem texto · text · obrigatório: «manual» se uma pessoa o escreveu; «sugestao» se aceitou a sugestão do sistema ou carregou em «Aprender os nomes»; «automatico» se o sistema o aprendeu sozinho numa importação.
criado_por identificador (UUID) · uuid · obrigatório: Conta que ligou o apelido (hub_users.id).
criado_em data e hora, com fuso · timestamp with time zone · obrigatório: Instante em que o apelido foi ligado.

`hub_fch_aliases_recusados` Apelidos desligados das lojas

Uma linha por par apelido–loja que uma pessoa desligou nos fechos financeiros. O Zarvo não volta a ligar esse apelido a essa loja sozinho; se uma pessoa o voltar a ligar, a linha sai.

alias texto · text · obrigatório: Apelido normalizado, como em hub_fch_aliases.
store_id identificador (UUID) · uuid · obrigatório: Loja de que o apelido foi desligado (hub_stores.id).
recusado_por identificador (UUID) · uuid · obrigatório: Conta que o desligou (hub_users.id).
recusado_em data e hora, com fuso · timestamp with time zone · obrigatório: Instante em que foi desligado.

`hub_fch_contas` Contas bancárias dos fechos financeiros

Uma linha por conta bancária da empresa cujos extratos se importam nos fechos financeiros. Guarda o banco, um nome escolhido pela empresa, os quatro últimos dígitos e uma impressão digital da conta; o número completo nunca é guardado.

id identificador (UUID) · uuid · obrigatório: Identificador da conta.
banco texto · text · obrigatório: Banco da conta: BPI, BCP ou BST.
alias texto · text · obrigatório: Nome dado pela empresa à conta, para a reconhecer.
ultimos_digitos texto · text · obrigatório: Os quatro últimos dígitos da conta (só para a mostrar).
chave texto · text · obrigatório: Impressão digital (SHA-256) do banco e do número da conta, para reconhecer um extrato da mesma conta sem guardar o número.
ativo verdadeiro ou falso · boolean · obrigatório: Falso quando a conta foi desativada e já não aceita extratos.
criado_por identificador (UUID) · uuid · obrigatório: Conta que registou a conta bancária (hub_users.id).
criado_em data e hora, com fuso · timestamp with time zone · obrigatório: Instante do registo.

`hub_fch_importacoes` Importações dos fechos financeiros

Uma linha por ficheiro importado nos fechos financeiros — o relatório do POS ou um extrato bancário: o nome, a impressão digital (para nunca importar o mesmo ficheiro duas vezes), o período que cobre, quem o importou e onde o original ficou guardado.

id identificador (UUID) · uuid · obrigatório: Identificador da importação.
tipo texto · text · obrigatório: «pos» (relatório «Fechos Financeiros» do POS) ou «extrato» (extrato bancário).
nome texto · text · obrigatório: Nome do ficheiro tal como foi escolhido (números longos escondidos).
sha256 texto · text · obrigatório: Impressão digital (SHA-256) do conteúdo do ficheiro; única por tipo.
tamanho número inteiro · integer · obrigatório: Tamanho do ficheiro, em bytes.
periodo_de data (um dia) · date · obrigatório: Primeiro dia com valores ou movimentos no ficheiro.
periodo_ate data (um dia) · date · obrigatório: Último dia com valores ou movimentos no ficheiro.
lojas lista de números inteiros · _int2 · obrigatório: Números das lojas no POS que o relatório cobre (vazio nos extratos).
n_dias número inteiro · integer · obrigatório: Quantos dias de loja (POS) ou dias com movimentos (extrato) o ficheiro trouxe.
n_valores número inteiro · integer · obrigatório: Quantos valores (POS) ou movimentos (extrato) o ficheiro trouxe.
avisos JSON · jsonb · obrigatório: Avisos que a importação deu (dias em falta, intervalo entre extratos, meses fechados afetados…), em JSON.
ficheiro_estado texto · text · obrigatório: «por_enviar» enquanto o ficheiro original não chegou ao arquivo; «guardado» depois.
ficheiro_path texto · text · obrigatório: Caminho do ficheiro original no arquivo privado «fechos-ficheiros».
criado_por identificador (UUID) · uuid · obrigatório: Conta que fez a importação (hub_users.id).
criado_em data e hora, com fuso · timestamp with time zone · obrigatório: Instante da importação.
banco texto · text: Banco do extrato (só nas importações de extratos).
conta_id identificador (UUID) · uuid: Conta bancária do extrato (hub_fch_contas.id; só nas importações de extratos).

`hub_fch_lojas` Lojas dos fechos financeiros

Uma linha por número de loja do POS e a loja da empresa a que corresponde: é como o relatório do POS, que identifica as lojas por número, se liga às lojas da empresa.

zs_loja número inteiro · smallint · obrigatório: Número da loja no POS, de 1 a 999 (chave).
store_id identificador (UUID) · uuid · obrigatório: Loja da empresa (hub_stores.id); cada loja só tem um número.
criado_em data e hora, com fuso · timestamp with time zone · obrigatório: Instante em que a ligação foi feita.

`hub_fch_meses` Fecho do mês por loja

Uma linha por loja e mês que foi fechado nos fechos financeiros (ou reaberto depois): quem fechou, quando, o resumo congelado do que estava decidido e, se foi reaberto, quem e porquê.

store_id identificador (UUID) · uuid · obrigatório: Loja da empresa (hub_stores.id).
mes data (um dia) · date · obrigatório: Primeiro dia do mês.
estado texto · text · obrigatório: «fechado» (o POS, os TPA e os apelidos desse mês estão trancados) ou «aberto» (foi reaberto).
fechado_por identificador (UUID) · uuid: Conta que fechou o mês (hub_users.id).
fechado_em data e hora, com fuso · timestamp with time zone: Instante do fecho.
resumo JSON · jsonb: Resumo congelado no fecho: dias confirmados e justificados e os totais do POS e do banco, em JSON.
reaberto_por identificador (UUID) · uuid: Conta que reabriu o mês (hub_users.id).
reaberto_em data e hora, com fuso · timestamp with time zone: Instante da reabertura.
reaberto_motivo texto · text: Motivo escrito por quem reabriu (10 a 200 caracteres).

`hub_fch_movimentos` Movimentos dos extratos bancários

Uma linha por movimento dos extratos bancários importados (BPI, BCP, BST): a data, a descrição que o banco escreve, o valor e a classificação (venda de TPA, depósito de numerário, pagamento de plataforma, taxa ou outro). A descrição pode conter nomes de terceiros; o IBAN/NIB nela é escondido e o número da conta própria nunca é guardado.

id número inteiro · bigint · obrigatório: Identificador do movimento.
conta_id identificador (UUID) · uuid · obrigatório: Conta bancária (hub_fch_contas.id).
importacao_id identificador (UUID) · uuid · obrigatório: Importação em que o movimento entrou (hub_fch_importacoes.id).
data_mov data (um dia) · date · obrigatório: Data do movimento.
data_valor data (um dia) · date: Data-valor do movimento, quando o banco a dá.
descricao texto · text · obrigatório: Descrição escrita pelo banco (até 300 caracteres).
valor número decimal · numeric · obrigatório: Valor em euros; negativo nos débitos.
classe texto · text · obrigatório: «tpa», «numerario», «plataforma», «taxa» ou «outro».
tpa texto · text: Número do terminal (7 dígitos) numa venda de TPA.
tpa_seq texto · text: Sequência do terminal (3 dígitos) numa venda de TPA.
comerciante texto · text: Nome do comerciante que o banco escreve numa venda de TPA.
dia_venda data (um dia) · date: Dia de venda a que o banco atribui uma venda de TPA.
loja_alias texto · text: Apelido da loja lido do texto de um depósito de numerário.
dia_texto data (um dia) · date: Dia lido do texto de um depósito de numerário.
maquina texto · text: Referência da máquina de depósito (BCP).
plataforma texto · text: Plataforma de um pagamento: uber, bolt, glovo ou tgtg.
chave texto · text · obrigatório: Impressão digital da linha (data, texto e valor), para não importar o mesmo movimento duas vezes.
ordinal número inteiro · integer · obrigatório: Ordem entre linhas iguais no mesmo ficheiro.
criado_em data e hora, com fuso · timestamp with time zone · obrigatório: Instante em que o movimento foi importado.

`hub_fch_parametros` Parâmetros do emparelhamento

Uma única linha com os parâmetros do emparelhamento do banco com o POS: a comissão mínima e máxima aceites nos cartões e a diferença aceite nos depósitos de dinheiro.

id número inteiro · smallint · obrigatório: Sempre 1 (linha única).
comissao_min número decimal · numeric · obrigatório: Comissão mínima aceite nos cartões, em fração (0,005 = 0,5 %).
comissao_max número decimal · numeric · obrigatório: Comissão máxima aceite nos cartões, em fração (0,025 = 2,5 %; até 10 %).
tol_numerario número decimal · numeric · obrigatório: Diferença aceite nos depósitos de dinheiro, em euros (até 1 €).
alterado_por identificador (UUID) · uuid: Conta que alterou os parâmetros por último (hub_users.id).
alterado_em data e hora, com fuso · timestamp with time zone · obrigatório: Instante da última alteração.

`hub_fch_pares` Decisões sobre os dias dos fechos

Uma linha por loja, dia e tipo (cartões ou numerário) que uma pessoa confirmou ou justificou: guarda os valores do POS e do banco que a pessoa viu, para saber se depois mudaram, e a justificação quando o dia não bate.

id identificador (UUID) · uuid · obrigatório: Identificador da decisão.
store_id identificador (UUID) · uuid · obrigatório: Loja da empresa (hub_stores.id).
dia data (um dia) · date · obrigatório: Dia a que a decisão se refere.
tipo texto · text · obrigatório: «cartoes» ou «numerario».
estado texto · text · obrigatório: «confirmado» ou «justificado».
regra texto · text · obrigatório: Regra que propôs o emparelhamento: «n1» (dia exato), «n2» (saldo acumulado), «valor» (depósito casado pelo valor) ou «manual».
confianca texto · text: «alta» ou «media»; vazio nas decisões manuais.
valor_pos número decimal · numeric · obrigatório: Valor do POS que a pessoa viu ao decidir.
valor_banco número decimal · numeric · obrigatório: Valor do banco que a pessoa viu ao decidir.
nota texto · text: Justificação escrita (5 a 200 caracteres); obrigatória quando o estado é «justificado».
criado_por identificador (UUID) · uuid · obrigatório: Conta que decidiu (hub_users.id).
criado_em data e hora, com fuso · timestamp with time zone · obrigatório: Instante da decisão.

`hub_fch_pos` Valores dos fechos do POS

Uma linha por loja, dia e rubrica do relatório «Fechos Financeiros» do POS: o que o POS registou de vendas, métodos de pagamento, origens (terminais) e depósitos. Os valores a zero não se guardam, exceto a venda do dia.

store_id identificador (UUID) · uuid · obrigatório: Loja da empresa (hub_stores.id).
dia data (um dia) · date · obrigatório: Dia a que o valor se refere.
bloco texto · text · obrigatório: Zona do relatório: geral, metodo, origem ou deposito.
codigo texto · text · obrigatório: Rubrica (hub_fch_rubricas.codigo), por exemplo VENDAS, TPA1 ou DINHEIRO.
valor número decimal · numeric · obrigatório: Valor em euros.
importacao_id identificador (UUID) · uuid · obrigatório: Importação que deu o valor (hub_fch_importacoes.id).

`hub_fch_rubricas` Colunas do relatório do POS

Catálogo das colunas do relatório «Fechos Financeiros» do POS: a que código da plataforma corresponde cada cabeçalho. Uma coluna nova do relatório só se importa depois de alguém lhe dar um código.

bloco texto · text · obrigatório: Zona do relatório: geral, metodo, origem ou deposito.
cabecalho texto · text · obrigatório: Cabeçalho da coluna, normalizado (minúsculas, sem acentos).
codigo texto · text · obrigatório: Código da rubrica na plataforma.
rotulo texto · text: Nome legível da rubrica.

`hub_fch_tpas` Terminais de pagamento por loja

Uma linha por atribuição de um terminal de pagamento (TPA) a uma loja, durante um período: em que coluna do POS (TPA 1, TPA 2 ou ambas) os seus valores aparecem e com quantos dias de desvio o banco lança as vendas.

id identificador (UUID) · uuid · obrigatório: Identificador da atribuição.
tpa texto · text · obrigatório: Número do terminal (7 dígitos).
store_id identificador (UUID) · uuid · obrigatório: Loja da empresa (hub_stores.id).
posicao texto · text · obrigatório: Coluna do POS em que a loja regista este terminal: TPA1, TPA2, AMBOS (a soma das duas) ou MOVEL (o TPA móvel).
valido_de data (um dia) · date · obrigatório: Primeiro dia (do banco) em que a atribuição vale.
valido_ate data (um dia) · date: Último dia em que a atribuição vale; vazio se ainda vale.
desvio_dias número inteiro · smallint · obrigatório: Dias de desvio habitual entre a venda e o dia em que o banco a lança (0 a 3); o Zarvo procura sozinho o dia que bate.
origem texto · text · obrigatório: «manual» ou «sugestao» (aceite a partir da sugestão do sistema).
nota texto · text: Nota livre (até 200 caracteres).
criado_por identificador (UUID) · uuid · obrigatório: Conta que atribuiu o terminal (hub_users.id).
criado_em data e hora, com fuso · timestamp with time zone · obrigatório: Instante da atribuição.

`hub_teso_contas_bancarias` Contas bancárias da empresa (pagamentos SEPA)

As contas bancárias da empresa de onde saem os pagamentos a fornecedores por ficheiro SEPA. A versão do ficheiro e o campo do extrato vêm do ficheiro de teste de cada conta (o diagnóstico do banco); sem eles, a conta só gera o ficheiro de teste.

id número inteiro · bigint · obrigatório: Identificador da conta.
nome texto · text · obrigatório: Nome curto da conta (por exemplo «BPI»).
titular texto · text · obrigatório: Titular da conta, como está no banco (vai no ficheiro como ordenante).
iban texto · text · obrigatório: IBAN da conta (sem espaços).
bic texto · text · obrigatório: BIC (SWIFT) do banco da conta.
versao texto · text: «09» ou «03»: a versão do ficheiro SEPA (pain.001.001) que o banco aceita; vazio enquanto está por testar.
campo_extrato texto · text: «descritivo», «referencia» ou «bloco»: o campo do ficheiro que o banco mostra no extrato da empresa — é onde vai o descritivo de cada pagamento; vazio enquanto está por testar.
ativa verdadeiro ou falso · boolean · obrigatório: Se a conta está em uso.
criada_por identificador (UUID) · uuid: Utilizador que criou a conta (hub_users.id).
criada_em data e hora, com fuso · timestamp with time zone · obrigatório: Instante em que a conta foi criada.
atualizada_por identificador (UUID) · uuid: Utilizador que a alterou por último (hub_users.id).
atualizada_em data e hora, com fuso · timestamp with time zone · obrigatório: Instante da última alteração.

`hub_teso_efatura_resumo_mes` Histórico do e-Fatura, somado por mês

Uma linha por mês de emissão com quantas linhas tem o histórico importado do e-Fatura (efatura_history) e o total, com as notas de crédito a abater; mantida sozinha a cada importação. Serve para o separador do histórico abrir depressa; não tem nada que não esteja no histórico.

ym texto · text · obrigatório: Mês de emissão (AAAA-MM); vazio para as linhas sem data.
n número inteiro · bigint · obrigatório: Quantas linhas do histórico são desse mês.
total número decimal · numeric · obrigatório: Soma dos totais desse mês, em euros, com as notas de crédito sempre a abater.

`hub_teso_pag_banco` Prova do banco dos pagamentos

Uma linha por decisão de uma pessoa sobre se um movimento do extrato bancário importado prova (ou não) um pagamento a um fornecedor — ou uma das transferências de um ficheiro de pagamentos. As provas exatas (o mesmo valor e a referência do pagamento no extrato) contam sem linha aqui; só se guarda o que uma pessoa decidiu, com o que viu.

id número inteiro · bigint · obrigatório: Identificador da decisão.
pagamento_id número inteiro · bigint · obrigatório: Pagamento (pagamentos.id).
parte número inteiro · integer · obrigatório: Parte do pagamento: 0 num pagamento registado à mão; o número da transferência num ficheiro de pagamentos.
movimento_id número inteiro · bigint · obrigatório: Movimento do extrato bancário (hub_fch_movimentos.id).
decisao texto · text · obrigatório: «confirmado» (este movimento prova a parte) ou «recusado» (não a prova, e não volta a ser sugerido).
visto JSON · jsonb · obrigatório: O que a pessoa viu ao decidir, em JSON: o valor e o dia da parte, o valor e a data do movimento.
criado_por identificador (UUID) · uuid · obrigatório: Conta que decidiu (hub_users.id).
criado_em data e hora, com fuso · timestamp with time zone · obrigatório: Instante da decisão.

`hub_teso_retencoes_entregas` Retenções na fonte entregues ao Estado

Uma linha por mês cujas retenções na fonte (das faturas pagas nesse mês) foram marcadas como entregues ao Estado: a data, a referência da guia e o valor nesse dia.

mes data (um dia) · date · obrigatório: Mês das retenções (o primeiro dia do mês do pagamento das faturas).
entregue_em data (um dia) · date · obrigatório: Data em que a entrega foi feita.
valor número decimal · numeric · obrigatório: Total das retenções desse mês no momento em que se marcou a entrega, em euros.
ref texto · text: Referência da guia de pagamento (opcional, até 120 caracteres).
entregue_por identificador (UUID) · uuid: Utilizador que marcou a entrega (hub_users.id).
criado_em data e hora, com fuso · timestamp with time zone · obrigatório: Instante em que a entrega foi marcada (ou corrigida).

`hub_teso_sepa_ficheiros` Ficheiros SEPA de pagamentos

Cada ficheiro SEPA gerado para o banco: o de um lote de pagamento (uma transferência por fornecedor) ou um ficheiro de teste. Guarda a fotografia do que foi para o banco — a conta, a data de execução, os totais —, para que descarregá-lo outra vez dê exatamente o mesmo ficheiro. Fica «enviado» até alguém confirmar que foi pago («pago», ligado ao pagamento) ou o anular («anulado»).

id número inteiro · bigint · obrigatório: Identificador do ficheiro.
lote_id número inteiro · bigint: Lote de pagamento do ficheiro (hub_teso_lotes.id); vazio no ficheiro de teste.
conta_id número inteiro · bigint · obrigatório: Conta de onde sai o dinheiro (hub_teso_contas_bancarias.id).
teste verdadeiro ou falso · boolean · obrigatório: Se é um ficheiro de teste (duas transferências de 0,01 € entre contas da empresa).
msg_id texto · text · obrigatório: Referência única do ficheiro no banco (MsgId); é também a referência do pagamento.
criado_em data e hora, com fuso · timestamp with time zone · obrigatório: Instante em que o ficheiro foi gerado (vai dentro do ficheiro).
data_execucao data (um dia) · date · obrigatório: Data pedida ao banco para executar as transferências.
versao texto · text · obrigatório: Versão do ficheiro (pain.001.001.03 ou .09).
campo_extrato texto · text: O campo onde foi o descritivo, copiado da conta nesse momento.
titular texto · text · obrigatório: Titular da conta, copiado nesse momento.
iban texto · text · obrigatório: IBAN da conta, copiado nesse momento.
bic texto · text · obrigatório: BIC da conta, copiado nesse momento.
estado texto · text · obrigatório: «enviado», «pago» ou «anulado».
n_transferencias número inteiro · integer · obrigatório: Número de transferências do ficheiro.
total número decimal · numeric · obrigatório: Soma das transferências, em euros.
criado_por identificador (UUID) · uuid · obrigatório: Utilizador que gerou o ficheiro (hub_users.id).
confirmado_por identificador (UUID) · uuid: Utilizador que confirmou o pagamento (hub_users.id).
confirmado_em data e hora, com fuso · timestamp with time zone: Instante da confirmação.
anulado_por identificador (UUID) · uuid: Utilizador que anulou o ficheiro (hub_users.id).
anulado_em data e hora, com fuso · timestamp with time zone: Instante da anulação.
pagamento_id número inteiro · bigint: Pagamento criado ao confirmar (pagamentos.id).
comprovativo_path texto · text: Caminho do comprovativo do banco no arquivo (bucket teso-comprovativos), se foi anexado.

`hub_teso_sepa_transferencias` Transferências dos ficheiros SEPA

As transferências de cada ficheiro SEPA, como foram para o banco: uma por fornecedor, com o valor, o IBAN e o descritivo escolhido para o extrato da empresa.

ficheiro_id número inteiro · bigint · obrigatório: Ficheiro a que pertence (hub_teso_sepa_ficheiros.id).
ordem número inteiro · integer · obrigatório: Posição da transferência no ficheiro.
supplier_id número inteiro · bigint: Fornecedor pago (suppliers.id); vazio no ficheiro de teste.
nome texto · text · obrigatório: Nome do beneficiário, copiado nesse momento.
iban texto · text · obrigatório: IBAN do beneficiário, copiado nesse momento.
valor número decimal · numeric · obrigatório: Valor da transferência, em euros.
descritivo texto · text · obrigatório: O descritivo escolhido para o extrato da empresa.
ref_bloco texto · text · obrigatório: Identificador do bloco no ficheiro (PmtInfId).
ref_ponta texto · text · obrigatório: Referência ponta a ponta (EndToEndId).
ustrd texto · text · obrigatório: Texto livre que segue para o fornecedor: o descritivo e os números das faturas.
faturas lista de números inteiros · _int8 · obrigatório: Faturas pagas por esta transferência (faturas.id).

`pagamentos` Pagamentos a fornecedores

Uma linha por pagamento registado na tesouraria: de uma fatura (total ou parcial) ou de várias faturas de uma vez.

id número inteiro · bigint · obrigatório: Identificador do pagamento.
fatura_id número inteiro · bigint: Fatura paga (faturas.id); vazio num pagamento de várias faturas de uma vez, que as indica nas notas.
date data (um dia) · date: Data do pagamento (dia).
amount número decimal · numeric: Valor pago, em euros; negativo quando se marca como paga uma nota de crédito. Num pagamento de várias faturas é a soma do que faltava pagar de cada uma, com as notas de crédito a abater.
method texto · text: Meio de pagamento: um valor da lista «metodo_pagamento» («Transferência bancária», «Cheque», «Débito direto») ou texto livre.
ref texto · text: Referência do pagamento, por exemplo o n.º da ordem de pagamento.
notes texto · text: Notas livres; num pagamento de várias faturas, um JSON com «bulk», «faturaIds» e, se havia pagamentos parciais, «valores» (quanto cobriu de cada fatura).
created_at data e hora, com fuso · timestamp with time zone: Instante em que o pagamento foi registado.

Faturas de fornecedores

`doc_store_references` Referências de loja por fornecedor

Uma linha por identificador que um fornecedor usa nas faturas para distinguir as lojas (n.º de cliente, local de consumo, telefone, cartão…), aprendido quando alguém confirma a loja ao rever uma fatura. A leitura automática usa-o para atribuir a loja às faturas seguintes.

id identificador (UUID) · uuid · obrigatório: Identificador da referência.
supplier_id número inteiro · bigint · obrigatório: Fornecedor que usa o identificador (suppliers.id).
kind texto · text · obrigatório: Tipo de identificador, como a leitura o classificou: por exemplo «customer_code» (n.º de cliente), «cpe» ou «cui» (local de consumo), «loja_numero», «telefone», «cartao», «matricula» ou «outro».
value texto · text · obrigatório: O identificador tal como aparece nas faturas do fornecedor; único por fornecedor e tipo.
store_id identificador (UUID) · uuid · obrigatório: Loja ou centro de custo a que o identificador corresponde (hub_stores.id).
created_by identificador (UUID) · uuid: Utilizador que confirmou a loja na revisão da fatura (hub_users.id).
created_at data e hora, com fuso · timestamp with time zone · obrigatório: Instante em que a referência foi aprendida.

`document_items` Linhas das faturas lidas

Uma linha por artigo de uma fatura de fornecedor lida pela leitura automática. Só se guardam para os fornecedores com leitura completa de artigos (ou sem fornecedor reconhecido).

id identificador (UUID) · uuid · obrigatório: Identificador da linha.
document_id identificador (UUID) · uuid: Documento a que a linha pertence (documents.id); apagar o documento apaga as linhas.
line_number número inteiro · integer: Ordem da linha no documento, a começar em 1.
ref texto · text: Referência ou código do artigo no fornecedor; a descrição, quando o documento não tem código.
description texto · text: Designação do artigo tal como impressa.
unit_price número decimal · numeric: Preço por unidade tal como impresso, antes do desconto da linha, em euros.
quantity número decimal · numeric: Quantidade faturada (em kg nos produtos de peso variável).
unit texto · text: Unidade tal como no documento, por exemplo «KG», «UN», «CX» ou «L».
format texto · text: Embalagem indicada na linha (por exemplo «6x1L» ou «CX 24UN»); repete a unidade quando não há.
qt_vol texto · text: Valor da coluna «QT/VOL» (quantidade/volume) tal como impresso, quando o documento a tem.
vol texto · text: Valor de uma coluna «Vol» separada da quantidade, tal como impresso, quando o documento a tem.
total número decimal · numeric: Valor da linha depois do desconto da linha, sem IVA, em euros.

`documents` Faturas de fornecedores carregadas

Uma linha por fatura ou nota de crédito de fornecedor carregada e lida pela leitura automática: o ficheiro original, o que foi lido, o que ficou confirmado na revisão e a loja e o fornecedor atribuídos.

id identificador (UUID) · uuid · obrigatório: Identificador do documento.
uploaded_by identificador (UUID) · uuid: Utilizador que carregou e gravou o documento (hub_users.id).
uploaded_at data e hora, com fuso · timestamp with time zone · obrigatório: Instante em que o documento foi gravado.
file_name texto · text · obrigatório: Nome original do ficheiro carregado.
file_size número inteiro · integer: Tamanho do ficheiro original, em bytes.
file_type texto · text: Tipo do ficheiro original (tipo MIME, por exemplo «application/pdf» ou «image/jpeg»).
status texto · text: Estado do processamento: «pending», «processing», «processed», «reviewed» ou «error»; a plataforma grava sempre «processed» (lido e guardado).
ocr_raw JSON · jsonb: Resultado da leitura automática, em JSON, com o fornecedor decidido: número, datas, fornecedor, NIF, IBAN, loja, totais, IVA por taxa, linhas e avisos.
error_message texto · text: Mensagem de erro da leitura; prevista, mas a plataforma não a preenche.
document_type texto · text: Tipo de documento: «fatura» ou «nota_credito».
invoice_number texto · text: Número do documento com a série, tal como impresso.
invoice_date data (um dia) · date: Data de emissão do documento (dia).
supplier texto · text: Nome do emitente tal como lido no documento; é o que a lista mostra.
delivery_address texto · text: Local de entrega lido no documento; nas leituras atuais, o nome da loja reconhecida.
store_id identificador (UUID) · uuid: Loja ou centro de custo a que o documento foi atribuído (hub_stores.id).
total número decimal · numeric: Total do documento com IVA, em euros; as leituras atuais gravam as notas de crédito em negativo. Quando o total não foi lido nem escrito na revisão, fica a soma das linhas e dos encargos, sem IVA (ou vazio).
notes texto · text: Observações sobre o documento; previstas, mas a plataforma não as preenche.
file_path texto · text: Caminho do original no arquivo local de pastas da empresa (fornecedor/ano/mês), gravado só com o programa local de arquivo ligado; esse ficheiro fica fora da plataforma.
storage_path texto · text: Caminho do original (PDF ou imagem) no armazenamento de ficheiros, no formato ano/mês/identificador_nome; o ficheiro vai na cópia com o índice.
ocr_final JSON · jsonb: Resultado depois da revisão, em JSON: a leitura com os valores confirmados (número, data, tipo, totais, loja) e o bloco «revisao» (ação, campos editados, quem reviu).
ocr_model texto · text: Identificador do modelo de leitura automática que leu o documento.
ocr_prompt_version texto · text: Versão das instruções de leitura usadas (por exemplo «v3.1»).
total_net número decimal · numeric: Total sem IVA, em euros, com o mesmo sinal do total.
total_vat número decimal · numeric: Valor do IVA, em euros, com o mesmo sinal do total.
supplier_id número inteiro · bigint: Fornecedor registado a que o documento ficou ligado (suppliers.id); vazio enquanto não estiver decidido.
supplier_name_raw texto · text: Nome do fornecedor tal como vem impresso no documento.

Fornecedores e lojas

`hub_iban_propostas` IBAN lidos para validação

Uma linha por IBAN de fornecedor proposto — lido numa fatura ou escrito na ficha — e diferente do registado. Nunca entra sozinho na ficha: fica pendente até alguém com permissão sobre fornecedores o aprovar ou recusar.

id número inteiro · bigint · obrigatório: Identificador da proposta.
supplier_id número inteiro · bigint · obrigatório: Fornecedor a que o IBAN se destina (suppliers.id).
iban texto · text · obrigatório: IBAN proposto (lido na fatura ou escrito na ficha), sem espaços e em maiúsculas, com os dígitos de controlo válidos.
iban_atual texto · text: IBAN que estava na ficha do fornecedor quando a proposta foi feita; vazio se não havia.
tipo texto · text · obrigatório: «novo» (a ficha não tinha IBAN) ou «alteracao» (a ficha tinha outro).
document_id identificador (UUID) · uuid: Documento de onde o IBAN foi lido (documents.id).
fatura_num texto · text: Número da fatura de onde o IBAN foi lido.
estado texto · text · obrigatório: «pendente», «aprovado» (o IBAN passou para a ficha do fornecedor) ou «recusado».
criado_por identificador (UUID) · uuid: Utilizador que fez a proposta: quem gravou a fatura de onde o IBAN foi lido, ou quem o escreveu na ficha (hub_users.id). Não pode ser quem a aprova.
criado_em data e hora, com fuso · timestamp with time zone · obrigatório: Instante da proposta.
decidido_por identificador (UUID) · uuid: Utilizador que aprovou ou recusou (hub_users.id).
decidido_em data e hora, com fuso · timestamp with time zone: Instante da decisão.
motivo texto · text: Motivo escrito por quem decidiu; «substituída por outra proposta aprovada» quando foi aprovado outro IBAN do mesmo fornecedor.
swift texto · text: SWIFT/BIC proposto com o IBAN, quando a proposta nasceu na ficha do fornecedor; vazio se não traz (a ficha fica com o que tinha).
bank texto · text: Nome do banco proposto com o IBAN, quando a proposta nasceu na ficha do fornecedor; vazio se não traz.

`hub_supplier_anexos` Anexos dos fornecedores

Uma linha por ficheiro anexado à ficha de um fornecedor (contratos, acordos assinados e outros documentos).

id número inteiro · bigint · obrigatório: Identificador do anexo.
supplier_id número inteiro · bigint · obrigatório: Fornecedor a que o anexo pertence (suppliers.id).
path texto · text · obrigatório: Caminho do ficheiro no armazenamento de ficheiros (fornecedor/identificador.extensão); o ficheiro vai na cópia com o índice.
nome texto · text · obrigatório: Nome original do ficheiro.
mime texto · text: Tipo do ficheiro (tipo MIME).
tamanho número inteiro · bigint: Tamanho do ficheiro, em bytes.
autor_user_id identificador (UUID) · uuid: Utilizador que anexou o ficheiro (hub_users.id).
created_at data e hora, com fuso · timestamp with time zone · obrigatório: Instante em que o ficheiro foi anexado.

`hub_teso_lote_faturas` Faturas de cada lote de pagamento

Uma linha por fatura que está, ou esteve, num lote de pagamento. Uma fatura só pode estar num lote aberto de cada vez; quando o lote é pago a ligação fica no histórico.

lote_id número inteiro · bigint · obrigatório: Lote de pagamento (hub_teso_lotes.id).
fatura_id número inteiro · bigint · obrigatório: Fatura que entrou no lote (faturas.id).
aberto verdadeiro ou falso · boolean · obrigatório: Verdadeiro enquanto o lote está em preparação; passa a falso quando o lote é pago.
adicionada_em data e hora, com fuso · timestamp with time zone · obrigatório: Instante em que a fatura entrou no lote.
adicionada_por identificador (UUID) · uuid: Utilizador que a juntou ao lote (hub_users.id).

`hub_teso_lotes` Lotes de pagamento

Um lote de pagamento é um conjunto de faturas juntas ao longo da semana, para serem pagas de uma vez. Fica «aberto» (em preparação) até alguém o fechar e pagar, e então passa a «pago» e liga-se ao pagamento criado.

id número inteiro · bigint · obrigatório: Identificador do lote.
nome texto · text · obrigatório: Nome do lote («Lote 13/10», por omissão; a pessoa pode mudá-lo).
estado texto · text · obrigatório: «aberto» (em preparação), «enviado» (o ficheiro SEPA está no banco: o lote fica trancado até se confirmar o pagamento ou se anular o ficheiro) ou «pago».
criado_por identificador (UUID) · uuid: Utilizador que criou o lote (hub_users.id).
criado_em data e hora, com fuso · timestamp with time zone · obrigatório: Instante em que o lote foi criado.
pago_em data e hora, com fuso · timestamp with time zone: Instante em que o lote foi fechado e pago; vazio enquanto está aberto.
pagamento_id número inteiro · bigint: Pagamento que o lote gerou ao ser pago (pagamentos.id).
updated_at data e hora, com fuso · timestamp with time zone · obrigatório: Instante da última alteração do lote.

`suppliers` Fichas de fornecedores

Uma linha por fornecedor: identificação fiscal, contactos, dados bancários, condições de pagamento e as pistas que a leitura automática usa para o reconhecer. Nunca se apaga; desativa-se.

id número inteiro · bigint · obrigatório: Identificador do fornecedor.
name texto · text · obrigatório: Nome ou denominação social.
nif texto · text: NIF do fornecedor, sem espaços; único entre os fornecedores ativos.
email texto · text: Email de contacto.
phone texto · text: Telefone de contacto.
address texto · text: Morada, em texto livre.
iban texto · text: IBAN confirmado para pagamentos; um IBAN lido numa fatura só chega aqui depois de aprovado (hub_iban_propostas).
swift texto · text: Código SWIFT/BIC do banco.
bank texto · text: Nome do banco.
terms número inteiro · integer: Prazo de pagamento, em dias (0 = pronto pagamento).
terms_custom número inteiro · integer: Prazo de pagamento próprio, em dias; quando preenchido prevalece sobre «terms» (a ficha dos registos grava-o vazio).
rmf texto · text: Contagem do prazo: «none» (desde a data da fatura), «rmf» (resumo mensal: desde o fim do mês da fatura) ou «fim_mes» (vence no último dia do mês).
discount número decimal · numeric: Desconto comercial acordado, em percentagem (0 a 100).
notify verdadeiro ou falso · boolean: Se verdadeiro, a tesouraria propõe enviar-lhe por email a lista das faturas que constam no e-Fatura e ainda não foram registadas.
notes texto · text: Observações livres, escritas ao criar o fornecedor a partir de uma fatura.
created_at data e hora, com fuso · timestamp with time zone: Instante em que o fornecedor foi criado.
reconcile verdadeiro ou falso · boolean: Se verdadeiro, as faturas do fornecedor entram na comparação com o histórico do e-Fatura.
ocr_full_detail verdadeiro ou falso · boolean: Se verdadeiro, a leitura automática guarda todas as linhas de artigos das faturas deste fornecedor; senão, só o cabeçalho e os totais.
abbreviation texto · text: Nome curto usado nas listas e nas pastas do arquivo.
distrito texto · text: Distrito da morada.
concelho texto · text: Concelho da morada.
active verdadeiro ou falso · boolean · obrigatório: Falso quando o fornecedor foi desativado.
deactivated_by identificador (UUID) · uuid: Utilizador que desativou o fornecedor (hub_users.id).
deactivated_at data e hora, com fuso · timestamp with time zone: Instante da desativação.
aliases lista de textos · _text · obrigatório: Outros nomes com que o fornecedor aparece nas faturas, usados pela leitura automática; acrescentam-se quando alguém confirma a correspondência.
brands lista de textos · _text · obrigatório: Marcas comerciais do fornecedor, usadas pela leitura automática para o reconhecer.
email_domain texto · text: Domínio do email do fornecedor (a parte depois de «@»), usado pela leitura automática para o reconhecer.
vat_number texto · text: Número de contribuinte estrangeiro (IVA, com o prefixo do país) de um fornecedor sem NIF português.
debito_direto verdadeiro ou falso · boolean · obrigatório: Se verdadeiro, as faturas do fornecedor são pagas por débito direto: a tesouraria assinala-as e propõe esse meio ao marcá-las como pagas.
fatura_sede verdadeiro ou falso · boolean · obrigatório: Se verdadeiro, o fornecedor só fatura à sede: a leitura automática atribui as faturas dele à sede sem perguntar.
loja_fixa identificador (UUID) · uuid: Loja ou centro de custo a que se atribuem sempre as faturas deste fornecedor (hub_stores.id). É uma escolha única com «fatura_sede» e «rateio_todas_lojas»: a ficha só tem uma das três.
updated_at data e hora, com fuso · timestamp with time zone · obrigatório: Instante da última alteração; serve também para recusar gravações de quem editou uma versão antiga.
por_validar verdadeiro ou falso · boolean · obrigatório: Se verdadeiro, o fornecedor foi criado sozinho a partir do que se leu numa fatura e ainda não foi confirmado por uma pessoa: fica assim até alguém preencher e verificar os dados.
rateio_todas_lojas verdadeiro ou falso · boolean · obrigatório: Se verdadeiro, cada fatura nova deste fornecedor reparte-se em partes iguais pelas lojas ativas nesse momento (lojas, não centros de custo).
gravar_sem_qr verdadeiro ou falso · boolean · obrigatório: Se verdadeiro, o fornecedor é «de confiança»: uma fatura dele sem QR fiscal da AT legível grava-se e lança-se sozinha nos Documentos, desde que tudo o resto esteja limpo (fornecedor reconhecido pelo NIF, totais certos, número, data e total lidos, não repetida).
postal_code texto · text: Código postal da morada (em Portugal, no formato 1000-001); vazio quando não foi indicado. Em Portugal serve também para preencher o concelho e o distrito.
country texto · text: País da morada, em código de duas letras (PT, ES, FR…); vazio nas fichas antigas, que se leem como Portugal ou pelo prefixo do número de IVA. Fora de Portugal não há concelho nem distrito.

Despesas e quilómetros

`hub_desp_capturas` Faturas por completar

Uma linha por fatura fotografada ou escolhida que ainda não passou a despesa: o ficheiro já guardado e o que a leitura automática deu, para pré-preencher o formulário. A linha sai quando a despesa é gravada ou a fatura é apagada.

id identificador (UUID) · uuid · obrigatório: Identificador da fatura por completar.
user_id identificador (UUID) · uuid · obrigatório: Conta que fotografou a fatura (hub_users.id); só ela a vê, completa ou apaga.
mapa_id identificador (UUID) · uuid · obrigatório: Mapa em cuja pasta ficou o ficheiro (hub_desp_mapas.id): o rascunho ou um mapa devolvido de despesas da pessoa, ou o mapa do fundo de cofre da loja.
anexo_path texto · text · obrigatório: Caminho do ficheiro (fotografia ou PDF) no armazenamento de ficheiros; o ficheiro vai na cópia, com o índice.
anexo_mime texto · text: Tipo do ficheiro: «application/pdf», «image/jpeg», «image/png» ou «image/webp».
anexo_bytes número inteiro · bigint: Tamanho do ficheiro em bytes, lido pelo servidor no armazenamento.
anexo_sha256 texto · text: Resumo sha256 do ficheiro calculado no browser (informativo), em hexadecimal.
estado texto · text · obrigatório: Situação da leitura: «a_ler» (à espera), «lida», «nao_lida» (preenche-se à mão) ou «recusa» (documento que não se reembolsa, ver recusa).
leitura texto · text: Como se leu: «qr» (código QR fiscal da Autoridade Tributária) ou «ia» (leitura automática de documentos); vazio se não se leu.
dados JSON · jsonb · obrigatório: Valores lidos, em texto, para pré-preencher a despesa: fornecedor_nome, fornecedor_nif, nif_adquirente, doc_tipo, doc_numero, atcud, data, total e iva (euros).
qr_raw texto · text: Texto em bruto do código QR fiscal lido na fatura, quando a leitura foi pelo QR.
avisos lista de textos · _text · obrigatório: Códigos de aviso da leitura automática (por exemplo «NIF_ILEGIVEL», «TOTAL_ILEGIVEL», «DATA_ILEGIVEL», «LEITURA_FRACA»).
recusa texto · text: Porque não se reembolsa: «ANULADA» (anulada pelo emitente), «NAO_E_FATURA», «COM_RETENCAO» (retenção na fonte) ou «VARIOS» (vários documentos na imagem).
erro texto · text: Mensagem do erro quando a fatura não se conseguiu ler (até 300 caracteres).
criado_em data e hora, com fuso · timestamp with time zone · obrigatório: Instante em que a fatura foi registada.
lida_em data e hora, com fuso · timestamp with time zone: Instante em que se gravou o resultado da leitura.

`hub_desp_eventos` Histórico dos mapas de despesas

Uma linha por acontecimento na vida de um mapa (criado, entregue, devolvido, aprovado, pago, anulado…), com quem, quando e o motivo. As linhas nunca se alteram; as entregas de mapas de km guardam o conteúdo assinado.

id número inteiro · bigint · obrigatório: Número sequencial do acontecimento.
mapa_id identificador (UUID) · uuid · obrigatório: Mapa a que diz respeito (hub_desp_mapas.id).
evento texto · text · obrigatório: O que aconteceu: «criado», «entregue», «reentregue» (depois de devolvido), «recusado» (devolvido para corrigir), «aprovado», «pago», «anulado», «entregue_por_admin», «reposto_no_cofre», «linha_regularizada», «ajuste_pedido» (a mudança do valor do fundo pedida) ou «devolucao_recebida» (a devolução de um ajuste chegou ao escritório).
por identificador (UUID) · uuid · obrigatório: Conta que fez a ação (hub_users.id).
em data e hora, com fuso · timestamp with time zone · obrigatório: Instante do acontecimento.
motivo texto · text: Motivo escrito: da devolução, da anulação ou das despesas do fundo recusadas numa aprovação parcial.
detalhe JSON · jsonb: Dados do acontecimento em JSON: total e n_linhas na entrega; linhas na devolução; data e referencia no pagamento; na entrega de km, a assinatura, o conteudo assinado, a origem (resumo sha256 do endereço IP de quem assinou) e o user_agent (o browser usado).

`hub_desp_km` Deslocações dos mapas de km

Uma linha por deslocação em viatura que não é da empresa, num mapa de km: data, partida, chegada, motivo, viatura, km aceites e valor a pagar.

id identificador (UUID) · uuid · obrigatório: Identificador da deslocação.
mapa_id identificador (UUID) · uuid · obrigatório: Mapa de km a que pertence (hub_desp_mapas.id).
criado_por identificador (UUID) · uuid · obrigatório: Conta que registou a deslocação (hub_users.id).
criado_em data e hora, com fuso · timestamp with time zone · obrigatório: Instante em que foi registada.
atualizado_em data e hora, com fuso · timestamp with time zone · obrigatório: Instante da última alteração.
data data (um dia) · date · obrigatório: Dia da deslocação (da partida).
data_regresso data (um dia) · date · obrigatório: Dia do regresso; igual à data quando não foi indicado.
hora_saida hora do dia · time without time zone: Hora de saída; opcional, deixou de ser pedida (vazia nas deslocações mais recentes).
hora_regresso hora do dia · time without time zone: Hora de regresso; opcional, deixou de ser pedida (vazia nas deslocações mais recentes).
motivo texto · text · obrigatório: Para que foi a deslocação (3 a 300 caracteres).
origem_tipo texto · text · obrigatório: Tipo do local de partida: «loja», «casa» (a casa da pessoa), «guardado» (local guardado pela pessoa) ou «outro» (escolhido numa pesquisa).
destino_tipo texto · text · obrigatório: Tipo do local de chegada: «loja», «casa», «guardado» ou «outro», como em origem_tipo.
origem_store_id identificador (UUID) · uuid: Loja de partida (hub_stores.id), quando origem_tipo é «loja».
destino_store_id identificador (UUID) · uuid: Loja de chegada (hub_stores.id), quando destino_tipo é «loja».
origem_place_id texto · text · obrigatório: Identificador do local de partida no serviço de mapas (nunca a morada nem coordenadas).
destino_place_id texto · text · obrigatório: Identificador do local de chegada no serviço de mapas (nunca a morada nem coordenadas).
origem_texto texto · text · obrigatório: Nome do local de partida como a pessoa o vê: nome da loja, «Casa», nome dado ao local guardado ou descrição curta escrita por ela.
destino_texto texto · text · obrigatório: Nome do local de chegada, com as mesmas regras de origem_texto.
ida_volta verdadeiro ou falso · boolean · obrigatório: Verdadeiro se a deslocação é de ida e volta (os km incluem o regresso).
viatura_id identificador (UUID) · uuid · obrigatório: Viatura usada (hub_desp_viaturas.id).
viatura_matricula texto · text: Matrícula da viatura, congelada ao entregar o mapa.
viatura_proprietario texto · text: Nome do proprietário da viatura, congelado ao entregar: o da própria pessoa ou o indicado na viatura.
valor_km número decimal · numeric · obrigatório: Valor pago por km, em euros, em vigor na data da deslocação (confirmado ao entregar).
limite_isento número decimal · numeric · obrigatório: Limite por km isento de IRS e Segurança Social, em euros, em vigor na data da deslocação.
calculado_em data e hora, com fuso · timestamp with time zone · obrigatório: Instante em que o serviço de mapas calculou a distância usada; mantém-se depois de os km calculados serem apagados.
km_declarados número decimal · numeric · obrigatório: Km aceites para pagamento, com uma casa decimal: os calculados ou os escritos pela pessoa (com justificação quando diferem mais de 1 km e 5 %).
km_aceite_sem_alteracao verdadeiro ou falso · boolean · obrigatório: Verdadeiro se os km aceites são exatamente os calculados pelo serviço de mapas.
justificacao_km texto · text: Porque os km escritos diferem dos calculados; obrigatória quando a diferença passa 1 km e 5 %.
total número decimal · numeric · obrigatório: Valor a pagar em euros: km aceites × valor por km, arredondado ao cêntimo.
avisos lista de textos · _text · obrigatório: Códigos de aviso para quem aprova: «KM_ALTERADOS», «CASA_COMO_LOCAL» (um local escolhido é a casa da pessoa) e «EXERCICIO_ANTERIOR».
ativa verdadeiro ou falso · boolean · obrigatório: Falso quando o mapa foi anulado; a deslocação fica guardada.

Não vão na cópia: km_calculados (conteúdo do serviço de mapas, guardado temporariamente (cláusula 17.7, alínea e))).

`hub_desp_linhas` Linhas dos mapas de despesas

Uma linha por fatura ou talão num mapa de despesas pessoais ou do fundo de cofre: dados fiscais do documento, categoria, valor, avisos e o ficheiro com a fotografia.

id identificador (UUID) · uuid · obrigatório: Identificador da despesa.
mapa_id identificador (UUID) · uuid · obrigatório: Mapa a que pertence (hub_desp_mapas.id).
criado_por identificador (UUID) · uuid · obrigatório: Conta que lançou a despesa (hub_users.id).
criado_em data e hora, com fuso · timestamp with time zone · obrigatório: Instante em que foi lançada.
atualizado_em data e hora, com fuso · timestamp with time zone · obrigatório: Instante da última alteração.
data data (um dia) · date · obrigatório: Dia do documento.
descricao texto · text · obrigatório: Para que foi a despesa, escrito por quem a lançou (3 a 500 caracteres).
categoria_chave texto · text · obrigatório: Categoria: valor da lista «categoria_despesa» (hub_ref_lists.value), por exemplo «comb_gasoleo», «viat_portagem», «refeicao_repr», ou «outro».
categoria_texto texto · text: Nome da categoria escrito pela pessoa, só quando categoria_chave é «outro».
participantes texto · text: Quem participou; obrigatório nas refeições de representação.
fornecedor_nome texto · text: Nome do fornecedor que emitiu o documento.
fornecedor_nif texto · text: NIF do fornecedor (9 algarismos); pode faltar num talão de venda.
doc_tipo texto · text · obrigatório: Tipo de documento: «FT» fatura, «FS» fatura simplificada, «FR» fatura-recibo, «NC» nota de crédito, «ND» nota de débito, «VD» venda a dinheiro, «TV» talão de venda, «TD» talão de devolução.
doc_numero texto · text: Número do documento, como impresso.
doc_chave texto · text: Número do documento normalizado (maiúsculas, sem espaços nem o sufixo « / ATCUD»), calculado pela base para detetar duplicados.
atcud texto · text: Código único do documento (ATCUD).
nif_adquirente texto · text: NIF do adquirente que consta do documento; vazio se não tiver ou for consumidor final.
doc_origem texto · text: Número do documento que uma nota de crédito corrige; a Plataforma ainda não o preenche.
total número decimal · numeric · obrigatório: Total do documento em euros, com IVA; negativo nas notas de crédito.
iva JSON · jsonb: IVA do documento, informativo, em JSON: total (euros) e origem («qr», «ia» ou «manual»); vazio se desconhecido.
meio_pagamento texto · text: Como foi pago: «cartao_pessoal», «numerario», «mbway» ou «transferencia»; no fundo de cofre é sempre «numerario».
viatura_tipo texto · text: Nas categorias de viatura, de quem é a viatura: «empresa» ou «propria».
viatura_matricula texto · text: Matrícula da viatura, nas categorias de viatura, quando indicada: três pares de letras ou algarismos separados por hífen (por exemplo «AA-00-AA»).
leitura texto · text · obrigatório: Origem dos dados fiscais: «qr» (código QR fiscal lido no servidor), «ia» (leitura automática de documentos) ou «manual».
qr_raw texto · text: Texto em bruto do código QR fiscal da Autoridade Tributária, quando a leitura foi pelo QR.
avisos lista de textos · _text · obrigatório: Códigos de aviso calculados ao gravar: «NIF_EMPRESA_POR_CONFIGURAR», «SEM_NIF_EMPRESA», «NIF_DO_BENEFICIARIO», «SIMPLIFICADA_ACIMA_100», «POSSIVEL_DUPLICADA», «SEM_QR», «SEM_ANEXO», «EXERCICIO_ANTERIOR», «NO_EFATURA», «TALAO_40_5» e, no fundo de cofre, «DE_MES_ANTERIOR» e «SALDO_NEGATIVO».
recusada verdadeiro ou falso · boolean · obrigatório: No fundo de cofre: verdadeiro se quem aprovou recusou esta despesa e aprovou o resto do mapa.
recusa_motivo texto · text: Motivo da recusa desta despesa.
regularizada_em data e hora, com fuso · timestamp with time zone: Instante em que a despesa recusada foi regularizada pelo responsável do fundo.
regularizada_por identificador (UUID) · uuid: Conta que a regularizou (hub_users.id).
regularizada_como texto · text: Como se regularizou: «relancada» (corrigida e lançada noutro mapa) ou «reposta_pelo_responsavel» (o responsável repôs o dinheiro no cofre).
anexo_path texto · text: Caminho da fotografia ou PDF no armazenamento de ficheiros; o ficheiro vai na cópia, com o índice. Vazio só numa portagem sem talão.
anexo_bytes número inteiro · bigint: Tamanho do ficheiro em bytes, lido pelo servidor no armazenamento.
anexo_mime texto · text: Tipo do ficheiro: «application/pdf», «image/jpeg», «image/png» ou «image/webp».
anexo_etag texto · text: Etiqueta de versão (ETag) do ficheiro no armazenamento no momento da gravação, para provar a integridade.
anexo_sha256 texto · text: Resumo sha256 do ficheiro, em hexadecimal (informativo).
anexo_sha256_origem texto · text: Quem calculou o anexo_sha256: «browser» ou «servidor».
ativa verdadeiro ou falso · boolean · obrigatório: Falso quando o mapa foi anulado; a despesa e o ficheiro ficam guardados.
acerto_de_linha_id identificador (UUID) · uuid: Numa linha de acerto de um mapa já pago, a despesa que corrige (hub_desp_linhas.id); a Plataforma ainda não cria linhas de acerto.
acerto_motivo texto · text: Motivo da linha de acerto; a Plataforma ainda não cria linhas de acerto.
sem_anexo_motivo texto · text: Numa portagem sem talão, porque não há documento: «via_verde» (portagem eletrónica, o extrato vem depois), «perdido» ou texto escrito.

`hub_desp_locais` Locais guardados das pessoas

Locais privados de cada conta usados nos mapas de km: a Casa (com a autorização para a guardar) e os locais a que a pessoa deu nome. Guarda só o identificador do local no serviço de mapas, nunca a morada.

id identificador (UUID) · uuid · obrigatório: Identificador do local.
user_id identificador (UUID) · uuid · obrigatório: Conta dona do local (hub_users.id); só ela o vê.
nome texto · text · obrigatório: Nome dado pela pessoa (2 a 60 caracteres); «Casa» na casa da pessoa.
place_id texto · text · obrigatório: Identificador do local no serviço de mapas.
e_casa verdadeiro ou falso · boolean · obrigatório: Verdadeiro se é a casa da pessoa (no máximo uma por conta).
criado_em data e hora, com fuso · timestamp with time zone · obrigatório: Instante em que o local foi guardado.
casa_autorizada_em data e hora, com fuso · timestamp with time zone: Na Casa, instante em que a pessoa autorizou guardar a sua localização; vazio numa Casa por confirmar, que não se pode usar.
casa_autorizacao_versao texto · text: Versão do texto da autorização aceite (por exemplo «casa-2026-09»).

`hub_desp_mapas` Mapas de despesas e de km

Um mapa por linha: de despesas pagas do próprio bolso, de quilómetros ou do fundo de cofre de uma loja num mês (ou um ajuste do valor do fundo, ou a regularização de um ano já fechado), com o estado, o beneficiário e os dados congelados na entrega, a aprovação, o pagamento e a assinatura dos mapas de km.

id identificador (UUID) · uuid · obrigatório: Identificador do mapa.
numero texto · text: Número atribuído na primeira entrega: «DSP-AAAA-NNNN» (despesas), «KM-AAAA-NNNN» ou «FND-AAAA-NNNN» (fundo); vazio num rascunho nunca entregue.
tipo texto · text · obrigatório: «despesas» (pagas do próprio bolso), «km» (deslocações em viatura que não é da empresa) ou «fundo» (pagas pelo fundo de cofre de uma loja).
estado texto · text · obrigatório: «rascunho», «submetido» (entregue, por aprovar), «recusado» (devolvido para corrigir), «aprovado», «pago» ou «anulado».
criado_por identificador (UUID) · uuid · obrigatório: Conta que criou o mapa (hub_users.id); nos mapas pessoais é o dono.
criado_em data e hora, com fuso · timestamp with time zone · obrigatório: Instante da criação.
employee_id identificador (UUID) · uuid: Ficha do colaborador dono do mapa (hub_rh_employees.id), nos mapas de despesas e de km; vazio no fundo.
store_id identificador (UUID) · uuid: No fundo de cofre, a loja (hub_stores.id); vazio nos outros tipos.
periodo data (um dia) · date: No fundo de cofre, o primeiro dia do mês a que o mapa diz respeito (num ajuste, o do mês em que foi pedido; numa regularização, o de dezembro desse ano); vazio nos outros tipos.
beneficiario_employee_id identificador (UUID) · uuid: Ficha de quem recebe o reembolso (hub_rh_employees.id), congelada ao entregar; no fundo, a do responsável.
beneficiario_nome texto · text: Nome de quem recebe o reembolso, congelado ao entregar.
beneficiario_nif texto · text: NIF de quem recebe o reembolso (9 algarismos), congelado ao entregar.
responsavel_user_id identificador (UUID) · uuid: No fundo de cofre, conta do responsável congelada ao entregar (hub_users.id), para quem vai a reposição.
centro_custo_id identificador (UUID) · uuid: Centro de custo (hub_stores.id), congelado ao entregar: o da loja da ficha do beneficiário ou da loja do fundo.
pagamento_forma texto · text: Como se paga: «transferencia» ou «vencimento» (com o salário, só em mapas de km).
valor_fixo_snapshot número decimal · numeric: No fundo de cofre, o valor fixo do fundo em euros no momento da entrega.
local_habitual_texto texto · text: Nos mapas de km, o nome do local de trabalho habitual da pessoa no momento da entrega.
declaracao_versao texto · text: Versão do texto da declaração aceite ao entregar (por exemplo «desp-2026-09», «km-2026-09», «fnd-2026-09»).
total número decimal · numeric: Total do mapa em euros (faturas com IVA, ou km × valor), congelado ao entregar; no fundo com despesas recusadas, o total aprovado; num ajuste do fundo, a diferença entre o valor pedido e o de antes (negativa numa devolução).
n_linhas número inteiro · integer: Número de despesas ou deslocações ativas no momento da entrega.
exercicio número inteiro · integer: Ano das despesas ou deslocações, que é o ano do número do mapa.
submetido_em data e hora, com fuso · timestamp with time zone: Instante da última entrega.
submetido_por identificador (UUID) · uuid: Conta que fez a última entrega (hub_users.id).
decidido_em data e hora, com fuso · timestamp with time zone: Instante da aprovação; vazio enquanto não aprovado ou depois de devolvido.
decidido_por identificador (UUID) · uuid: Conta que aprovou (hub_users.id).
iban_sha256_aprovado texto · text: Resumo sha256 do IBAN do beneficiário no momento da aprovação; o pagamento recusa-se se o IBAN mudou entretanto.
pago_em data (um dia) · date: Dia da transferência, ou do pagamento do vencimento em que os km foram incluídos; na devolução de um ajuste do fundo, o dia em que chegou ao escritório.
pago_por identificador (UUID) · uuid: Conta que registou o pagamento (hub_users.id).
pagamento_ref texto · text: Referência do pagamento escrita por quem pagou (até 100 caracteres), ou «Vencimento MM/AAAA».
mes_vencimento data (um dia) · date: Nos km pagos com o salário, o primeiro dia do mês desse vencimento.
iban_usado_mascarado texto · text: IBAN para onde se transferiu, só com os 4 primeiros e os 4 últimos caracteres (por exemplo «PT50 ••• 1234»).
iban_usado_sha256 texto · text: Resumo sha256 do IBAN completo para onde se transferiu.
anulado_em data e hora, com fuso · timestamp with time zone: Instante da anulação.
anulado_por identificador (UUID) · uuid: Conta que anulou (hub_users.id).
anulado_motivo texto · text: Motivo da anulação (pelo menos 3 caracteres).
updated_at data e hora, com fuso · timestamp with time zone · obrigatório: Instante da última alteração ao mapa.
assinatura_path texto · text: Nos mapas de km, caminho da imagem PNG da assinatura desenhada no ecrã, no armazenamento de ficheiros; o ficheiro vai na cópia, com o índice.
assinatura_sha256 texto · text: Resumo sha256 da imagem da assinatura calculado no browser (informativo).
assinado_em data e hora, com fuso · timestamp with time zone: Instante da assinatura e da entrega, segundo o relógio do servidor.
assinatura_conteudo_sha256 texto · text: Resumo sha256 do conteúdo assinado (número, beneficiário, declaração, total e cada deslocação); a aprovação recusa um mapa que já não lhe corresponda.
variante texto · text: Nos mapas do fundo de cofre: vazio no mapa do mês; «ajuste» na mudança do valor do fundo (o reforço, ou a devolução da diferença), sem despesas; «regularizacao» quando junta os documentos de um ano que chegaram depois de entregue o mapa de dezembro.
ajuste_de número decimal · numeric: Num ajuste do fundo, o valor fixo do fundo em euros antes da mudança; vazio nos outros mapas.
ajuste_para número decimal · numeric: Num ajuste do fundo, o valor fixo pedido em euros (passa a valer quando o ajuste é aprovado); vazio nos outros mapas.

`hub_desp_numeracao` Numeração dos mapas

O último número atribuído a cada tipo de mapa em cada ano; os números são sequenciais, sem buracos, e nunca descem.

tipo texto · text · obrigatório: Tipo de mapa: «despesas» (DSP), «km» (KM) ou «fundo» (FND).
exercicio número inteiro · integer · obrigatório: Ano da numeração.
ultimo número inteiro · integer · obrigatório: Último número sequencial atribuído nesse tipo e ano.

`hub_desp_rotas_uso` Uso diário do serviço de mapas

Contadores, por conta e dia, das pesquisas de locais e dos cálculos de distância feitos no serviço de mapas; servem os limites diários e apagam-se ao fim de 30 dias.

user_id identificador (UUID) · uuid · obrigatório: Conta que fez as pesquisas e os cálculos (hub_users.id).
dia data (um dia) · date · obrigatório: Dia a que os contadores dizem respeito (hora de Lisboa).
sugestoes número inteiro · integer · obrigatório: Número de pesquisas de locais nesse dia (limite diário de 60).
calculos número inteiro · integer · obrigatório: Número de cálculos de distância nesse dia (limite diário de 40).

`hub_desp_viaturas` Viaturas dos mapas de km

Viaturas registadas por cada conta para os mapas de km, com a declaração de que não são da empresa. Não se editam: uma viatura mudada desativa-se e cria-se outra.

id identificador (UUID) · uuid · obrigatório: Identificador da viatura.
user_id identificador (UUID) · uuid · obrigatório: Conta que registou a viatura (hub_users.id).
employee_id identificador (UUID) · uuid: Ficha do colaborador ligada à conta ao registar (hub_rh_employees.id).
matricula texto · text · obrigatório: Matrícula: três pares separados por hífen, cada par só letras ou só algarismos, com pelo menos um de cada (por exemplo «AA-00-AA» ou «00-AA-00»).
proprietario_tipo texto · text · obrigatório: De quem é: «proprio» (da própria pessoa) ou «outro» (de outra pessoa, por exemplo um familiar).
proprietario_nome texto · text: Nome do proprietário, só quando proprietario_tipo é «outro».
descricao texto · text: Descrição curta dada pela pessoa (até 60 caracteres), opcional.
ativa verdadeiro ou falso · boolean · obrigatório: Falso quando a viatura foi desativada; fica guardada para as deslocações que a usam.
declaracao_em data e hora, com fuso · timestamp with time zone · obrigatório: Instante em que a pessoa declarou que a viatura não é da empresa nem alugada por ela (renting).
criado_em data e hora, com fuso · timestamp with time zone · obrigatório: Instante do registo.

Vendas por loja

`hub_rh_sales` Vendas mensais por loja (antigas)

Tabela antiga de vendas por loja e mês. A plataforma já não lê nem escreve nela (as vendas estão em hub_rh_sales_daily), mas os dados que tenha ficam guardados.

id identificador (UUID) · uuid · obrigatório: Identificador da linha.
store_id identificador (UUID) · uuid: Loja (hub_stores.id).
period data (um dia) · date · obrigatório: Mês das vendas, indicado pelo seu primeiro dia.
amount número decimal · numeric · obrigatório: Total das vendas do mês, em euros.

`hub_rh_sales_daily` Vendas diárias por loja

Totais de vendas de cada loja por dia, importados dos relatórios do sistema de faturação (POS) ou lidos diretamente dele quando o dia fecha. Uma linha por loja e dia.

id identificador (UUID) · uuid · obrigatório: Identificador da linha.
store_id identificador (UUID) · uuid: Loja (hub_stores.id).
sale_date data (um dia) · date · obrigatório: Dia de negócio das vendas.
tickets número inteiro · integer · obrigatório: Número de talões (documentos de venda) do dia.
qty número decimal · numeric · obrigatório: Quantidade total de artigos vendidos no dia.
amount_excl_vat número decimal · numeric · obrigatório: Total das vendas sem IVA, em euros.
vat_amount número decimal · numeric · obrigatório: Total do IVA das vendas, em euros.
amount_incl_vat número decimal · numeric · obrigatório: Total das vendas com IVA, em euros.
origem texto · text · obrigatório: De onde vieram as vendas do dia: «pos» (lidas diretamente do sistema de faturação quando o dia fecha) ou «ficheiro» (importadas de um relatório).

`hub_rh_sales_hourly` Vendas por hora por loja

Vendas de cada loja por dia e hora, importadas dos relatórios horários do sistema de faturação (POS) ou lidas diretamente dele. Uma linha por loja, dia e hora.

id identificador (UUID) · uuid · obrigatório: Identificador da linha.
store_id identificador (UUID) · uuid: Loja (hub_stores.id).
sale_date data (um dia) · date · obrigatório: Dia de negócio das vendas.
hour número inteiro · smallint · obrigatório: Hora do dia, de 0 a 23: 9 = das 9:00 às 9:59.
tickets número inteiro · integer · obrigatório: Número de talões nessa hora.
amount_excl_vat número decimal · numeric · obrigatório: Vendas sem IVA nessa hora, em euros.
amount_incl_vat número decimal · numeric · obrigatório: Vendas com IVA nessa hora, em euros.
people número inteiro · integer · obrigatório: Número de pessoas atendidas nessa hora, segundo o relatório horário; nos dias lidos diretamente do POS é igual ao número de talões.

`hub_vd_pos_artigos` Vendas por artigo lidas do POS

Uma linha por loja, dia e artigo, com o que o sistema de faturação (POS) diz ter vendido nos dias lidos pela reconstrução do histórico ou abrangidos por uma substituição. Serve para comparar com os ficheiros e para os substituir.

store_id identificador (UUID) · uuid · obrigatório: Loja (hub_stores.id).
dia data (um dia) · date · obrigatório: Dia de negócio (as vendas depois da meia-noite contam no dia anterior).
codigo texto · text · obrigatório: Código do artigo no POS (corresponde a hub_vendas_produtos.cod_artigo).
descricao texto · text: Nome do artigo no POS nesse dia.
qtd número decimal · numeric · obrigatório: Unidades vendidas: todas as linhas dos talões de venda não anulados, incluindo os componentes de menus e de packs.
liquido número decimal · numeric · obrigatório: Valor vendido sem IVA, em euros.
total número decimal · numeric · obrigatório: Valor vendido com IVA, em euros.

`hub_vd_pos_artigos_hora` Vendas do ano anterior por hora

Uma linha por loja, hora e artigo do dia do ano anterior com que o quadro diário compara o dia em curso (364 dias antes, o mesmo dia da semana). Guardam-se só as duas últimas semanas.

store_id identificador (UUID) · uuid · obrigatório: Loja (hub_stores.id).
dia data (um dia) · date · obrigatório: Dia de negócio do ano anterior que foi lido (o dia em curso menos 364 dias).
hora número inteiro · smallint · obrigatório: Hora do talão, de 0 a 23 (as vendas depois da meia-noite continuam no mesmo dia de negócio).
codigo texto · text · obrigatório: Código do artigo no POS (corresponde a hub_vendas_produtos.cod_artigo).
qtd número decimal · numeric · obrigatório: Unidades vendidas nessa hora.
total número decimal · numeric · obrigatório: Valor vendido nessa hora, com IVA, em euros.
liquido número decimal · numeric · obrigatório: Valor vendido nessa hora, sem IVA, em euros.

`hub_vd_pos_dias` Dias de venda lidos do POS

Uma linha por loja e dia de negócio, com o que o sistema de faturação (POS) diz desse dia: estado, vendas, talões, consumo interno, quebras, anulações e a curva por hora.

store_id identificador (UUID) · uuid · obrigatório: Loja (hub_stores.id).
dia data (um dia) · date · obrigatório: Dia de negócio (as vendas depois da meia-noite contam no dia anterior).
zs_loja número inteiro · smallint · obrigatório: Número da loja no POS usado na leitura (hub_vd_pos_lojas.zs_loja).
estado texto · text · obrigatório: «aberto» (alguma caixa ainda aberta, ou dia de hoje ainda sem caixas) ou «fechado» (todas as caixas fecharam).
final verdadeiro ou falso · boolean · obrigatório: Dia dado como definitivo: fechado no POS, ou com dois ou mais dias. Só ao gravar um dia final se escrevem as vendas diárias, por hora e por artigo (nunca num dia com manter_ficheiros); um dia que reabre volta a falso e essas vendas ficam as do fecho anterior.
aberto_em data e hora · timestamp without time zone: Data e hora da primeira abertura de caixa do dia, na hora local do POS (sem fuso).
fechado_em data e hora · timestamp without time zone: Data e hora do último fecho de caixa, na hora local do POS (sem fuso); vazio enquanto o dia está aberto.
caixas número inteiro · smallint · obrigatório: Número de caixas com sessão nesse dia.
documentos número inteiro · integer · obrigatório: Número de documentos do dia no POS, de todos os tipos (vendas, consumo interno, quebras e anulados).
taloes número inteiro · integer · obrigatório: Número de talões de venda não anulados (documentos dos tipos FS, FT, FA e NC).
total número decimal · numeric · obrigatório: Vendas do dia com IVA, em euros: soma dos talões de venda não anulados (as notas de crédito entram negativas).
liquido número decimal · numeric · obrigatório: Vendas do dia sem IVA, em euros.
qtd número decimal · numeric: Unidades vendidas (soma das quantidades das linhas dos talões de venda); só num dia final, senão vazio.
ci_docs número inteiro · integer · obrigatório: Número de documentos de consumo interno (tipo CI) não anulados.
ci_total número decimal · numeric · obrigatório: Valor dos documentos de consumo interno, em euros.
qb_docs número inteiro · integer · obrigatório: Número de documentos de quebra (tipo QB) não anulados.
qb_total número decimal · numeric · obrigatório: Valor dos documentos de quebra, em euros, como o POS o regista (nalgumas lojas é zero).
anul_docs número inteiro · integer · obrigatório: Número de talões de venda anulados.
anul_total número decimal · numeric · obrigatório: Valor dos talões de venda anulados, em euros com IVA.
horas JSON · jsonb · obrigatório: Curva do dia pela hora do talão: lista de {h (0 a 23), taloes, total (com IVA), liquido (sem IVA)}.
lido_completo_em data e hora, com fuso · timestamp with time zone: Num dia aberto, o instante em que se leram pela última vez todos os talões do dia; vazio num dia final.
final_em data e hora, com fuso · timestamp with time zone: Instante em que o dia foi gravado como definitivo pela última vez; vazio se nunca o foi (um dia que reabre guarda o instante do fecho anterior).
atualizado_em data e hora, com fuso · timestamp with time zone · obrigatório: Instante da última gravação desta linha.
historico verdadeiro ou falso · boolean · obrigatório: Dia lido pela reconstrução do histórico (ou abrangido por uma substituição), e não pela leitura do dia a dia.
trocado verdadeiro ou falso · boolean · obrigatório: As vendas deste dia que vinham dos ficheiros foram substituídas pelas do POS; a cópia fica nas tabelas hub_vd_pos_sombra_*.
manter_ficheiros verdadeiro ou falso · boolean · obrigatório: O dia fica com as vendas carregadas por ficheiro: a leitura do POS nunca as substitui.

`hub_vd_pos_disparos` Pedidos de leitura automática

Uma linha por pedido que a base de dados faz, de minuto a minuto, à função de leitura do sistema de faturação (POS), com a resposta recebida. Guardam-se dois dias.

id identificador (UUID) · uuid · obrigatório: Identificador do pedido.
criado_em data e hora, com fuso · timestamp with time zone · obrigatório: Instante do pedido.
expira_em data e hora, com fuso · timestamp with time zone · obrigatório: Instante até ao qual a senha de uso único do pedido é válida (cinco minutos depois).
usado_em data e hora, com fuso · timestamp with time zone: Instante em que a função de leitura usou a senha; vazio se nunca a usou.
pedido_id número inteiro · bigint: Número do pedido HTTP na fila de pedidos de saída da base de dados.
resposta_http número inteiro · integer: Código HTTP com que a função respondeu (409 = a execução anterior ainda corria, não é erro); vazio até chegar a resposta.
erro texto · text: Erro do pedido: tempo esgotado, falha de rede ou o corpo de uma resposta sem sucesso; vazio se correu bem.

Não vão na cópia: senha_hash (dados de segurança do acesso (cláusula 17.7, alínea b))).

`hub_vd_pos_docs` Talões dos dias em curso

Uma linha por documento do POS de um dia ainda não definitivo, só com números e códigos (nunca dados do cliente final). Saem quando o dia é gravado como definitivo, ou ao fim de três dias.

store_id identificador (UUID) · uuid · obrigatório: Loja (hub_stores.id).
doc texto · text · obrigatório: Tipo de documento no POS, até 4 letras: «FS», «FT», «FA» e «NC» (vendas), «CI» (consumo interno), «QB» (quebra) ou outro.
serie texto · text · obrigatório: Série do documento no POS.
numero número inteiro · bigint · obrigatório: Número do documento na série.
dia data (um dia) · date · obrigatório: Dia de negócio a que o documento pertence (depois da meia-noite, o dia anterior).
datahora data e hora · timestamp without time zone: Data e hora do documento, na hora local do POS (sem fuso).
total número decimal · numeric · obrigatório: Total do documento com IVA, em euros (negativo nas notas de crédito).
liquido número decimal · numeric · obrigatório: Total do documento sem IVA, em euros.
anulado verdadeiro ou falso · boolean · obrigatório: O documento foi anulado no POS.
pagamento número inteiro · integer: Código do meio de pagamento (hub_vd_pos_meios.codigo da loja); 9 = pago com vários meios.
linhas JSON · jsonb: Linhas de um talão de venda: lista de {c (código do artigo), q (quantidade), t (total com IVA), v (valor sem IVA)}; vazio nos outros documentos.

`hub_vd_pos_hist_saltados` Dias saltados do histórico

Uma linha por loja e dia que a reconstrução do histórico não conseguiu ler à terceira tentativa e deixou para trás.

store_id identificador (UUID) · uuid · obrigatório: Loja (hub_stores.id).
dia data (um dia) · date · obrigatório: Dia de negócio que ficou por ler.
erro texto · text: Texto do último erro desse dia.
em data e hora, com fuso · timestamp with time zone · obrigatório: Instante em que o dia foi saltado.

`hub_vd_pos_horas_falhas` Falhas na leitura do ano anterior

Uma linha por loja e dia do ano anterior cuja leitura por hora e artigo falhou; a loja só volta a ser pedida depois de uma espera.

store_id identificador (UUID) · uuid · obrigatório: Loja (hub_stores.id).
dia data (um dia) · date · obrigatório: Dia de negócio do ano anterior que se tentou ler.
tentativas número inteiro · integer · obrigatório: Número de falhas seguidas.
proximo_em data e hora, com fuso · timestamp with time zone · obrigatório: Instante a partir do qual se volta a tentar (10 min, 30 min, depois 2 h; 1 h se o POS pediu para abrandar).
erro texto · text: Texto do último erro.
falhou_em data e hora, com fuso · timestamp with time zone · obrigatório: Instante da última falha.

`hub_vd_pos_horas_lidas` Leituras do ano anterior

Uma linha por loja e dia do ano anterior já lido por hora e artigo (em hub_vd_pos_artigos_hora). Guardam-se só as duas últimas semanas.

store_id identificador (UUID) · uuid · obrigatório: Loja (hub_stores.id).
dia data (um dia) · date · obrigatório: Dia de negócio do ano anterior que foi lido.
lido_em data e hora, com fuso · timestamp with time zone · obrigatório: Instante da leitura.
linhas número inteiro · integer · obrigatório: Número de linhas (hora e artigo) gravadas; zero se a loja não vendeu nesse dia.

`hub_vd_pos_lojas` Lojas ligadas ao POS

Uma linha por loja ligada à leitura automática: o número dela no sistema de faturação (POS), desde quando as vendas vêm dele e o estado das leituras e da reconstrução do histórico.

zs_loja número inteiro · smallint · obrigatório: Número da loja no POS, de 1 a 99 (chave).
store_id identificador (UUID) · uuid · obrigatório: Loja da empresa (hub_stores.id); cada loja só se liga uma vez.
ativo verdadeiro ou falso · boolean · obrigatório: A loja está a ser lida.
dia_inicio data (um dia) · date · obrigatório: Primeiro dia cujas vendas vêm do POS; daí em diante os ficheiros já não as escrevem. Recua quando se substituem dias anteriores.
marca texto · text: Data da alteração mais recente entre os documentos já lidos, na hora local do POS (texto AAAA-MM-DD hh:mm:ss); a leitura seguinte parte daqui.
meios_em data e hora, com fuso · timestamp with time zone: Instante em que se leram pela última vez os nomes dos meios de pagamento (uma vez por dia).
ultimo_ok_em data e hora, com fuso · timestamp with time zone: Instante da última leitura bem-sucedida desta loja.
ultimo_erro texto · text: Último erro da leitura desta loja, ou de um dia fechado ainda por gravar; vazio quando está tudo bem.
ultimo_erro_em data e hora, com fuso · timestamp with time zone: Instante desse erro.
criado_em data e hora, com fuso · timestamp with time zone · obrigatório: Instante em que a loja foi ligada.
hist_desde data (um dia) · date: Primeiro dia da loja no POS: até onde recua a reconstrução do histórico.
hist_cursor data (um dia) · date: Próximo dia a ler na reconstrução do histórico, que anda para trás; vazio quando acabou ou ainda não começou.
hist_falhas número inteiro · integer · obrigatório: Falhas seguidas do dia do cursor por defeito desse dia; à terceira o dia é saltado (hub_vd_pos_hist_saltados).
hist_erro texto · text: Último erro da reconstrução do histórico nesta loja.
hist_erro_em data e hora, com fuso · timestamp with time zone: Instante desse erro.
hist_feito_em data e hora, com fuso · timestamp with time zone: Instante em que a reconstrução do histórico desta loja acabou; vazio enquanto não acabou.

`hub_vd_pos_lotes` Execuções da leitura do POS

Uma linha por execução da leitura automática do sistema de faturação (POS), de minuto a minuto ou pedida à mão, com o resultado. Guardam-se sete dias.

id identificador (UUID) · uuid · obrigatório: Identificador da execução.
origem texto · text · obrigatório: «cron» (automática, de minuto a minuto) ou «manual» (pedida por um utilizador).
user_id identificador (UUID) · uuid: Utilizador que a pediu (hub_users.id); só nas execuções manuais.
iniciado_em data e hora, com fuso · timestamp with time zone · obrigatório: Instante em que começou.
terminado_em data e hora, com fuso · timestamp with time zone: Instante em que acabou; vazio enquanto corre.
estado texto · text · obrigatório: «a_correr», «ok» (todas as lojas bem), «parcial» (algumas lojas com erro) ou «erro» (nenhuma loja bem, ou interrompida).
resumo JSON · jsonb: Resultado detalhado: lojas (por loja: zs_loja, ok, erro, ref, dias gravados, pedidos ao POS, produtos novos), erro geral e, se houve, hist (histórico) e horas (ano anterior).
erro texto · text: Erro geral ou, por loja, os erros das que falharam; vazio se correu bem.

`hub_vd_pos_meios` Meios de pagamento do POS

Uma linha por loja e meio de pagamento, com o nome que a loja lhe dá no sistema de faturação (POS).

zs_loja número inteiro · smallint · obrigatório: Número da loja no POS (hub_vd_pos_lojas.zs_loja).
codigo número inteiro · integer · obrigatório: Código do meio de pagamento no POS.
descricao texto · text · obrigatório: Nome do meio de pagamento.
atualizado_em data e hora, com fuso · timestamp with time zone · obrigatório: Instante da última leitura deste nome.

`hub_vd_pos_pagamentos` Vendas por meio de pagamento

Uma linha por loja, dia e meio de pagamento, com o valor recebido nos talões de venda desse dia, como o sistema de faturação (POS) o dá.

store_id identificador (UUID) · uuid · obrigatório: Loja (hub_stores.id).
dia data (um dia) · date · obrigatório: Dia de negócio.
codigo número inteiro · integer · obrigatório: Código do meio de pagamento (hub_vd_pos_meios.codigo da loja); 9 = vários meios: num dia final, só o que o POS não repartiu; num dia ainda aberto, o total desses talões.
valor número decimal · numeric · obrigatório: Valor recebido com este meio, em euros com IVA.
documentos número inteiro · integer · obrigatório: Número de talões pagos com este meio.

`hub_vd_pos_pendentes` Fila de dias por ler

Uma linha por loja e dia que a leitura automática ainda tem de ler ou reler: dias com documentos alterados no POS, o dia em curso e a releitura de madrugada. Sai quando o dia é gravado como definitivo.

zs_loja número inteiro · smallint · obrigatório: Número da loja no POS (hub_vd_pos_lojas.zs_loja).
dia data (um dia) · date · obrigatório: Dia de negócio por ler.
desde data e hora, com fuso · timestamp with time zone · obrigatório: Instante em que o dia entrou na fila.
falhas número inteiro · integer · obrigatório: Falhas por defeito dos dados desse dia; o dia espera 10 min, 30 min, depois 2 h, e dá alerta à terceira.
proximo_em data e hora, com fuso · timestamp with time zone: O dia só volta a ler-se a partir deste instante; vazio = na próxima execução.
ultimo_erro texto · text: Texto da última falha.
falhou_em data e hora, com fuso · timestamp with time zone: Instante da última falha; vazio se nunca falhou.
falhas_zs número inteiro · integer · obrigatório: Falhas seguidas por o POS não responder bem; o dia espera sempre 10 min e dá alerta à décima segunda.

`hub_vd_pos_quebras` Quebras por artigo lidas do POS

Uma linha por loja, dia e artigo registado como quebra (documentos QB) num dia definitivo do sistema de faturação (POS).

store_id identificador (UUID) · uuid · obrigatório: Loja (hub_stores.id).
dia data (um dia) · date · obrigatório: Dia de negócio.
codigo texto · text · obrigatório: Código do artigo no POS.
descricao texto · text: Nome do artigo.
qtd número decimal · numeric · obrigatório: Unidades dadas como quebra.
valor número decimal · numeric · obrigatório: Valor das quebras como o POS o regista, em euros (nalgumas lojas é zero).

`hub_vd_pos_sombra_artigos` Cópia das vendas por artigo substituídas

Cópia das linhas de vendas por artigo que tinham vindo dos ficheiros, guardada antes de serem substituídas pelas do sistema de faturação (POS); serve para as repor.

id identificador (UUID) · uuid · obrigatório: Identificador da linha original (hub_vendas_artigos_dia.id), mantido para a reposição.
store_id identificador (UUID) · uuid · obrigatório: Loja (hub_stores.id).
sale_date data (um dia) · date · obrigatório: Dia de negócio.
produto_id identificador (UUID) · uuid · obrigatório: Produto (hub_vendas_produtos.id).
qty número decimal · numeric · obrigatório: Unidades vendidas.
amount_excl_vat número decimal · numeric · obrigatório: Valor vendido sem IVA, em euros.
amount_incl_vat número decimal · numeric · obrigatório: Valor vendido com IVA, em euros.
copiado_em data e hora, com fuso · timestamp with time zone · obrigatório: Instante da cópia.

`hub_vd_pos_sombra_daily` Cópia das vendas diárias substituídas

Cópia dos totais diários por loja que tinham vindo dos ficheiros, guardada antes de serem substituídos pelos do sistema de faturação (POS); serve para os repor.

id identificador (UUID) · uuid · obrigatório: Identificador da linha original (hub_rh_sales_daily.id), mantido para a reposição.
store_id identificador (UUID) · uuid: Loja (hub_stores.id).
sale_date data (um dia) · date · obrigatório: Dia de negócio.
tickets número inteiro · integer · obrigatório: Número de talões (clientes) do dia.
qty número decimal · numeric · obrigatório: Unidades vendidas.
amount_excl_vat número decimal · numeric · obrigatório: Vendas sem IVA, em euros.
vat_amount número decimal · numeric · obrigatório: IVA das vendas, em euros.
amount_incl_vat número decimal · numeric · obrigatório: Vendas com IVA, em euros.
copiado_em data e hora, com fuso · timestamp with time zone · obrigatório: Instante da cópia.

`hub_vd_pos_sombra_hourly` Cópia das vendas por hora substituídas

Cópia das vendas por loja, dia e hora que tinham vindo dos ficheiros, guardada antes de serem substituídas pelas do sistema de faturação (POS); serve para as repor.

id identificador (UUID) · uuid · obrigatório: Identificador da linha original (hub_rh_sales_hourly.id), mantido para a reposição.
store_id identificador (UUID) · uuid: Loja (hub_stores.id).
sale_date data (um dia) · date · obrigatório: Dia de negócio.
hour número inteiro · smallint · obrigatório: Hora, de 0 a 23.
tickets número inteiro · integer · obrigatório: Número de talões nessa hora.
amount_excl_vat número decimal · numeric · obrigatório: Vendas sem IVA nessa hora, em euros.
amount_incl_vat número decimal · numeric · obrigatório: Vendas com IVA nessa hora, em euros.
people número inteiro · integer · obrigatório: Número de pessoas atendidas nessa hora, como vinha do ficheiro.
copiado_em data e hora, com fuso · timestamp with time zone · obrigatório: Instante da cópia.

`hub_vd_pos_trocas` Substituições de ficheiros pelo POS

Uma linha por loja cujas vendas carregadas por ficheiro foram substituídas pelas lidas do sistema de faturação (POS), com o período e o que é preciso para desfazer.

store_id identificador (UUID) · uuid · obrigatório: Loja (hub_stores.id).
zs_loja número inteiro · smallint · obrigatório: Número da loja no POS.
dia_inicio_antes data (um dia) · date · obrigatório: Primeiro dia lido do POS antes da substituição; a loja volta a ele se a substituição for desfeita.
de data (um dia) · date · obrigatório: Primeiro dia substituído.
ate data (um dia) · date · obrigatório: Último dia do período substituído.
dias número inteiro · integer · obrigatório: Número de dias substituídos.
produtos_criados lista de identificadores · _uuid · obrigatório: Produtos criados pela substituição (lista de hub_vendas_produtos.id); saem ao desfazer se continuarem pendentes e sem vendas.
trocado_em data e hora, com fuso · timestamp with time zone · obrigatório: Instante da substituição.
reposto_em data e hora, com fuso · timestamp with time zone: Instante em que foi desfeita; vazio enquanto está em vigor.

`hub_vendas_artigos_dia` Vendas diárias por artigo

Uma linha por loja, dia e produto, com a quantidade e o valor vendidos, vinda dos ficheiros carregados ou da leitura automática do sistema de faturação (POS). Alimenta as categorias dos quadros de vendas.

id identificador (UUID) · uuid · obrigatório: Identificador da linha.
store_id identificador (UUID) · uuid · obrigatório: Loja (hub_stores.id).
sale_date data (um dia) · date · obrigatório: Dia de negócio.
produto_id identificador (UUID) · uuid · obrigatório: Produto (hub_vendas_produtos.id).
qty número decimal · numeric · obrigatório: Unidades vendidas.
amount_excl_vat número decimal · numeric · obrigatório: Valor vendido sem IVA, em euros.
amount_incl_vat número decimal · numeric · obrigatório: Valor vendido com IVA, em euros.

`hub_vendas_artigos_dia_cadeia` Vendas diárias por artigo, somadas de todas as lojas

Uma linha por dia e produto com a soma das vendas por artigo de todas as lojas (hub_vendas_artigos_dia), mantida sozinha a cada escrita. Serve para os quadros e a lista de produtos da cadeia inteira responderem depressa; não tem nada que não esteja nas vendas por artigo.

sale_date data (um dia) · date · obrigatório: Dia de negócio.
produto_id identificador (UUID) · uuid · obrigatório: Produto (hub_vendas_produtos.id).
linhas número inteiro · integer · obrigatório: Quantas lojas venderam o produto nesse dia (as linhas somadas).
qty número decimal · numeric · obrigatório: Unidades vendidas, somadas de todas as lojas.
amount_excl_vat número decimal · numeric · obrigatório: Valor vendido sem IVA, em euros, somado de todas as lojas.
amount_incl_vat número decimal · numeric · obrigatório: Valor vendido com IVA, em euros, somado de todas as lojas.

`hub_vendas_categorias` Categorias dos quadros de vendas

Uma linha por categoria de produtos, que aparece como linha nos quadros diário, semanal e mensal do módulo Vendas.

id identificador (UUID) · uuid · obrigatório: Identificador da categoria.
nome texto · text · obrigatório: Nome da categoria (único).
ordem número inteiro · integer · obrigatório: Posição da linha nos quadros, por ordem crescente.
ativa verdadeiro ou falso · boolean · obrigatório: Aparece nos quadros; desativada, sai de todo o histórico dos quadros sem se apagar nenhum dado.
created_at data e hora, com fuso · timestamp with time zone: Instante da criação.

`hub_vendas_produtos` Produtos e sua classificação

Uma linha por artigo vendido, identificado pelo código do sistema de faturação (POS), com a classificação que decide como conta nos quadros por categoria.

id identificador (UUID) · uuid · obrigatório: Identificador do produto.
cod_artigo texto · text · obrigatório: Código do artigo no POS (único): a identidade do produto.
nome texto · text · obrigatório: Nome do artigo; acompanha o nome que o POS lhe dá.
familia texto · text: Família do artigo no POS, como vem nos ficheiros exportados (a leitura automática não a traz).
estado texto · text · obrigatório: «mapeado» (conta na categoria indicada), «ignorado» (fora dos quadros por categoria) ou «pendente» (por classificar; um produto novo entra assim).
categoria_id identificador (UUID) · uuid: Categoria (hub_vendas_categorias.id); obrigatória quando «mapeado», vazia nos outros estados.
multiplicador número decimal · numeric · obrigatório: Fator, maior que zero, pelo qual a quantidade vendida se multiplica ao somar na categoria (1 = conta tal como vendida).
updated_at data e hora, com fuso · timestamp with time zone: Instante da última classificação (ou da criação, se nunca foi classificado).
updated_by identificador (UUID) · uuid: Utilizador que fez a última classificação (hub_users.id); vazio se nunca foi classificado à mão.
custo_unitario número decimal · numeric: Custo de uma unidade do artigo, em euros (0 a 100 000), definido à mão por quem gere os produtos; dá o valor das quebras a custo. Vazio = sem custo definido.

`hub_vendas_uploads` Ficheiros de vendas carregados

Uma linha por ficheiro exportado do sistema de faturação (POS) e carregado à mão no módulo Vendas.

id identificador (UUID) · uuid · obrigatório: Identificador do carregamento.
tipo texto · text · obrigatório: «vendas» (totais diários por loja, gravados em hub_rh_sales_daily) ou «artigos» (vendas por artigo e dia, em hub_vendas_artigos_dia).
ficheiro texto · text: Nome do ficheiro carregado.
periodo_min data (um dia) · date: Primeiro dia com vendas no ficheiro.
periodo_max data (um dia) · date: Último dia com vendas no ficheiro.
lojas número inteiro · integer: Número de lojas reconhecidas no ficheiro.
linhas número inteiro · integer: Número de linhas gravadas.
novos_produtos número inteiro · integer: Produtos novos criados pelo carregamento (só nos ficheiros de artigos).
user_id identificador (UUID) · uuid: Utilizador que carregou o ficheiro (hub_users.id).
created_at data e hora, com fuso · timestamp with time zone: Instante do carregamento.

Pedidos das lojas, comunicados e checklists

`hub_comunicado_acks` Confirmações de leitura dos comunicados

Uma linha por pessoa que confirmou ter lido um comunicado. Serve de prova de que a informação chegou.

comunicado_id identificador (UUID) · uuid · obrigatório: Comunicado lido (hub_comunicados.id).
user_id identificador (UUID) · uuid · obrigatório: Conta que confirmou a leitura (hub_users.id).
ack_at data e hora, com fuso · timestamp with time zone · obrigatório: Instante da confirmação.

`hub_comunicados` Comunicados às lojas

Uma linha por comunicado publicado pelo escritório para as lojas, com ou sem pedido de confirmação de leitura.

id identificador (UUID) · uuid · obrigatório: Identificador do comunicado.
titulo texto · text · obrigatório: Título do comunicado.
corpo texto · text: Texto do comunicado.
store_ids lista de identificadores · _uuid: Lojas a que se dirige (lista de hub_stores.id); vazio = todas as lojas.
requires_ack verdadeiro ou falso · boolean · obrigatório: Verdadeiro se cada pessoa tem de confirmar que o leu.
active verdadeiro ou falso · boolean · obrigatório: Visível para as lojas; falso = retirado (continua no histórico).
created_by identificador (UUID) · uuid · obrigatório: Conta que o publicou (hub_users.id).
created_at data e hora, com fuso · timestamp with time zone · obrigatório: Instante da publicação.

`hub_loja_checklist_runs` Preenchimentos das checklists

Uma linha por checklist preenchida numa loja num dia: o que foi verificado, as notas e quem preencheu. Serve de prova de cumprimento.

id identificador (UUID) · uuid · obrigatório: Identificador do preenchimento.
checklist_id identificador (UUID) · uuid · obrigatório: Checklist preenchida (hub_loja_checklists.id).
store_id identificador (UUID) · uuid · obrigatório: Loja (hub_stores.id).
run_date data (um dia) · date · obrigatório: Dia a que o preenchimento respeita; há um por checklist, loja e dia, e nunca num dia futuro.
respostas JSON · jsonb · obrigatório: Respostas em JSON: {código do item: verdadeiro/falso}, com os códigos dos itens de hub_loja_checklists.itens.
notas texto · text: Observações livres de quem preencheu.
done_by identificador (UUID) · uuid: Conta que gravou o preenchimento pela última vez (hub_users.id).
done_at data e hora, com fuso · timestamp with time zone · obrigatório: Instante da última gravação.

`hub_loja_checklists` Modelos de checklists das lojas

Uma linha por checklist definida pelo escritório (lista de verificação de abertura, fecho, diária ou semanal), com os itens e as lojas a que se aplica.

id identificador (UUID) · uuid · obrigatório: Identificador da checklist.
nome texto · text · obrigatório: Nome da checklist.
periodo texto · text · obrigatório: Quando se preenche: «abertura», «fecho», «diaria» ou «semanal».
itens JSON · jsonb · obrigatório: Itens a verificar, em JSON: lista ordenada de {key, label} — o código do item e o texto mostrado.
store_ids lista de identificadores · _uuid: Lojas a que se aplica (lista de hub_stores.id); vazio = todas as lojas.
active verdadeiro ou falso · boolean · obrigatório: Em uso; falso = desativada (os preenchimentos antigos ficam).
created_by identificador (UUID) · uuid: Conta que a criou (hub_users.id).
created_at data e hora, com fuso · timestamp with time zone · obrigatório: Instante de criação.

`hub_ticket_anexos` Anexos dos pedidos

Uma linha por ficheiro anexado a um pedido (fotografia ou PDF). O ficheiro vai na cópia, com este índice.

id identificador (UUID) · uuid · obrigatório: Identificador do anexo.
ticket_id identificador (UUID) · uuid · obrigatório: Pedido a que pertence (hub_tickets.id).
path texto · text · obrigatório: Caminho do ficheiro no armazenamento de ficheiros («id do pedido/identificador.extensão»; o nome original está em «nome»); o ficheiro vai na cópia, com o índice.
nome texto · text: Nome original do ficheiro, como foi enviado.
mime texto · text: Tipo do ficheiro: PDF, JPEG, PNG, WebP, HEIC ou HEIF (as fotografias chegam normalmente comprimidas em JPEG).
tamanho número inteiro · integer: Tamanho do ficheiro guardado, em bytes.
autor_user_id identificador (UUID) · uuid · obrigatório: Conta que anexou (hub_users.id).
created_at data e hora, com fuso · timestamp with time zone · obrigatório: Instante em que foi anexado.

`hub_ticket_assign_hist` Histórico de atribuições dos pedidos

Uma linha por atribuição ou reatribuição de um pedido a um responsável do escritório.

id identificador (UUID) · uuid · obrigatório: Identificador da atribuição.
ticket_id identificador (UUID) · uuid · obrigatório: Pedido (hub_tickets.id).
de_user_id identificador (UUID) · uuid: Responsável anterior (hub_users.id); vazio na primeira atribuição.
para_user_id identificador (UUID) · uuid: Novo responsável (hub_users.id).
motivo texto · text: Motivo da mudança; obrigatório numa reatribuição.
por_user_id identificador (UUID) · uuid · obrigatório: Conta que fez a atribuição (hub_users.id).
created_at data e hora, com fuso · timestamp with time zone · obrigatório: Instante da atribuição.

`hub_ticket_comments` Comentários dos pedidos

Uma linha por comentário escrito num pedido, pela loja ou pelo escritório.

id identificador (UUID) · uuid · obrigatório: Identificador do comentário.
ticket_id identificador (UUID) · uuid · obrigatório: Pedido comentado (hub_tickets.id).
autor_user_id identificador (UUID) · uuid · obrigatório: Conta que escreveu (hub_users.id).
corpo texto · text · obrigatório: Texto do comentário.
interno verdadeiro ou falso · boolean · obrigatório: Verdadeiro = nota interna do escritório, que a loja não vê.
created_at data e hora, com fuso · timestamp with time zone · obrigatório: Instante do comentário.

`hub_ticket_eventos` Histórico dos pedidos

Uma linha por acontecimento na vida de um pedido (aberto, atribuído, mudança de estado, comentário, anexo, marca de urgência, automatismos), para a cronologia mostrada no pedido.

id identificador (UUID) · uuid · obrigatório: Identificador do acontecimento.
ticket_id identificador (UUID) · uuid · obrigatório: Pedido (hub_tickets.id).
tipo texto · text · obrigatório: «aberto», «atribuido», «reatribuido», «estado», «comentario», «anexo», «urgente», «urgente_retirado», «fechado_auto», «reaberto_auto» ou «escalado_auto» (prioridade subida automaticamente).
ator_user_id identificador (UUID) · uuid: Conta que fez a ação (hub_users.id); vazio quando foi automática.
de texto · text: Valor anterior: o estado anterior ou o nome do responsável anterior (texto, não identificador).
para texto · text: Valor novo: o estado, a prioridade ou o nome do novo responsável (texto, não identificador).
detalhe texto · text: Texto adicional: motivo, nome do anexo, de quem se espera e data de revisão, ou a razão do automatismo.
interno verdadeiro ou falso · boolean · obrigatório: Verdadeiro = só o escritório vê este acontecimento (notas internas e reatribuições).
created_at data e hora, com fuso · timestamp with time zone · obrigatório: Instante do acontecimento.

`hub_ticket_notif` Avisos dos pedidos

Uma linha por aviso no sino de uma pessoa sobre um pedido (novo, atribuído, comentado, mudou de estado…), lido ou por ler.

id identificador (UUID) · uuid · obrigatório: Identificador do aviso.
user_id identificador (UUID) · uuid · obrigatório: Conta que recebe o aviso (hub_users.id).
ticket_id identificador (UUID) · uuid · obrigatório: Pedido (hub_tickets.id).
tipo_evento texto · text · obrigatório: Motivo do aviso: «novo», «atribuido», «reatribuido», «estado», «comentario», «urgente», «fechado_auto», «reaberto_auto», «resposta» (o escritório respondeu a um pedido da loja) ou «resolvida» (o escritório resolveu-o); estes dois vão a todas as contas da loja que veem os pedidos dela.
lido verdadeiro ou falso · boolean · obrigatório: Verdadeiro depois de a pessoa o marcar como lido ou de abrir o pedido.
created_at data e hora, com fuso · timestamp with time zone · obrigatório: Instante do aviso.

`hub_tickets` Pedidos das lojas e tarefas internas

Uma linha por pedido de uma loja ao escritório (avaria, falta de material, reclamação…) ou por tarefa interna do escritório, com o estado, a prioridade e o responsável.

id identificador (UUID) · uuid · obrigatório: Identificador do pedido.
numero número inteiro · integer · obrigatório: Número curto e único do pedido (sequencial, a partir de 1000), para o referir.
tipo texto · text · obrigatório: «loja» (pedido de uma loja ao escritório) ou «interno» (tarefa interna do escritório, que as lojas não veem).
titulo texto · text · obrigatório: Título do pedido.
descricao texto · text: Descrição livre do pedido.
store_id identificador (UUID) · uuid: Loja do pedido (hub_stores.id); obrigatória nos pedidos de loja, vazia nas tarefas internas.
autor_user_id identificador (UUID) · uuid · obrigatório: Conta que abriu o pedido (hub_users.id).
categoria texto · text: Categoria escolhida da lista configurada nas definições (hub_settings «tickets_categorias»).
prioridade texto · text · obrigatório: «baixa», «normal», «alta» ou «urgente»; decidida pelo escritório ao abrir (um pedido aberto pela loja começa em «normal») e subida um nível automaticamente após 3 dias sem atividade, enquanto o pedido está «por_atribuir» ou «em_curso».
responsavel_user_id identificador (UUID) · uuid: Pessoa do escritório responsável (hub_users.id); vazio enquanto não for atribuído.
estado texto · text · obrigatório: «por_atribuir», «em_curso», «a_espera», «resolvida» ou «fechada»; um pedido de loja resolvido fecha-se sozinho 7 dias depois de resolvido, se alguém da loja já o viu (um aviso «resolvida» lido); se a loja não tem quem veja os pedidos, ao fim dos 7 dias.
espera_de texto · text: De quem se espera resposta, em texto livre; só no estado «a_espera».
espera_revisao data (um dia) · date: Dia de revisão no estado «a_espera»; passado esse dia o pedido volta sozinho a «em_curso».
created_at data e hora, com fuso · timestamp with time zone · obrigatório: Instante em que foi aberto.
first_response_at data e hora, com fuso · timestamp with time zone: Instante da primeira resposta do escritório (primeira atribuição ou primeiro comentário visível à loja).
resolved_at data e hora, com fuso · timestamp with time zone: Instante em que passou a «resolvida»; limpa-se se for reaberto.
closed_at data e hora, com fuso · timestamp with time zone: Instante em que passou a «fechada»; limpa-se se for reaberto.
updated_at data e hora, com fuso · timestamp with time zone · obrigatório: Instante da última atividade no pedido.
reopened_count número inteiro · integer · obrigatório: Número de vezes que voltou a «em_curso» depois de resolvido ou fechado.
campos_extra JSON · jsonb: Campos adicionais da categoria em JSON {código do campo: valor}; os códigos e os nomes vêm da definição «tickets_campos_extra».
urgente_loja verdadeiro ou falso · boolean · obrigatório: Marca da loja: este é o seu pedido mais urgente (só um por loja); não muda a prioridade.

Auditoria e histórico de alterações

`hub_audit_log` Registo de auditoria

Uma linha por ação registada na Plataforma (entradas, contas, perfis, fichas de colaborador, faturas, pagamentos, definições, comunicados…), com quem a fez e quando. O registo é imutável: nenhuma linha se altera nem se apaga.

id número inteiro · bigint · obrigatório: Número sequencial do registo.
actor_id identificador (UUID) · uuid: Conta que fez a ação (hub_users.id); vazio quando a ação foi automática.
action texto · text · obrigatório: Ação registada, em código (por exemplo «login», «login_falhado», «utilizador_criado», «definicao_alterada», «comunicado_publicado»); a lista é aberta.
entity_type texto · text · obrigatório: Tipo de registo afetado (por exemplo «utilizador», «perfil», «colaborador», «fatura», «pagamento», «fornecedor», «ticket»).
entity_id texto · text: Identificador do registo afetado, em texto (normalmente o id na tabela correspondente ao tipo).
detail JSON · jsonb: Pormenores da ação em JSON; as chaves variam com a ação (valores antes e depois, nomes, contagens, motivo).
created_at data e hora, com fuso · timestamp with time zone · obrigatório: Instante da ação.
verbo texto · text: O que se fez, numa palavra fixa da Plataforma (por exemplo «criou», «alterou», «apagou», «aprovou», «acedeu»); vazio nos registos anteriores ao histórico novo, que só têm a ação em código.
modulo texto · text: Módulo onde a ação aconteceu (por exemplo «rh», «tesouraria», «despesas»).
ficha_tipo texto · text: Tipo da ficha a que a ação se aplica, como está no catálogo do histórico (hub_sys_hist_tipos.tipo).
ficha_id texto · text: Identificador da ficha a que a ação se aplica, em texto.
ficha_nome texto · text: Nome da ficha no momento da ação (por exemplo o nome do colaborador ou o número do mapa), para o histórico se ler mesmo depois de a ficha mudar de nome.
mae_tipo texto · text: Tipo da ficha principal a que esta pertence (por exemplo as férias pertencem a um colaborador); vazio quando a ficha é ela própria a principal.
mae_id texto · text: Identificador da ficha principal, em texto; vazio quando a ficha é ela própria a principal.
origem texto · text: Por onde veio a ação: o ecrã, uma importação, a ligação ao sistema de faturação ou a própria Plataforma.
ator_nome texto · text: Nome de quem fez a ação, no momento em que a fez (fica mesmo que a conta mude de nome ou seja desativada).
campos JSON · jsonb: Os campos que mudaram, em JSON: para cada um, o valor antes e o valor depois. Os dados sensíveis guardam-se tapados (o IBAN só com os 4 últimos algarismos) ou só como «alterado», sem o valor (o motivo das ausências e as notas).
motivo texto · text: O motivo dado por quem fez a ação, quando a ação o pede (por exemplo ao recusar ou anular um mapa).

`hub_desp_fundo_eventos` Histórico dos fundos de cofre

Uma linha por alteração à configuração do fundo de cofre de uma loja (constituição, valor, responsável, desativação), com os valores antes e depois. As linhas nunca se alteram.

id número inteiro · bigint · obrigatório: Número sequencial da alteração.
store_id identificador (UUID) · uuid · obrigatório: Loja do fundo (hub_stores.id).
evento texto · text · obrigatório: Tipo de alteração: «constituido», «alterado», «desativado» ou «reativado».
antes JSON · jsonb: Configuração anterior em JSON: valor_fixo (euros), responsavel_user_id e ativo; vazio na constituição.
depois JSON · jsonb: Configuração nova em JSON: valor_fixo (euros), responsavel_user_id e ativo.
por identificador (UUID) · uuid · obrigatório: Conta que fez a alteração (hub_users.id).
em data e hora, com fuso · timestamp with time zone · obrigatório: Instante da alteração.

`hub_rh_access_log` Consultas a dados sensíveis

Uma linha por cada vez que um utilizador abriu dados sensíveis de uma ficha de colaborador (identificação fiscal, morada, remuneração, documentos, notas internas). Serve para saber quem viu o quê e quando.

id identificador (UUID) · uuid · obrigatório: Identificador da consulta.
viewer_id identificador (UUID) · uuid: Utilizador que consultou os dados (hub_users.id); numa consulta feita no «ver como», o administrador — nunca a conta com que a Plataforma estava a ser vista.
employee_id identificador (UUID) · uuid: Ficha consultada (hub_rh_employees.id).
fields_accessed lista de textos · _text: Lista dos campos ou blocos consultados (por exemplo «nif», «iban», «base_salary», «internal_notes», «pay_items», «documents»); as leituras feitas pelas despesas levam o contexto, como «iban (despesas N.º do mapa)» ou «nif (despesas: exportação de AAAA-MM)». Depois de um apagamento a pedido do titular fica «(apagado a pedido do titular)».
accessed_at data e hora, com fuso · timestamp with time zone: Instante da consulta.
ver_como_id identificador (UUID) · uuid: Acesso «ver como» em que a consulta foi feita (hub_sys_ver_como.id); vazio numa consulta normal.

`hub_rh_events` Histórico das fichas

Uma linha por acontecimento ou alteração na ficha de um colaborador (admissão, saída, readmissão, mudança de função, de loja, de morada, de remuneração ou de qualquer outro campo), com o valor antigo e o novo, até à entrada do histórico novo. Desde então não recebe linhas novas: as alterações da ficha ficam no registo de auditoria (hub_audit_log, com ficha_tipo «colaborador» e os campos que mudaram).

id identificador (UUID) · uuid · obrigatório: Identificador do acontecimento.
employee_id identificador (UUID) · uuid: Colaborador (hub_rh_employees.id).
event_type texto · text: O que aconteceu: «admissao», «readmissao», «saida», «funcao», «loja», «morada», «carro», «vencimento», «gestor» (antigo), ou o nome da coluna de hub_rh_employees que mudou.
old_value texto · text: Valor antes da alteração, em texto. Vazio nos dados fiscais, no IBAN e na remuneração; numa mudança de loja, o hub_stores.id. Apagado a pedido do titular: «(apagado a pedido do titular)».
new_value texto · text: Valor depois da alteração, em texto, com as mesmas regras de old_value (na admissão, o nome completo; na saída e na readmissão, a data).
event_date data e hora, com fuso · timestamp with time zone: Instante do acontecimento; na admissão, a data de admissão.
author identificador (UUID) · uuid: Utilizador que fez a alteração (hub_users.id).

`hub_sys_avisos_conta` Avisos de alterações à conta

Uma linha por cada vez que outra pessoa mudou o email de segurança ou repôs a password da conta (um administrador, quem trata dos acessos no RH, ou quem enviou o convite por ligação), a Plataforma suspendeu a recuperação da password depois de demasiados códigos errados, a entrada com Face ID foi ativada num aparelho, um administrador a removeu, ou uma chave de acesso foi recusada por parecer copiada: quem foi avisado, quem mexeu, quando, o tipo de alteração e a situação do aviso por email. O aviso aparece no sino do titular até ele o ver e é enviado por email (para o endereço antigo, quando mudou o email).

id número inteiro · bigint · obrigatório: Identificador do aviso.
user_id identificador (UUID) · uuid · obrigatório: Conta da pessoa avisada (hub_users.id).
tipo texto · text · obrigatório: O que mudou: «email_mudado» (o email de segurança), «password_reposta», «recuperacao_suspensa» (a recuperação da password suspensa pela Plataforma), «passkey_ativada» (a própria pessoa ativou a entrada com Face ID num aparelho), «passkeys_removidas» (um administrador removeu as entradas com Face ID da conta) ou «passkey_copiada» (uma entrada com Face ID foi recusada por parecer copiada para outro aparelho).
actor_id identificador (UUID) · uuid: Quem fez a alteração (hub_users.id); vazio quando foi a Plataforma ou quando a conta dessa pessoa deixou de existir.
criado_em data e hora, com fuso · timestamp with time zone · obrigatório: Instante da alteração.
email_para texto · text: Endereço para onde vai o aviso por email (o antigo, no caso de mudança de email); vazio se a conta não tinha email.
email_estado texto · text · obrigatório: Situação do aviso por email: «sem_email», «por_enviar», «pedido» (entregue ao serviço de email, à espera da resposta), «enviado» ou «falhou».
email_pedido_em data e hora, com fuso · timestamp with time zone: Instante em que o aviso por email foi entregue ao serviço de email.
visto_em data e hora, com fuso · timestamp with time zone: Instante em que a pessoa viu o aviso na Plataforma; vazio enquanto não o viu.

`hub_sys_validador_aceites` Casos aceites no validador de dados

Os casos do validador de dados que alguém deu por certos assim (um fornecedor estrangeiro sem NIF português, uma loja sem email…), com o motivo, quem e quando. Um caso aceite deixa de contar até alguém o voltar a contar.

codigo texto · text · obrigatório: Código da verificação (por exemplo rh.sem_email); o catálogo é da Plataforma.
registo_id texto · text · obrigatório: Identificador do registo aceite (o fornecedor, a loja, o colaborador, a fatura…), em texto.
motivo texto · text · obrigatório: Motivo escrito por quem aceitou (de 3 a 500 caracteres).
aceite_por identificador (UUID) · uuid · obrigatório: Conta que aceitou (hub_users.id).
aceite_em data e hora, com fuso · timestamp with time zone · obrigatório: Instante em que foi aceite.

`hub_sys_ver_como` Acessos «ver como» às contas

Uma linha por cada vez que um administrador viu a Plataforma com a conta de outro utilizador, só para leitura e no máximo 30 minutos: quem viu, com que conta, o motivo, quando começou e acabou, se a pessoa já viu o aviso e se o aviso por email saiu. Faz parte do registo de auditoria.

id identificador (UUID) · uuid · obrigatório: Identificador do acesso.
admin_id identificador (UUID) · uuid · obrigatório: Administrador que viu a Plataforma com a conta de outra pessoa (hub_users.id).
alvo_id identificador (UUID) · uuid · obrigatório: Conta com que a Plataforma foi vista (hub_users.id).
motivo texto · text · obrigatório: Motivo escrito pelo administrador ao começar (de 10 a 300 caracteres).
iniciado_em data e hora, com fuso · timestamp with time zone · obrigatório: Instante em que o acesso começou.
expira_em data e hora, com fuso · timestamp with time zone · obrigatório: Instante em que o acesso acaba sozinho (30 minutos depois do início).
terminado_em data e hora, com fuso · timestamp with time zone: Instante em que o acesso acabou; vazio enquanto dura.
terminado_como texto · text: Como acabou: «terminar» (o administrador terminou-o), «tempo» (passaram os 30 minutos), «outro_ver_como» (o administrador começou outro), «saida_admin» (o administrador saiu da conta) ou «admin_perdeu_direito» (deixou de ser administrador, foi desativado ou apagado); vazio enquanto dura.
alvo_visto_em data e hora, com fuso · timestamp with time zone: Instante em que a pessoa viu o aviso deste acesso na Plataforma; vazio enquanto não o viu.
email_estado texto · text · obrigatório: Situação do aviso por email à pessoa: «sem_email» (a conta não tem email), «por_enviar», «pedido» (entregue ao serviço de email, à espera da resposta), «enviado» ou «falhou».
email_pedido_em data e hora, com fuso · timestamp with time zone: Instante em que o aviso por email foi entregue ao serviço de email.

Configurações do espaço da empresa

`config` Parâmetros da tesouraria

Uma linha por parâmetro da empresa, em pares chave/valor, definido nas configurações da tesouraria: dados da empresa, prazo de pagamento por omissão e envio de emails aos fornecedores. Nenhuma chave guarda segredos, por isso vão todas.

key texto · text · obrigatório: Nome do parâmetro: «name», «nif», «email», «phone», «address», «zip» (dados da empresa), «terms», «emailSig», «emailCc» ou «emailViaServidor».
value texto · text: Valor do parâmetro codificado em JSON: texto entre aspas, número (em «terms», dias de prazo por omissão), lista de emails («emailCc») ou verdadeiro/falso («emailViaServidor»).

`hub_den_textos` Textos do canal de denúncias

Uma linha com os textos da empresa no canal de denúncias: a confirmação de receção e a nota de privacidade.

id número inteiro · integer · obrigatório: Sempre 1.
confirmacao texto · text: O texto da confirmação de receção ao denunciante.
privacidade texto · text: A nota de privacidade do canal.
atualizado_em data e hora, com fuso · timestamp with time zone: Instante da última alteração.
atualizado_por identificador (UUID) · uuid: Conta do administrador que a fez (hub_users.id).

`hub_desp_fundos` Fundos de cofre das lojas

Um fundo de cofre por loja: o valor fixo em numerário e o responsável a quem se transfere a reposição das despesas pagas pelo cofre.

store_id identificador (UUID) · uuid · obrigatório: Loja do fundo (hub_stores.id); uma linha por loja.
valor_fixo número decimal · numeric · obrigatório: Valor fixo do fundo, em euros.
responsavel_user_id identificador (UUID) · uuid: Conta responsável pelo fundo (hub_users.id), para quem vai a transferência de reposição; vazio se não houver.
ativo verdadeiro ou falso · boolean · obrigatório: Se o fundo está em uso; um fundo desativado não recebe despesas nem se entrega.
constituido_em data (um dia) · date · obrigatório: Dia em que o fundo foi constituído.
updated_by identificador (UUID) · uuid: Conta que fez a última alteração (hub_users.id).
updated_at data e hora, com fuso · timestamp with time zone · obrigatório: Instante da última alteração.
responsavel_auto verdadeiro ou falso · boolean · obrigatório: Verdadeiro se o responsável acompanha a loja (o gerente com conta ou, na falta dele, o supervisor); falso se foi escolhido à mão.

`hub_desp_km_valores` Valores por quilómetro

Uma linha por data de início: o valor por km que a empresa paga e o limite isento, em vigor desde essa data até à seguinte.

valido_desde data (um dia) · date · obrigatório: Primeiro dia em que estes valores se aplicam; numa data vale a linha mais recente até essa data.
valor_empresa número decimal · numeric · obrigatório: Valor pago por km, em euros.
limite_isento número decimal · numeric · obrigatório: Valor por km isento de IRS e Segurança Social, em euros; o que passar é rendimento tributável.
criado_por identificador (UUID) · uuid: Conta que registou os valores (hub_users.id); vazio nos valores iniciais da Plataforma.
criado_em data e hora, com fuso · timestamp with time zone · obrigatório: Instante em que foram registados ou alterados pela última vez.

`hub_desp_lojas_locais` Locais das lojas no mapa

Uma linha por loja com o identificador do seu local no serviço de mapas, confirmado no escritório e usado como partida ou chegada das deslocações.

store_id identificador (UUID) · uuid · obrigatório: Loja (hub_stores.id); uma linha por loja.
place_id texto · text · obrigatório: Identificador do local da loja no serviço de mapas.
estado texto · text · obrigatório: «ok» ou «por_reconfirmar» (o local tem de ser confirmado outra vez — também quando a renovação automática soube que o serviço de mapas já não o conhece; entretanto a loja não serve de partida nem de chegada).
confirmado_por identificador (UUID) · uuid · obrigatório: Conta que confirmou o local (hub_users.id).
confirmado_em data e hora, com fuso · timestamp with time zone · obrigatório: Instante da confirmação.
renovado_em data e hora, com fuso · timestamp with time zone · obrigatório: Último instante em que o identificador foi confirmado no escritório ou renovado pela renovação automática, que o volta a pedir ao serviço de mapas quando tem mais de 11 meses (um identificador novo substitui o antigo).

`hub_desp_pessoas` Parâmetros de km por pessoa

Uma linha por colaborador com a forma de pagamento dos km e o local de trabalho habitual; as deslocações entre a casa e esse local não contam.

employee_id identificador (UUID) · uuid · obrigatório: Ficha do colaborador (hub_rh_employees.id); uma linha por ficha.
km_pagamento texto · text · obrigatório: Como se pagam os km: «transferencia» ou «vencimento» (com o salário).
local_habitual_store_id identificador (UUID) · uuid: Local de trabalho habitual (hub_stores.id); vazio = a loja da ficha do colaborador.
updated_by identificador (UUID) · uuid: Conta que fez a última alteração (hub_users.id).
updated_at data e hora, com fuso · timestamp with time zone · obrigatório: Instante da última alteração.

`hub_desp_rotas_config` Renovação dos locais das lojas

Uma só linha com a configuração e o estado da renovação automática dos locais das lojas no serviço de mapas (o identificador de cada local volta a pedir-se uma vez por ano): se está ligada, o último pedido e a sua resposta, o último erro e a última renovação gravada.

id número inteiro · smallint · obrigatório: Sempre 1: a tabela tem uma única linha.
funcao_url texto · text: Endereço da função que pergunta ao serviço de mapas, no alojamento da própria base de dados. É público e não contém segredos.
ativo verdadeiro ou falso · boolean · obrigatório: A renovação automática está ligada; desligada, nada é pedido.
forcar verdadeiro ou falso · boolean · obrigatório: O último pedido renova todos os locais confirmados, e não só os que têm mais de 11 meses (a prova feita ao ligar a renovação).
pedido_id número inteiro · bigint: Número do último pedido HTTP na fila de pedidos de saída da base de dados.
pedido_em data e hora, com fuso · timestamp with time zone: Instante do último pedido.
resposta_em data e hora, com fuso · timestamp with time zone: Instante em que se leu a resposta do último pedido; vazio enquanto não chega.
resposta_http número inteiro · integer: Código HTTP com que a função respondeu ao último pedido.
ultimo_erro texto · text: Último erro da renovação: tempo esgotado, falha de rede, o corpo de uma resposta sem sucesso ou as lojas cujo local não se renovou.
ultimo_erro_em data e hora, com fuso · timestamp with time zone: Instante do último erro.
ultima_renovacao_em data e hora, com fuso · timestamp with time zone: Instante em que a função gravou pela última vez o resultado de uma renovação.
atualizado_em data e hora, com fuso · timestamp with time zone · obrigatório: Instante da última alteração desta linha.

Não vão na cópia: senha_hash (dados de segurança do acesso (cláusula 17.7, alínea b))); senha_expira_em (dados de segurança do acesso (cláusula 17.7, alínea b))).

`hub_rh_autorizacoes` Tabela de autorizações por função

Uma linha por função profissional: quem aprova os pedidos de férias e ausências das pessoas dessa função e quem as avalia no desempenho. Basta um dos escolhidos; os administradores podem sempre.

funcao texto · text · obrigatório: Nome da função, igual ao de hub_rh_employees.role_function e ao da lista de funções da Plataforma.
aprova_pedidos lista de textos · _text · obrigatório: Quem aprova férias e ausências: lista com «gerente» (da loja), «supervisor» (da loja), «diretor» (conta definida nas definições de RH) e/ou «rh» (Responsável de RH). Vazia = só administradores.
avalia lista de textos · _text · obrigatório: Quem faz a avaliação de desempenho, com as mesmas opções de aprova_pedidos. Vazia = só administradores.
updated_at data e hora, com fuso · timestamp with time zone: Instante da última alteração.
updated_by identificador (UUID) · uuid: Utilizador que fez a última alteração (hub_users.id).

`hub_rh_aval_criterios` Critérios das grelhas de avaliação

Critérios de cada versão da grelha de avaliação de desempenho, com o peso de cada um na nota final.

id identificador (UUID) · uuid · obrigatório: Identificador do critério.
grelha_id identificador (UUID) · uuid · obrigatório: Versão da grelha a que o critério pertence (hub_rh_aval_grelhas.id).
nome texto · text · obrigatório: Nome do critério.
descricao texto · text: Explicação do critério para quem avalia.
peso número inteiro · integer · obrigatório: Peso na nota final, em percentagem (1 a 100); os pesos de uma grelha somam 100.
ordem número inteiro · integer · obrigatório: Posição do critério na grelha.

`hub_rh_aval_grelhas` Grelhas de avaliação

Versões da grelha de critérios das avaliações de desempenho. Mudar a grelha cria uma versão nova; só uma está ativa, e cada avaliação guarda a cópia da que usou.

id identificador (UUID) · uuid · obrigatório: Identificador da versão da grelha.
nome texto · text · obrigatório: Nome da grelha.
ativa verdadeiro ou falso · boolean · obrigatório: Se é a grelha usada nas avaliações novas (só uma de cada vez).
created_at data e hora, com fuso · timestamp with time zone: Instante em que a versão foi criada.
created_by identificador (UUID) · uuid: Conta que criou a versão (hub_users.id); vazio na grelha criada com a instalação.

`hub_rh_checklist_templates` Modelos de tarefas de integração

Uma linha por modelo de lista de tarefas para a entrada ou a saída de colaboradores; aplicar um modelo a uma ficha copia as suas tarefas para hub_rh_checklist_items.

id identificador (UUID) · uuid · obrigatório: Identificador do modelo.
name texto · text · obrigatório: Nome do modelo.
kind texto · text · obrigatório: Momento: «onboarding» (integração) ou «offboarding» (saída).
tasks JSON · jsonb · obrigatório: Lista ordenada das tarefas do modelo, cada uma com «task» (descrição) e «responsible» (quem a faz).
active verdadeiro ou falso · boolean · obrigatório: Falso quando o modelo foi removido; deixa de aparecer, mas as tarefas já copiadas ficam.

`hub_rh_config` Parâmetros de recursos humanos

Uma linha por parâmetro do módulo de RH, em chave e valor: dias de férias, períodos experimentais, majorações e limites das horas extra, período noturno, taxas usadas no custo de pessoal e outras opções da empresa.

key texto · text · obrigatório: Nome do parâmetro (por exemplo «ferias_dias_ano», «noturno_inicio_min», «tsu_empresa_pct»).
value texto · text: Valor do parâmetro, em texto: número, fração, minutos desde a meia-noite, «1»/«0» ou identificador de utilizador, conforme a chave.
description texto · text: Explicação do parâmetro.
updated_at data e hora, com fuso · timestamp with time zone: Instante da última alteração.

`hub_rh_contract_templates` Modelos de documentos

Uma linha por modelo de documento (contrato, declaração, carta) que o ecrã preenche com os dados da ficha de um colaborador; o modelo é um texto com campos ou um ficheiro .docx com campos.

id identificador (UUID) · uuid · obrigatório: Identificador do modelo.
name texto · text · obrigatório: Nome do modelo.
body texto · text · obrigatório: Texto do modelo, com campos entre chavetas duplas como «{{nome}}» ou «{{funcao}}». Vazio nos modelos do tipo «docx».
created_by identificador (UUID) · uuid: Utilizador que criou o modelo (hub_users.id).
created_at data e hora, com fuso · timestamp with time zone: Instante em que o modelo foi criado.
updated_at data e hora, com fuso · timestamp with time zone: Instante da última alteração.
kind texto · text · obrigatório: Formato: «text» (usa body) ou «docx» (usa o ficheiro de file_path).
file_path texto · text: Caminho do ficheiro .docx do modelo no armazenamento de ficheiros, só no tipo «docx»; o ficheiro vai na cópia com o índice.

`hub_rh_ponto_config` Registo de ponto — formas de marcar

Uma só linha com as formas de marcar o ponto que a empresa ligou (todas desligadas de origem) e quem as mudou por último.

id número inteiro · smallint · obrigatório: Sempre 1: a tabela tem uma só linha.
quiosque verdadeiro ou falso · boolean · obrigatório: Ligado: marca-se no tablet da loja, com o PIN.
telemovel_qr verdadeiro ou falso · boolean · obrigatório: Ligado: marca-se no telemóvel lendo o QR do tablet da loja.
telemovel_livre verdadeiro ou falso · boolean · obrigatório: Ligado: marca-se no telemóvel sem QR.
updated_at data e hora, com fuso · timestamp with time zone · obrigatório: Instante da última mudança.
updated_by identificador (UUID) · uuid: Conta que fez a última mudança (hub_users.id).

`hub_rh_ponto_quiosques` Registo de ponto — tablets das lojas

Uma linha por tablet ligado ao ponto numa loja: o nome, quando foi ligado, o último contacto e, se foi desligado, quando e por quem. A chave do tablet, o código de ligação, o segredo do QR e as contagens de tentativas não vão na cópia.

id identificador (UUID) · uuid · obrigatório: Identificador do tablet.
store_id identificador (UUID) · uuid · obrigatório: Loja do tablet (hub_stores.id).
nome texto · text · obrigatório: Nome dado ao tablet (por exemplo «Balcão»).
codigo_expira data e hora, com fuso · timestamp with time zone: Até quando vale o código de ligação por usar; vazio depois de ligado.
criado_por identificador (UUID) · uuid · obrigatório: Conta que criou o tablet (hub_users.id).
criado_em data e hora, com fuso · timestamp with time zone · obrigatório: Instante da criação.
ligado_em data e hora, com fuso · timestamp with time zone: Instante em que o tablet se ligou com o código.
ultimo_contacto data e hora, com fuso · timestamp with time zone: Último instante em que o tablet falou com o servidor.
revogado_em data e hora, com fuso · timestamp with time zone: Instante em que foi desligado; vazio = ligado.
revogado_por identificador (UUID) · uuid: Conta que o desligou (hub_users.id).

Não vão na cópia: token_hash (dados de segurança do acesso (cláusula 17.7, alínea b))); codigo_hash (dados de segurança do acesso (cláusula 17.7, alínea b))); segredo (dados de segurança do acesso (cláusula 17.7, alínea b))); erros (dados de segurança do acesso (cláusula 17.7, alínea b))); erros_desde (dados de segurança do acesso (cláusula 17.7, alínea b))).

`hub_settings` Definições gerais

Uma linha por parâmetro geral do Espaço do Cliente: categorias e campos extra dos pedidos das lojas, antecedência dos alertas, início das avaliações, mapa de importação de vendas, opções da leitura automática de documentos. Nenhum parâmetro da Plataforma guarda chaves de serviços externos (a da leitura automática, que chegou a viver aqui, é recusada e foi apagada), por isso todas as linhas vão na cópia.

key texto · text · obrigatório: Nome do parâmetro, por exemplo «tickets_categorias», «tickets_campos_extra», «alertas_horizonte_dias», «avaliacoes_inicio», «vendas_import_map», «ocr_via_proxy», «ocr_escalar_modelo».
value texto · text: Valor em texto: listas e mapas em JSON, interruptores como «1»/«0», dias como número inteiro, datas como AAAA-MM-DD.
updated_at data e hora, com fuso · timestamp with time zone: Instante da última alteração.
updated_by identificador (UUID) · uuid: Conta que fez a última alteração (hub_users.id); vazio nos valores iniciais da Plataforma.

`hub_vd_pos_config` Configuração da ligação ao POS

Uma só linha com os parâmetros da leitura automática do sistema de faturação (POS): se está ligada, a reconstrução do histórico e a releitura diária.

id número inteiro · integer · obrigatório: Sempre 1: a tabela tem uma única linha.
ativo verdadeiro ou falso · boolean · obrigatório: A leitura automática está ligada; desligada, nada é lido.
funcao_url texto · text: Endereço da função de leitura, no alojamento da própria base de dados. É público e não contém segredos.
reconciliado_em data (um dia) · date: Último dia (hora de Lisboa) em que se pôs na fila a releitura de madrugada do dia de anteontem de cada loja.
atualizado_em data e hora, com fuso · timestamp with time zone · obrigatório: Instante da última alteração desta configuração.
hist_ativo verdadeiro ou falso · boolean · obrigatório: A reconstrução do histórico (leitura dos dias anteriores à ligação) está ligada.
hist_paginas número inteiro · integer · obrigatório: Máximo de páginas de documentos (até 250 cada) que a reconstrução do histórico pede ao POS em cada execução, de 0 a 200.
hist_pausa_ate data e hora, com fuso · timestamp with time zone: Instante até ao qual a reconstrução do histórico fica em pausa, depois de o POS pedir para abrandar (uma hora).

Listas de referência

`hub_ref_lists` Listas de referência da plataforma

Uma linha por valor de uma lista fixa da plataforma que os registos usam (tipos de contrato, funções, métodos de pagamento, categorias de despesa…). As listas não se editam nos ecrãs; um valor fora da lista grava-se como texto livre no próprio registo.

id identificador (UUID) · uuid · obrigatório: Identificador do valor.
list_key texto · text · obrigatório: Lista: «contract_type», «function», «categoria_profissional», «motivo_saida», «tipo_documento», «tipo_vencimento», «categoria_documento», «tipo_baixa», «modalidade_formacao», «metodo_pagamento» ou «categoria_despesa».
value texto · text · obrigatório: O valor, tal como se grava nos registos; nas categorias de despesa é uma chave (por exemplo «comb_gasoleo») cujo texto vem da interface.
sort_order número inteiro · integer: Posição do valor na lista.
active verdadeiro ou falso · boolean: Verdadeiro enquanto o valor é proposto nos ecrãs.
created_at data e hora, com fuso · timestamp with time zone: Instante em que o valor foi criado.
nivel texto · text: Nas funções, o nível hierárquico («loja», «chefia_turno», «subgerente», «gerente», «supervisor», «escritorio», «direcao»); nas categorias profissionais, um nível salarial (I a XI) guardado sem uso; vazio nas outras.

`hub_rh_cct_tabela` Mínimos salariais por nível

Uma linha por ano e nível: o vencimento mínimo mensal de uma convenção coletiva de trabalho, semeado pela Plataforma. O ecrã deixou de o usar a 23/09/2026; a tabela ficou na base.

ano número inteiro · integer · obrigatório: Ano civil a que o mínimo se aplica.
nivel texto · text · obrigatório: Nível salarial da convenção, de «I» a «XI».
minimo número decimal · numeric · obrigatório: Vencimento mínimo mensal do nível, em euros.
fonte texto · text: Publicação oficial de onde vem o valor.

`hub_sys_hist_acoes_antigas` Histórico: tradução das ações antigas

Uma linha por ação em código do registo de auditoria anterior ao histórico novo, com a forma como se lê no histórico: o verbo, o módulo, o tipo de ficha e onde estão os valores. O catálogo é da Plataforma.

action texto · text · obrigatório: Ação em código, como está no registo de auditoria (hub_audit_log.action).
verbo texto · text · obrigatório: Verbo com que se lê no histórico.
modulo texto · text · obrigatório: Módulo da ação.
ficha_tipo texto · text · obrigatório: Tipo de ficha a que a ação se aplica.
mae_expr texto · text: Onde se encontra, nos pormenores da ação, a ficha principal; vazio quando é a própria ficha.
campos_map JSON · jsonb · obrigatório: Como se tiram, dos pormenores da ação, os campos que mudaram (em JSON).

`hub_sys_hist_campos` Histórico: campos de cada ficha

Uma linha por campo de uma ficha que o histórico mostra: o nome no ecrã, como se escreve o valor e se é um dado sensível (que se tapa ou só se diz «alterado»). O catálogo é da Plataforma.

tipo texto · text · obrigatório: Tipo de ficha (hub_sys_hist_tipos.tipo).
coluna texto · text · obrigatório: Campo da ficha.
rotulo_pt texto · text · obrigatório: Nome do campo em português.
rotulo_en texto · text · obrigatório: Nome do campo em inglês.
formato texto · text · obrigatório: Como se escreve o valor (texto, dinheiro, data, sim/não, referência a outra ficha…).
classe texto · text · obrigatório: Que regra de proteção se aplica ao valor: comum, dados pessoais, salário, IBAN ou só «alterado».

`hub_sys_hist_sem_gatilho` Histórico: tabelas sem registo automático

Uma linha por tabela cujas alterações não ficam registadas sozinhas no histórico, com a razão (por exemplo, são registadas à mão pela ação que as faz, ou não são fichas de ninguém). O catálogo é da Plataforma.

tabela texto · text · obrigatório: Nome da tabela.
motivo texto · text · obrigatório: Porque não tem registo automático.

`hub_sys_hist_tipos` Histórico: tipos de ficha

Uma linha por tipo de ficha que tem histórico (colaborador, fornecedor, fatura, mapa de despesas…): onde vive, como se chama no ecrã, a que ficha principal pertence e quem o pode ver. O catálogo é da Plataforma.

tipo texto · text · obrigatório: Código do tipo de ficha.
modulo texto · text · obrigatório: Módulo a que pertence.
tabela texto · text · obrigatório: Tabela onde vivem as fichas deste tipo.
coluna_id texto · text · obrigatório: Campo dessa tabela que identifica a ficha.
coluna_nome texto · text: Campo dessa tabela com o nome que o histórico mostra; vazio quando o nome se compõe de outra forma.
mae_tipo texto · text · obrigatório: Tipo da ficha principal a que esta pertence (o próprio tipo, quando é principal).
mae_coluna texto · text · obrigatório: Campo que liga a ficha à sua ficha principal.
rotulo_pt texto · text · obrigatório: Nome do tipo em português.
rotulo_en texto · text · obrigatório: Nome do tipo em inglês.
categoria texto · text · obrigatório: Grupo a que o tipo pertence no filtro do histórico.
porta texto · text · obrigatório: Permissão de que depende ver o histórico deste tipo.
com_gatilho verdadeiro ou falso · boolean · obrigatório: Se as alterações a estas fichas já ficam registadas sozinhas no histórico.
corte data e hora, com fuso · timestamp with time zone: Instante a partir do qual o histórico deste tipo se lê só do registo novo; antes dele lê-se também do histórico antigo. Vazio enquanto não há corte.

Outros dados

`hub_alertas_fila` Alertas enviados por email

Uma linha por alerta operacional gerado pela Plataforma para o endereço de alertas da empresa (contas bloqueadas, vaga de entradas falhadas, erros de tarefas automáticas, consumo invulgar da leitura automática de documentos). Nada se apaga: a linha é o registo de que o aviso saiu.

id número inteiro · bigint · obrigatório: Número sequencial do alerta.
criado_em data e hora, com fuso · timestamp with time zone · obrigatório: Instante em que o alerta foi gerado.
tipo texto · text · obrigatório: Tipo de alerta: «contas_bloqueadas», «logins_falhados», «erros_cron» (tarefas automáticas com erros) ou «ocr_consumo» (leituras automáticas de documentos acima do normal).
gravidade texto · text · obrigatório: «aviso» ou «grave».
assunto texto · text · obrigatório: Assunto do email.
corpo texto · text · obrigatório: Texto do email, com o que aconteceu e onde se resolve.
estado texto · text · obrigatório: «por_enviar», «enviado» (o pedido de envio saiu para o serviço de email; a resposta não é conferida) ou «sem_chave» (o envio de email ainda não está configurado; o alerta fica à espera e sai depois). O valor «erro» está previsto, mas nunca é gravado.
enviado_em data e hora, com fuso · timestamp with time zone: Instante em que o pedido de envio foi feito ao serviço de email (a entrega não é confirmada); vazio enquanto não sai.
resposta texto · text: Resultado do envio: o número do pedido de envio, ou a explicação de porque o alerta ficou à espera.
dia data (um dia) · date · obrigatório: Dia do alerta; há no máximo um alerta de cada tipo por dia.

`hub_cron_erros` Erros das tarefas automáticas

Uma linha por falha de uma tarefa automática (automatismos dos pedidos das lojas, desativação das contas de quem saiu, leitura das vendas do sistema de faturação, sincronização da licença). Os administradores veem-nas e geram o alerta diário.

id identificador (UUID) · uuid · obrigatório: Identificador do erro.
job texto · text · obrigatório: Tarefa que falhou: «tk-auto-reconciliar» (pedidos das lojas), «hub-contas-saidas» (contas de quem saiu), «vendas_pos», «vendas_pos_dias» (vendas do POS), «despesas_locais» (renovação dos locais das lojas) ou «licenca».
erro texto · text · obrigatório: Mensagem do erro; nas vendas do POS, as lojas e os dias afetados.
detalhe texto · text: Contexto adicional: a parte da tarefa que falhou ou o último erro técnico registado.
created_at data e hora, com fuso · timestamp with time zone · obrigatório: Instante do erro.

`hub_sys_ajuda_conversas` Conversas com o assistente de ajuda

Uma linha por conversa de um Utilizador com o assistente de ajuda (que responde a dúvidas sobre como usar a Plataforma, a partir dos manuais). Só o próprio Utilizador a vê; apaga-se sozinha 30 dias depois da última mensagem, ou antes, se ele a apagar.

id identificador (UUID) · uuid · obrigatório: Identificador da conversa.
user_id identificador (UUID) · uuid · obrigatório: Conta de quem conversa (hub_users.id).
titulo texto · text · obrigatório: O começo da primeira pergunta (até 80 caracteres), para a lista das recentes.
criada_em data e hora, com fuso · timestamp with time zone · obrigatório: Instante da primeira pergunta.
atualizada_em data e hora, com fuso · timestamp with time zone · obrigatório: Instante da última mensagem; os 30 dias contam daqui.

`hub_sys_ajuda_mensagens` Mensagens das conversas com o assistente de ajuda

Uma linha por pergunta de um Utilizador ao assistente de ajuda e por cada resposta, com o módulo e o ecrã de onde se perguntou e, nas respostas, as secções do manual citadas e o consumo. Apaga-se com a conversa.

id número inteiro · bigint · obrigatório: Número sequencial da mensagem.
conversa_id identificador (UUID) · uuid · obrigatório: Conversa a que pertence (hub_sys_ajuda_conversas.id).
user_id identificador (UUID) · uuid · obrigatório: Conta de quem perguntou (hub_users.id); conta para os limites diários.
papel texto · text · obrigatório: «pessoa» (a pergunta) ou «assistente» (a resposta).
texto texto · text · obrigatório: O texto da pergunta ou da resposta.
pergunta_id número inteiro · bigint: Na resposta, a pergunta a que responde; vazio nas perguntas.
fontes JSON · jsonb · obrigatório: Nas respostas, as secções do manual citadas (lista em JSON).
modulo texto · text: Módulo onde a pessoa estava ao perguntar (por exemplo «rh»).
ecra texto · text: Ecrã onde a pessoa estava ao perguntar.
criada_em data e hora, com fuso · timestamp with time zone · obrigatório: Instante da mensagem.
modelo texto · text: Nas respostas, o modelo de inteligência artificial que respondeu.
uso JSON · jsonb: Nas respostas, os tokens consumidos (JSON), para o custo.
stop_reason texto · text: Nas respostas, como acabou: o motivo do modelo, ou «filtrada» se a rede de segurança a trocou pela frase fixa.
voto número inteiro · smallint: Nas respostas, o voto do Utilizador: 1 se a resposta ajudou, -1 se não ajudou; vazio se não votou. Só o próprio Utilizador o põe; o administrador só vê contagens.
sabe verdadeiro ou falso · boolean: Nas respostas, o que o modelo disse: verdadeiro se os manuais respondiam à pergunta, falso se não (um «não sei» honesto). Vazio nas respostas anteriores a esta coluna.
sugerida_em data e hora, com fuso · timestamp with time zone: Nas respostas, o instante em que o Utilizador decidiu enviar esta pergunta e esta resposta ao ZarvoHUB para melhorar a ajuda (sem o nome, o email, a conta nem a empresa; só com o gesto dele, e uma só vez). Vazio se nunca a enviou.

`hub_sys_resumos` Resultados calculados guardados

Resultados que a Plataforma calcula a partir de outros dados e guarda por pouco tempo, para não os voltar a calcular em cada abertura: o resumo do validador de dados de cada conta, os avisos e os quadros do mês dos fechos financeiros, o estado dos dados das vendas. Cada um volta a calcular-se sozinho ao fim de minutos ou quando os dados de onde vem mudam — para isso, cada transação que muda esses dados deixa aqui uma linha só com o seu número interno, que se apaga sozinha. Refazem-se a partir dos outros dados.

chave texto · text · obrigatório: O que é: «validador:» e a conta, «fch_alertas», «fch_num:» ou «fch_cont:» e o mês, «vd_estado», ou «escrita:», o grupo e o número interno da transação que mudou os dados.
calculado_em data e hora, com fuso · timestamp with time zone · obrigatório: Instante em que foi calculado (ou registada a escrita).
assinatura texto · text: No resumo do validador, um resumo das verificações e lojas que a conta via quando se calculou (outra assinatura obriga a calcular de novo).
instantaneo texto · text: O instantâneo interno da base em que se calculou: diz que escritas o cálculo já contava.
dados JSON · jsonb · obrigatório: O resultado, em JSON (vazio nas linhas das escritas).

Canal de denúncias (sai pela caixa do canal)

`hub_den_acessos` Acessos às denúncias

Uma linha por cada vez que uma pessoa designada abriu uma denúncia, escreveu nela, mudou o estado, marcou um processo, deu acesso a outra pessoa ou a descarregou. Todas as pessoas que leem a denúncia veem este registo. Apaga-se com a denúncia.

id número inteiro · bigint · obrigatório: Número sequencial do acesso.
caso_id identificador (UUID) · uuid · obrigatório: Denúncia (hub_den_casos.id).
user_id identificador (UUID) · uuid: Conta da pessoa designada (hub_users.id).
acao texto · text · obrigatório: O que fez: «abrir», «estado», «mensagem», «reembrulhar» (deu acesso a outra pessoa), «processo», «anexo» (abriu um anexo), «apagar_pedido», «apagar_confirmado», «apagar_recusado», «apagar_cancelado», «relatorio» (contou a denúncia no relatório anual) ou «descarregar» (descarregou-a, decifrada, na caixa).
em data e hora, com fuso · timestamp with time zone · obrigatório: Instante do acesso.
anexo_id identificador (UUID) · uuid: O anexo aberto (hub_den_anexos.id), quando o acesso foi abrir um anexo.

`hub_den_anexos` Anexos das denúncias

Uma linha por ficheiro junto a uma denúncia, a uma mensagem ou a uma nota interna. O ficheiro é cifrado no dispositivo de quem o junta (as fotografias saem sem os metadados) e guarda-se num arquivo privado; a Plataforma não o consegue ler. Apaga-se com a denúncia.

id identificador (UUID) · uuid · obrigatório: Identificador do anexo, gerado no dispositivo de quem o juntou.
caso_id identificador (UUID) · uuid · obrigatório: Denúncia (hub_den_casos.id).
mensagem_id identificador (UUID) · uuid: Mensagem ou nota interna a que pertence (hub_den_mensagens.id); vazio quando é um anexo da própria denúncia.
interna verdadeiro ou falso · boolean · obrigatório: Se pertence a uma nota interna (só as pessoas designadas o abrem).
de texto · text · obrigatório: «denunciante» ou o identificador da conta da pessoa designada que o juntou.
tamanho número inteiro · integer · obrigatório: Tamanho do ficheiro cifrado, em bytes.
nome_cifrado texto · text · obrigatório: O nome, o tipo e o tamanho do ficheiro, cifrados.
nome_nonce texto · text · obrigatório: Valor de uso único dessa cifra.
criado_em data e hora, com fuso · timestamp with time zone · obrigatório: Instante em que o anexo foi reservado.
carregado_em data e hora, com fuso · timestamp with time zone: Instante em que o ficheiro acabou de chegar ao arquivo.
apagado_em data e hora, com fuso · timestamp with time zone: Instante em que o anexo foi apagado (art. 19.º da Lei 93/2021).
apagado_por identificador (UUID) · uuid: Conta de quem confirmou o apagamento (hub_users.id).
tirar_por identificador (UUID) · uuid: Conta de quem aplicou o apagamento e tira o ficheiro do arquivo (hub_users.id).
motivo_cifrado texto · text: O motivo do apagamento, cifrado com a chave das notas internas.
motivo_nonce texto · text: Valor de uso único dessa cifra.

`hub_den_apagamentos` Pedidos para apagar parte de uma denúncia

Uma linha por pedido para apagar uma parte de uma denúncia (o texto, uma mensagem ou um anexo), à espera da confirmação de uma segunda pessoa designada que leia a denúncia. A versão nova vai cifrada e sai do pedido quando se aplica: o pedido não guarda cópia do que se apagou. Apaga-se com a denúncia.

id identificador (UUID) · uuid · obrigatório: Identificador do pedido.
caso_id identificador (UUID) · uuid · obrigatório: Denúncia (hub_den_casos.id).
alvo texto · text · obrigatório: O que se apaga: «conteudo» (o texto da denúncia), «mensagem» ou «anexo».
alvo_id identificador (UUID) · uuid: A mensagem ou o anexo (hub_den_mensagens.id ou hub_den_anexos.id); vazio no texto da denúncia.
novo_cifrado texto · text: A versão nova do texto, já cifrada; vazio num anexo (sai inteiro) e depois de o pedido se decidir.
novo_nonce texto · text: Valor de uso único dessa cifra.
motivo_cifrado texto · text · obrigatório: O motivo do apagamento, cifrado com a chave das notas internas.
motivo_nonce texto · text · obrigatório: Valor de uso único dessa cifra.
pedido_por identificador (UUID) · uuid: Conta de quem pediu (hub_users.id).
pedido_em data e hora, com fuso · timestamp with time zone · obrigatório: Instante do pedido.
estado texto · text · obrigatório: «pendente», «confirmado», «recusado» ou «cancelado».
decidido_por identificador (UUID) · uuid: Conta de quem decidiu (hub_users.id); nunca quem pediu.
decidido_em data e hora, com fuso · timestamp with time zone: Instante da decisão.

`hub_den_avisos` Avisos do canal de denúncias

Uma linha por aviso a uma pessoa designada (no sino e por email): uma denúncia nova, uma mensagem do denunciante, um prazo a chegar, um pedido de designação. Nunca leva o conteúdo da denúncia. Apaga-se com a denúncia, ou um ano depois de visto.

id número inteiro · bigint · obrigatório: Número sequencial do aviso.
user_id identificador (UUID) · uuid · obrigatório: Conta de quem é avisado (hub_users.id).
tipo texto · text · obrigatório: O motivo: «nova», «mensagem», «por_abrir», «prazo_resposta», «resposta_atrasada», «prazo_resultado», «apagar», «designacao_pedida», «designado», «acesso_dado», «chaves_novas» ou «apagamento_pedido».
caso_id identificador (UUID) · uuid: Denúncia a que se refere (hub_den_casos.id), quando é de uma.
dia data (um dia) · date · obrigatório: Dia do aviso (um por pessoa, motivo, denúncia e dia).
quando data (um dia) · date: A data do prazo de que o aviso fala, quando fala de um.
criado_em data e hora, com fuso · timestamp with time zone · obrigatório: Instante em que o aviso foi criado.
visto_em data e hora, com fuso · timestamp with time zone: Instante em que a pessoa o viu no sino.
email_para texto · text: Endereço para onde foi o email do aviso.
email_estado texto · text · obrigatório: Estado do email: «por_enviar», «pedido», «enviado», «falhou» ou «sem_email».
email_pedido_id número inteiro · bigint: Identificador do pedido de envio do email.
email_pedido_em data e hora, com fuso · timestamp with time zone: Instante em que o envio do email foi pedido.
email_erro texto · text: A razão, quando o email falhou.

`hub_den_casos` Denúncias recebidas

Uma linha por denúncia recebida pelo canal de denúncias. O conteúdo vem cifrado do dispositivo do denunciante e só as pessoas designadas que ele deixou marcadas o conseguem ler, com a sua frase-passe; a Plataforma não o consegue ler. A denúncia não guarda a origem nem o dispositivo de quem a fez. Apaga-se 5 anos depois da conclusão, salvo com um processo pendente marcado.

id identificador (UUID) · uuid · obrigatório: Identificador da denúncia, gerado no dispositivo do denunciante.
numero texto · text · obrigatório: Número da denúncia (ano e número de ordem), para as pessoas designadas falarem dela.
versao número inteiro · integer · obrigatório: Versão do formato da cifra.
conteudo_cifrado texto · text · obrigatório: O conteúdo da denúncia (o texto, a área, o local, a identificação, se a houver), cifrado.
nonce texto · text · obrigatório: Valor de uso único da cifra do conteúdo.
emb_denunciante texto · text · obrigatório: A chave da denúncia cifrada com a chave que sai do código de acompanhamento.
emb_denunciante_nonce texto · text · obrigatório: Valor de uso único dessa cifra.
recebida_em data e hora, com fuso · timestamp with time zone · obrigatório: Instante da receção.
estado texto · text · obrigatório: «recebida», «em_analise» ou «concluida».
em_analise_em data e hora, com fuso · timestamp with time zone: Instante em que passou a em análise.
resposta_final_em data e hora, com fuso · timestamp with time zone: Instante da resposta final ao denunciante (as medidas e a fundamentação).
concluida_em data e hora, com fuso · timestamp with time zone: Instante da conclusão.
resultado_pedido_em data e hora, com fuso · timestamp with time zone: Instante em que o denunciante pediu o resultado da análise.
resultado_dado_em data e hora, com fuso · timestamp with time zone: Instante em que esse resultado lhe foi dado.
processo_pendente verdadeiro ou falso · boolean · obrigatório: Se há um processo pendente que impede o apagamento.
apagar_em data e hora, com fuso · timestamp with time zone · obrigatório: Quando a denúncia se apaga (5 anos depois da conclusão; 5 anos e 3 meses depois da receção, se nunca concluiu).
conteudo_editado_em data e hora, com fuso · timestamp with time zone: Instante em que parte do texto da denúncia foi apagada.
conteudo_editado_por identificador (UUID) · uuid: Conta de quem confirmou esse apagamento (hub_users.id).
conteudo_motivo_cifrado texto · text: O motivo, cifrado com a chave das notas internas.
conteudo_motivo_nonce texto · text: Valor de uso único dessa cifra.
processo_motivo_cifrado texto · text: Qual é o processo pendente, cifrado no dispositivo com a chave das notas internas.
processo_motivo_nonce texto · text: Valor de uso único dessa cifra.

Não vão na cópia: codigo_hash (dados de segurança do acesso (cláusula 17.7, alínea b))).

`hub_den_embrulhos` Chaves das denúncias por pessoa

Uma linha por denúncia, pessoa designada e chave (a da denúncia e a das notas internas): a chave cifrada para a pessoa, que só ela abre com a sua frase-passe. Quem o denunciante tirou da lista não tem linha. Sai quando a pessoa deixa de ser designada.

caso_id identificador (UUID) · uuid · obrigatório: Denúncia (hub_den_casos.id).
user_id identificador (UUID) · uuid · obrigatório: Conta da pessoa designada (hub_users.id).
o_que texto · text · obrigatório: «caso» (a chave do conteúdo e da conversa) ou «notas» (a das notas internas).
chave_efemera texto · text · obrigatório: A chave pública de uso único com que esta chave foi cifrada.
embrulho texto · text · obrigatório: A chave, cifrada para a pessoa.
nonce texto · text · obrigatório: Valor de uso único dessa cifra.
criado_em data e hora, com fuso · timestamp with time zone · obrigatório: Instante em que a pessoa recebeu o acesso.
dado_por identificador (UUID) · uuid: Conta de quem lhe deu o acesso (hub_users.id); vazio quando veio do próprio denunciante.

`hub_den_mensagens` Conversa e notas das denúncias

Uma linha por mensagem entre o denunciante e as pessoas designadas, e por nota interna (que o denunciante não vê). Tudo cifrado. Apaga-se com a denúncia.

id identificador (UUID) · uuid · obrigatório: Identificador da mensagem, gerado no dispositivo de quem a escreveu.
caso_id identificador (UUID) · uuid · obrigatório: Denúncia (hub_den_casos.id).
de texto · text · obrigatório: «denunciante» ou o identificador da conta da pessoa designada que escreveu.
interna verdadeiro ou falso · boolean · obrigatório: Se é uma nota interna (só as pessoas designadas a leem).
final verdadeiro ou falso · boolean · obrigatório: Se é a resposta final ao denunciante, ou o resultado que ele pediu.
cifrado texto · text · obrigatório: O texto, cifrado.
nonce texto · text · obrigatório: Valor de uso único da cifra.
criada_em data e hora, com fuso · timestamp with time zone · obrigatório: Instante da mensagem.
editada_em data e hora, com fuso · timestamp with time zone: Instante em que parte da mensagem foi apagada.
editada_por identificador (UUID) · uuid: Conta de quem confirmou esse apagamento (hub_users.id).
motivo_cifrado texto · text: O motivo, cifrado com a chave das notas internas.
motivo_nonce texto · text: Valor de uso único dessa cifra.

O que não se transfere

Estas tabelas são do funcionamento interno da plataforma ou de terceiros (termos, cláusula 17.7), e não vão na cópia:

hub_den_tentativas Tentativas na página pública do canal de denúncias: Uma linha por envio, abertura ou mensagem na página pública do canal, com o resumo criptográfico do endereço de origem, para travar abusos. Apaga-se ao fim de uma hora e não se liga a nenhuma denúncia. São dados de segurança do acesso; não vão na cópia. (dados de segurança do acesso (cláusula 17.7, alínea b)))
hub_desp_distancias Distâncias calculadas temporárias: Distâncias de percursos calculadas pelo serviço de mapas para uma conta, válidas 24 horas para gravar uma deslocação e apagadas ao fim de 2 dias; não vão na cópia (os km aceites de cada deslocação estão em hub_desp_km). (conteúdo do serviço de mapas, guardado temporariamente (cláusula 17.7, alínea e)))
hub_licenca Licença da Plataforma: Uma só linha com a última licença confirmada pelo serviço de licenças do ZarvoHUB (módulos em vigor), o estado dessa sincronização e o segredo da empresa junto desse serviço. São dados de licença da Plataforma e um segredo do ZarvoHUB (exclusão c); não vão na cópia. (dados de licença, de versão ou registos técnicos que não resultam do uso da empresa (cláusula 17.7, alínea d)))
hub_login_tentativas Tentativas de entrada por origem: Uma linha por tentativa de entrada ou de recuperação da palavra-passe, com o resumo criptográfico do endereço de origem, para travar ataques. São dados de segurança do acesso; não vão na cópia. (dados de segurança do acesso (cláusula 17.7, alínea b)))
hub_mfa_codes Códigos de entrada por email: Uma linha por código de confirmação enviado por email ao entrar, guardado só em resumo criptográfico, com as tentativas e a validade. São dados de segurança do acesso; não vão na cópia. (dados de segurança do acesso (cláusula 17.7, alínea b)))
hub_password_reset_codes Códigos de recuperação da palavra-passe: Uma linha por código de recuperação da palavra-passe enviado por email, guardado só em resumo criptográfico, com as tentativas e a validade. São dados de segurança do acesso; não vão na cópia. (dados de segurança do acesso (cláusula 17.7, alínea b)))
hub_password_reset_pedidos Pedidos de recuperação por origem: Uma linha por pedido de recuperação da palavra-passe, só com o resumo criptográfico do endereço de origem, para limitar pedidos repetidos. São dados de segurança do acesso; não vão na cópia. (dados de segurança do acesso (cláusula 17.7, alínea b)))
hub_rh_ponto_pins Registo de ponto — PIN: Uma linha por colaborador com PIN para marcar no tablet: o resumo (hash) do PIN, quem o definiu, as tentativas falhadas e o bloqueio. São dados de segurança do acesso; não vão na cópia. (dados de segurança do acesso (cláusula 17.7, alínea b)))
hub_schema_version Versões do esquema aplicadas: Uma linha por atualização da estrutura da base de dados aplicada, com o instante. É a versão da Plataforma, não um dado do cliente; não vai na cópia. (dados de licença, de versão ou registos técnicos que não resultam do uso da empresa (cláusula 17.7, alínea d)))
hub_sessions Sessões abertas: Uma linha por sessão iniciada: o resumo criptográfico do identificador da sessão, a conta, a última atividade e a validade e, numa sessão «ver como», o acesso a que pertence. São dados de segurança do acesso; não vão na cópia. (dados de segurança do acesso (cláusula 17.7, alínea b)))
hub_sys_exportacao_usos Contagem dos pedidos de exportação: Uma linha por chave de exportação (ou por administrador, na exportação pelo browser) e por dia, com o número de pedidos feitos, para os limites de pedidos (10 por segundo e 20 000 por dia). Não guarda o conteúdo dos pedidos e apaga-se ao fim de 30 dias. São contagens de segurança do acesso; não vão na cópia — o registo de auditoria guarda o primeiro uso de cada dia. (dados de segurança do acesso (cláusula 17.7, alínea b)))
hub_sys_passkey_desafios Desafios da entrada com Face ID: Uma linha por desafio de uso único (válido 2 minutos) que o servidor dá ao aparelho para assinar, ao ativar ou ao entrar com Face ID, com o resumo criptográfico do endereço de origem. Apagam-se ao ser usados ou ao expirar. São dados de segurança do acesso; não vão na cópia. (dados de segurança do acesso (cláusula 17.7, alínea b)))
hub_sys_passkeys Entradas com Face ID (chaves de acesso): Uma linha por aparelho em que uma pessoa ativou a entrada com Face ID (ou a impressão digital, ou o código do aparelho): o identificador da chave e a chave PÚBLICA que o aparelho criou, o algoritmo, o contador, o nome do aparelho, se a chave fica sincronizada na conta da pessoa no fabricante do aparelho, quando foi ativada, usada e, se for o caso, recusada por parecer copiada, e o resumo criptográfico do endereço de onde foi ativada. Nenhum dado biométrico: o reconhecimento é feito no próprio aparelho. São dados de segurança do acesso, presos aos endereços do ZarvoHUB; não vão na cópia. (dados de segurança do acesso (cláusula 17.7, alínea b)))

Interface de exportação

Além da cópia integral pedida por email, os dados saem por uma interface de programação, só de leitura, gratuita e igual para a sua empresa e para o prestador para onde muda (Regulamento dos Dados, artigo 30.º, n.º 2). Dá os mesmos dados que a cópia integral, no mesmo formato, sem o ficheiro SQL: este dicionário, cada tabela em CSV e os ficheiros — salvo as conversas com o assistente de ajuda, que nem um administrador da empresa lê na plataforma e por isso só vêm na cópia integral, e o canal de denúncias, que sai pela caixa do canal.

O que só vem na cópia integral: hub_den_designacoes, hub_den_responsaveis, hub_den_textos, hub_sys_ajuda_conversas, hub_sys_ajuda_mensagens. O que sai pela caixa do canal de denúncias, decifrado e no formato da descarga: hub_den_acessos, hub_den_anexos, hub_den_apagamentos, hub_den_casos, hub_den_mensagens, e os anexos das denúncias (hub_den_embrulhos e hub_den_avisos não saem). O GET /estrutura lista umas e outras em «as tabelas que não se transferem» — aqui, as que não vêm por esta interface —, com a razão.

A chave. Um administrador da empresa cria-a na plataforma (Administração › Exportação), com um nome e uma validade de 1 a 7 dias, e pode revogá-la a qualquer momento. A chave mostra-se uma vez, com o endereço da interface da empresa e a região. Deixa de servir se quem a criou deixar de ser administrador. Cada pedido leva-a no cabeçalho Authorization: Bearer <chave>. Usa-se num servidor ou no terminal: um pedido feito a partir de um browser é recusado. A criação, a revogação e o primeiro uso de cada dia ficam no registo de auditoria da empresa.

Na Administração há também o Exportar tudo: o mesmo que a interface dá, descarregado no browser num ZIP, por um administrador.

Os pedidos

Pedido	O que devolve
GET /estrutura	Este dicionário em JSON: as tabelas que se transferem; de cada campo, o tipo, o significado e se é obrigatório; a chave primária e as linhas aproximadas de cada tabela; os formatos; e as tabelas que não se transferem.
GET /tabelas/<tabela>	Uma página da tabela, pela ordem da chave primária, em CSV (com formato=json, em JSON). O parâmetro lote vai de 1 a 5 000 linhas (1 000 por omissão). O cabeçalho X-Proximo traz o cursor da página seguinte, que se passa em depois; vazio, era a última. Cada página tem até cerca de 4 MB: com campos grandes, vêm menos linhas do que o lote.
GET /ficheiros	O índice dos ficheiros guardados (armazenamento, caminho, tamanho, tipo e data de criação), em páginas da mesma maneira.
GET /ficheiros/<armazenamento>/<caminho>	Redireciona (302) para um endereço do ficheiro válido durante 5 minutos; com formato=json, devolve esse endereço.

O CSV é o da cópia integral: UTF-8, a primeira linha com os nomes dos campos (em cada página), cada valor entre aspas com as aspas dobradas, um valor em falta como campo vazio sem aspas, e os valores no formato de texto do PostgreSQL. Um ficheiro liga-se ao seu registo pelo campo que guarda o caminho, indicado na descrição do campo.

Os limites: 10 pedidos por segundo e 20 000 por dia, por chave. Acima disso, a resposta é 429, com o cabeçalho Retry-After (os segundos a esperar). Os outros erros: 401 (sem chave, ou uma chave inválida, expirada ou revogada), 403 (a chave usada num browser), 404 (uma tabela que não se transfere ou um endereço desconhecido) e 400 (um lote ou um cursor inválidos). Cada erro vem em JSON, com a frase e uma referência estável: {"ok": false, "erro": "…", "ref": "…"}.

Sem um instantâneo: cada página é lida no momento do pedido. Se a empresa continuar a trabalhar durante a exportação, o que mudar pode vir ou não. Para uma cópia sem escritas a meio, peça a cópia integral.

Um exemplo

curl -H "Authorization: Bearer $CHAVE" "<endereço>/estrutura?forceFunctionRegion=<região>"
curl -H "Authorization: Bearer $CHAVE" "<endereço>/tabelas/hub_stores?lote=1000&forceFunctionRegion=<região>"

O cliente em Node descarrega tudo para uma pasta: as tabelas em CSV, o dicionário, o índice dos ficheiros e os ficheiros. Não tem dependências (Node 18 ou mais recente) e respeita os limites:

ZARVOHUB_CHAVE=<chave> node exportar-dados.mjs "<endereço>?forceFunctionRegion=<região>" pasta-da-copia

Dicionário de dados

Formatos

Contas e organização

hub_atividade Atividade das contas

hub_convites Convites de acesso

hub_den_designacoes Pedidos de designação do canal de denúncias

hub_den_responsaveis Pessoas que recebem as denúncias

hub_permissions Catálogo de permissões

hub_profile_permissions Permissões de cada perfil

hub_profiles Perfis de acesso

hub_rh_funcao_perfil Perfil de acesso por função

hub_rh_store_hours Horário e regras das lojas

hub_stores Lojas e centros de custo

hub_sys_exportacao_chaves Chaves de exportação

hub_users Contas de utilizador

Recursos humanos

hub_rh_absences Faltas e baixas

hub_rh_assets Equipamentos atribuídos

hub_rh_availability Disponibilidade dos colaboradores

hub_rh_aval_notas Notas por critério das avaliações

hub_rh_aval_objetivos Objetivos das avaliações

hub_rh_aval_propostas Propostas de aumento ou promoção

hub_rh_avaliacoes Avaliações de desempenho

hub_rh_calendar_events Eventos do calendário de equipa

hub_rh_checklist_items Tarefas de integração e saída

hub_rh_contabilista_envios Ficheiro do contabilista — meses enviados

hub_rh_documents Documentos dos colaboradores

hub_rh_employees Fichas de colaborador

hub_rh_exit_forms Registos de saída

hub_rh_hour_bank Movimentos do banco de horas

hub_rh_movimentos Transferências e promoções

hub_rh_overtime Horas extra

hub_rh_pay_items Outros vencimentos

hub_rh_pedidos Pedidos de férias e ausência

hub_rh_ponto_avisos Registo de ponto — avisos à chefia

hub_rh_ponto_correcoes Registo de ponto — correções

hub_rh_ponto_marcacoes Registo de ponto — marcações

hub_rh_questionarios Questionários de saída

hub_rh_shift_requirements Necessidades de cobertura das escalas

hub_rh_shift_templates Modelos de turno

hub_rh_shift_weeks Estado semanal das escalas

hub_rh_shifts Turnos das escalas

hub_rh_trainings Formação dos colaboradores

hub_rh_trocas_turno Pedidos de troca de turno

hub_rh_vacation_records Períodos de férias

hub_rh_vacations Saldos de férias antigos