Manual de utilização

Capítulo 1Antes de começar

Para: Todos

O MARCAR recolhe as picagens (de leitores de ponto, de ficheiros, de um quiosque em tablet ou do telemóvel), calcula cada turno com a explicação e a versão da regra, deixa regularizar o que não bate certo e fecha o mês por serviço. Este manual explica, ecrã a ecrã, como se usa.

Cinco ideias para guardar

• O registo bruto nunca se altera. O que o leitor enviou fica como foi enviado. As correcções são registos novos, por cima.
• Tudo o que altera dados pede um motivo (mínimo de 5 caracteres) e fica em auditoria: quem, quando, antes, depois e porquê.
• A hora é a de Luanda (UTC+01, sem hora de Verão). Nos quiosques e nos telemóveis, a hora registada é a do servidor.
• Cada cálculo mostra a regra que usou. Em qualquer dia pode abrir o cálculo e ver as picagens e as frases que explicam o resultado.
• O que não cabe em nenhum turno não desaparece. Fica como pendência, à vista, e impede o fecho do mês até haver decisão.

O ciclo de um mês

1. Carregar o cadastro (pessoas e serviços) e atribuir as escalas.
2. Receber as picagens: dos leitores, de ficheiros CSV, do quiosque ou do telemóvel.
3. Consultar o mapa de assiduidade e abrir o cálculo dos dias que levantam dúvidas.
4. Resolver as pendências: corrigir picagens, aprovar justificações, decidir horas extra.
5. Fechar o mês de cada serviço. Depois do fecho, esse mês já não aceita alterações.
6. Descarregar o relatório mensal para Excel.

Capítulo 2Entrar e orientar-se

Para: Todos

Iniciar sessão

Abra o endereço do sistema na rede da organização e escreva o e-mail e a palavra-passe que o administrador lhe atribuiu. A sessão dura 8 horas. Cinco tentativas falhadas bloqueiam a conta durante 15 minutos, mesmo com a palavra-passe certa.

A primeira palavra-passe

Se a palavra-passe for temporária (nova conta ou reposição), o sistema leva-o logo para Conta e só deixa continuar depois de definir uma nova. A nova palavra-passe tem entre 16 e 72 caracteres. Ao alterá-la, as outras sessões abertas dessa conta terminam.

O menu

Num computador, as vistas estão na barra lateral. Num telemóvel, aparece uma barra inferior com até quatro vistas à mão do polegar e o botão Mais, que abre o menu completo (a tecla Esc fecha-o). As vistas que vê dependem do seu perfil (ver o capítulo seguinte).

O selector de serviço

No topo de cada vista, Serviço filtra tudo o que vê. A chefia só tem os seus serviços; os outros perfis têm também «Todos os serviços». O fecho mensal actua sobre o serviço seleccionado, por isso escolha um antes de fechar.

Terminar sessão

Use Terminar sessão no fundo do menu lateral (ou em Mais, no telemóvel), sobretudo num computador partilhado.

Capítulo 3Perfis e o que cada um pode fazer

Para: Todos

Cada pessoa tem um perfil, atribuído pelo administrador. O perfil decide as vistas que aparecem e as acções que o sistema aceita. Uma acção que o perfil não permite é recusada, mesmo que alguém consiga chegar ao ecrã.

Capítulo 4Preparar o sistema: cadastro, escalas e regras

Para: Administração e RH

Carregar o cadastro

Em Sincronização → Importar cadastro CSV (administração e suporte), cole o conteúdo do ficheiro, escreva o motivo e prima Validar e importar cadastro. Quando o HikCentral estiver ligado, o cadastro vem de lá; até lá, usa-se o CSV.

Colunas: externalId, name, number, serviceId, serviceName (opcional), active (true/false, opcional).

externalId é o número de funcionário no terminal: é ele que liga as picagens à pessoa. Importar de novo actualiza; nunca apaga, só marca active=false.

Atribuir um turno ou uma folga

1. Vá a Operações → Funcionário e dia e escolha o funcionário e a data do turno.
2. Em Atribuir turno ou folga, preencha o início e o fim (hora local). Para uma folga, deixe os dois vazios.
3. Escreva o motivo e prima Guardar escala e calcular.

O início tem de cair na data seleccionada. Um turno nocturno começa nessa data e pode acabar no dia seguinte (no máximo 24 horas). O sistema recalcula o dia e os vizinhos.

Importar escalas em lote

Em Operações → Importar escalas CSV: colunas externalId, day (AAAA-MM-DD), start e end (HH:MM, hora local). Início e fim vazios = folga. Se o fim não for depois do início, o turno acaba no dia seguinte. Máximo de 300 linhas. É tudo ou nada: se uma linha falhar, nada é gravado e o sistema indica qual.

Exemplo:

• externalId,day,start,end
• hik-1,2026-11-02,08:00,16:00
• hik-1,2026-11-03,, (folga)

As regras de cálculo

Em Administração → Regras de cálculo (administração) vê e regista as regras. Uma regra tem vigência: nunca se altera, cria-se uma nova vigência. Sem regra em vigor, os dias ficam pendentes.

Feriados

Em Administração → Feriados: indique o dia e o nome, escreva o motivo e prima Guardar feriado e recalcular. O sistema recalcula os turnos desse dia.

Capítulo 5Receber as picagens

Para: Administração, RH e suporte

As fontes

• Leitores Hikvision (directo ao terminal ou pelo HikCentral Professional) e ZKTeco (o terminal envia cada picagem no momento em que acontece).
• Suprema BioStar X, com validação do modelo e da versão na instalação.
• Entrada genérica de eventos, para qualquer equipamento ou programa que envie HTTP assinado (por exemplo Dahua ou Uniview, por um programa intermédio).
• Ficheiros CSV, importados no ecrã Sincronização.
• Quiosque (tablet fixo) e telemóvel pessoal, geridos em Picagem móvel.

A ligação aos leitores faz-se no capítulo Suporte e TI. O guia Como ligar leitores de ponto explica as quatro vias.

Importar picagens por ficheiro

1. Vá a Sincronização → Importar picagens CSV (administração e suporte).
2. Indique o início do intervalo (hora local). Eventos fora do intervalo ficam registados como anomalia.
3. Cole o conteúdo, escreva o motivo e prima Validar e importar.

Colunas: sourceEventId, terminalId, personExternalId, occurredAt, direction, method. A hora leva sempre o fuso, por exemplo 2026-09-08T07:55:00+01:00.

• Importar duas vezes não duplica.
• Um sourceEventId reutilizado com conteúdo diferente recusa a importação inteira.
• Depois da importação, o sistema diz quantos eventos novos entraram e quantos dias recalculou.

O que fica à vista

• Uma picagem que não se liga a nenhum turno fica como pendência.
• Duas picagens da mesma pessoa em canais diferentes, muito próximas, ficam como possível duplicado.
• Uma picagem que chega depois de o mês estar fechado fica como evento tardio até o mês ser reaberto com motivo.

Capítulo 6Ler o mapa de assiduidade

Para: Todos

A vista Assiduidade mostra uma linha por pessoa e dia, com o estado, o trabalho, o atraso e a extra validada. Em cima, quatro números resumem o que está calculado: dias calculados, presentes, incompletas e pendências. A caixa Pesquisar por nome, número ou data filtra a lista, e Actualizar volta a ler os dados. A lista mostra os 500 dias mais recentes; para um mês completo, use Relatórios.

Os estados

Os minutos antes e depois do turno são candidatos a hora extra e só somam depois de validados por uma pessoa.

Abrir o cálculo de um dia

Prima Ver cálculo numa linha. Abre-se um painel com a linha do dia, as picagens usadas, o estado e as frases que explicam o resultado, mais a versão da regra aplicada. Se o dia tem uma picagem inserida à mão, o painel diz isso e mostra o motivo registado. O registo técnico do cálculo serve para o suporte e para auditorias; os identificadores das picagens que lá aparecem são os que se usam nas correcções.

Capítulo 7Resolver pendências, correcções e justificações

Para: RH, chefias e administração

Uma pendência é algo que o sistema não decide sozinho. Cada pendência impede o fecho do mês do serviço até haver decisão. Na vista Pendências vê o resumo por tipo, a lista, e (a seguir) as justificações. O botão Seleccionar em Operações leva a pessoa e o dia directamente para o sítio onde se resolve.

Como se resolve cada uma

Algumas situações (por exemplo um evento não associado, um possível duplicado, uma regra ausente) podem ser dispensadas com motivo pelo RH ou pela administração, depois de verificadas. O motivo fica em auditoria.

Regularizar uma picagem

1. Em Operações, escolha o funcionário e a data do turno.
2. Em Regularizar picagem, preencha a hora da picagem em falta (hora local), ou o evento bruto a anular, ou os dois para substituir.
3. Escreva o motivo e prima Registar correcção.

Os registos brutos nunca se alteram. Para desfazer uma correcção, abra Correcções deste dia e prima Anular esta correcção, com motivo.

Justificar uma ausência

1. Em Operações, escolha o funcionário e o dia e, em Submeter justificação de ausência, escreva o motivo.
2. A chefia do serviço aprova (1.º nível). Depois o RH confirma (2.º nível). Cada passo faz-se em Pendências → Justificações, com Registar decisão.
3. O estado da justificação vê-se na lista: «Por decidir», «Aprovada pela chefia, falta o RH», «Aprovada» ou «Recusada».

O prazo para justificar é de 5 dias úteis na regra proposta. Passado o prazo, só o RH ou a administração podem submeter, e têm de escrever o motivo de desbloqueio (campo «Desbloqueio de prazo, se necessário»).

Validar horas extra

Em Operações → Validar horas extra, marque as categorias a aprovar para o dia: antes do turno, após o turno, folga e feriado. As caixas mostram o que já está aprovado. Escreva o motivo e prima Guardar validação. Uma categoria desmarcada fica registada como recusada.

Anomalias da sincronização

No fundo de Pendências aparecem avisos sem serviço associado (um carimbo de hora anormal, um formato inválido, um terminal desconhecido). Não bloqueiam fechos. Verifique a origem (terminal, relógio, cadastro) e dispense com motivo.

Capítulo 8Fechar o mês e tirar o relatório

Para: RH e administração

Fechar o mês

1. Seleccione o serviço no topo da página.
2. Vá a Operações → Fecho mensal (RH e administração).
3. Escolha o mês e a operação Fechar, escreva o motivo e prima Fechar (o botão mostra o mês).

O sistema recalcula tudo, recusa se houver pendências por resolver e, se estiver tudo resolvido, guarda uma fotografia imutável do mês desse serviço. Depois do fecho, nada nesse mês aceita alterações. As picagens que cheguem tarde ficam como evento tardio até o mês ser reaberto.

Reabrir um mês

Só a administração reabre um mês fechado: no mesmo painel, escolha a operação de reabrir e escreva o motivo. A reabertura fica em auditoria. Depois de corrigir, feche de novo.

O relatório mensal

Em Relatórios, escolha o mês (e, no topo, o serviço) e prima Ver relatório. Mostra, por pessoa, os dias previstos, a presença, os atrasos, os dias sem registo, as justificações, o tempo trabalhado, as horas extra aprovadas e os dias com pendências por resolver.

Descarregar para Excel

Descarregar para Excel gera um ficheiro em português (separador ;, acentos correctos) que mantém os zeros à esquerda do número do funcionário e o mês como texto. CSV simples serve para outros programas. As colunas são:

• Serviço, mês, estado do mês, número e nome.
• Dias previstos, com presença, com atraso, com saída antecipada, sem registo, justificados, com picagem incompleta, folgas e feriados, e com pendências.
• Trabalhado (minutos e h:mm), atraso, saída antecipada, atraso justificado, saída antecipada justificada, nocturno.
• Extra aprovado (minutos e h:mm).

Capítulo 9Gerir a picagem sem leitor

Para: RH e administração

A vista Picagem móvel (RH e administração) gere os dois modos de picar sem leitor. Se a função ainda não estiver activada no servidor, a vista diz «Picagem móvel desactivada» e indica que o técnico de TI a tem de configurar. Para escolher entre os dois modos, veja o guia quiosque ou telemóvel.

Emitir ou repor o PIN de uma pessoa

1. Em Emitir ou repor PIN, escolha o funcionário e escreva o motivo.
2. Prima Gerar PIN. O PIN aparece uma só vez. Copie-o e entregue-o em mão (nunca por e-mail nem mensagem).
3. Prima Já copiei, esconder.

O PIN é pessoal e temporário: a pessoa troca-o na primeira utilização. Repor desbloqueia a conta de picagem e volta a exigir a troca. Cinco PINs errados bloqueiam essa pessoa durante 15 minutos, mesmo com o PIN certo.

Ligar um quiosque (tablet fixo)

1. Em Quiosques (tablet fixo), preencha o identificador (3 a 32: minúsculas, números, - e _), o nome (por exemplo «Urgência, entrada»), o serviço (opcional) e o sentido, e prima Criar quiosque.
2. Aparece um código de uso único, válido 10 minutos.
3. No tablet, abra o endereço /picar do sistema, escreva o código e prima Ligar. Instale a página no ecrã inicial (menu do navegador → «Adicionar ao ecrã principal»).

O sentido do quiosque pode ser: a pessoa escolhe Entrada ou Saída, só entradas, só saídas, ou sem sentido. Tablet roubado ou substituído: prima Revogar (o tablet deixa de valer de imediato) ou Novo código (invalida o anterior).

Aprovar o telemóvel de uma pessoa

Cada pessoa regista o seu telemóvel uma vez, em /eu. Depois, em Telemóveis pessoais, o RH escreve o motivo e prima Aprovar. Só pode haver um telemóvel por pessoa. Se a pessoa mudar de telemóvel, Revogue o antigo primeiro; a pessoa regista o novo e o RH aprova.

Definir os locais permitidos

Sem locais configurados, a picagem no telemóvel está recusada. Em Locais permitidos para a picagem no telemóvel, defina para cada edifício:

• o centro (latitude e longitude); o botão Usar a minha posição actual preenche-os quando o administrador está no local;
• o raio (10 a 2000 metros);
• a precisão máxima do GPS (5 a 500 metros; 50 por omissão), que recusa leituras pouco fiáveis;
• se o local está activo.

Guardar com um identificador existente actualiza o local. Os valores certos para cada edifício têm de ser medidos no local. O servidor decide se a pessoa está dentro do perímetro; guarda só «dentro/fora», a distância arredondada a 10 m e a precisão arredondada a 5 m, nunca a coordenada.

Situações do dia a dia

Capítulo 10Picar o ponto: quiosque e telemóvel

Para: Funcionários

Dois princípios valem nos dois modos: a hora registada é a do servidor e sem ligação não há picagem. Se a rede falhar, o ecrã diz que não conseguiu registar; nada fica guardado no aparelho para enviar depois. Se isso acontecer, avise a chefia ou o RH.

No quiosque (tablet do serviço)

1. Escreva o seu número de funcionário.
2. Escreva o seu PIN no teclado do ecrã.
3. Se o ecrã pedir, escolha Entrada ou Saída. Noutros quiosques o botão já diz «Registar entrada» ou «Registar saída».
4. O ecrã mostra o seu nome e a hora registada. Os campos apagam-se sozinhos (e também ao fim de 60 segundos sem actividade).

Pode ver as suas últimas picagens com Ver as minhas picagens (pede o número e o PIN). Mostra as últimas 10, com o estado «Registada» ou «A processar».

No telemóvel pessoal

A primeira vez (uma só vez):

1. Abra o endereço /eu do sistema no navegador do telemóvel.
2. Escreva o seu número de funcionário e o PIN temporário que o RH lhe entregou, e prima Registar.
3. Escolha o seu PIN (o temporário só serve para isto) e prima Guardar PIN.
4. O ecrã diz «À espera de aprovação». Quando o RH aprovar o telemóvel, prima Verificar de novo.

Todos os dias:

1. Abra /eu, escreva o PIN e prima Entrada ou Saída.
2. O navegador pede a localização: aceite. Só funciona dentro do local de trabalho. A localização é verificada no servidor e não fica guardada.
3. O ecrã confirma, por exemplo «Entrada registada às 10:37».

Se não funcionar

Capítulo 11Para chefias e direcção

Para: Chefias e direcção

A chefia

Ao entrar, a chefia fica logo no primeiro dos seus serviços. Só vê os serviços que o administrador lhe atribuiu; se a conta não tiver nenhum, o sistema avisa e pede para os definir. A chefia pode:

• Acompanhar o serviço em Assiduidade (estados, atrasos, ausências) e abrir o cálculo de qualquer dia.
• Aprovar ou recusar justificações (1.º nível) em Pendências → Justificações. Depois o RH confirma.
• Submeter uma justificação em nome de um funcionário, em Operações.
• Validar horas extra: antes do turno, após o turno, folga e feriado.
• Descarregar o relatório mensal do serviço, para conferir antes do fecho.

A chefia não atribui escalas, não corrige picagens e não fecha o mês. Se encontrar uma picagem em falta, avise o RH, indicando a pessoa, o dia e a hora provável.

Uma rotina semanal sugerida

1. Abra Pendências e veja o resumo por tipo.
2. Decida as justificações da sua equipa.
3. Valide as horas extra dos dias em que houve trabalho antes ou depois do turno.
4. Avise o RH das picagens incompletas.

A direcção

A direcção consulta sem alterar. Vê todos os serviços, o mapa, as pendências, o cadastro e os relatórios mensais, e pode descarregar o relatório. Não aprova nem corrige nada. Cada cálculo mostra a regra que usou, por isso é possível auditar um número sem pedir explicações a ninguém. Na vista Auditoria vê quem fez cada alteração e quando.

Capítulo 12Administração: utilizadores, regras e feriados

Para: Administração

Criar um utilizador

1. Em Administração → Criar utilizador, escreva o e-mail e uma palavra-passe inicial (16 a 72 caracteres).
2. Escolha o perfil. Para a chefia, atribua também os serviços.
3. Escreva o motivo e prima Criar utilizador.

A palavra-passe inicial é temporária: a pessoa é obrigada a trocá-la na primeira entrada. Entregue-a em mão, não por e-mail.

Gerir um utilizador existente

• Estado: activar ou desactivar. Desactivar termina logo as sessões da pessoa.
• Repor palavra-passe: define uma palavra-passe temporária (16 a 72 caracteres) e termina as sessões. Prima Repor e terminar sessões.
• Terminar sessões: termina todas as sessões da conta, com motivo, por exemplo se um computador ficou aberto.
• Suporte: o perfil de suporte nasce com o acesso desligado. Ligue-o só durante a intervenção e desligue-o no fim.

Todas estas acções pedem motivo e ficam registadas.

Regras de cálculo e feriados

Descritos no capítulo Preparar o sistema. Uma regra nunca se altera: regista-se uma nova vigência, e os dias já calculados mantêm a versão com que foram calculados.

Auditoria

Cada alteração fica numa auditoria só de acrescento: quem, quando, o antes, o depois e o motivo. Ninguém a edita nem apaga, nem sequer a administração. O mesmo vale para as picagens brutas. As exportações de relatórios e as consultas do perfil de suporte também são registadas.

Para a consultar, abra a vista Auditoria (administração e direcção). Os registos aparecem do mais recente para o mais antigo. Filtre por acção, por quem (parte do e-mail) e por datas (hora de Luanda), e prima Carregar mais para ver registos mais antigos.

• A administração vê, em cada registo, o motivo, o identificador, o endereço de origem, e o antes e o depois (em Detalhe). Pode também pesquisar por texto no motivo e exportar para Excel (até 5000 registos); cada exportação fica ela própria registada.
• A direcção vê só quando, quem, a acção e a entidade, sem motivo nem detalhe, porque esses campos podem ter dados pessoais.

Capítulo 13Suporte e TI: sincronização e conectores

Para: Suporte e TI

A vista Sincronização (administração e suporte) liga o MARCAR aos leitores e recebe os ficheiros. As credenciais de acesso aos leitores são instaladas no servidor pelo técnico de TI, nunca no ecrã; sem elas, o conector não pode ser activado. A instalação do servidor está em docs/ARRANQUE.md.

Ligar um conector

1. Preencha as credenciais no .env do servidor e reinicie o servidor.
2. Em Conectores, prima Testar ligação. O teste mostra o número de série ou a versão, os eventos da última hora e as pessoas, e não grava nada.
3. Prima Activar, com motivo (só a administração activa).
4. Prima Reconciliar 7 dias para ler a última semana.

Depois disso, o ciclo automático (npm run sync) lê de 5 em 5 minutos, com sobreposição de 30 minutos, e reconcilia 7 dias uma vez por dia. Sincronizar agora força uma leitura. Em falhas seguidas, o ciclo recua até 1 hora e retoma sozinho.

Terminais ZKTeco

1. No terminal: Comunicação → Servidor na nuvem (ADMS), com o IP do servidor e a porta.
2. O terminal aparece em Terminais ZKTeco como «por aprovar». Dê-lhe um nome e prima Aprovar terminal (administração).
3. Active o conector. Até estar activo, as picagens esperam na caixa de entrada e entram quando for activado.

Fontes de eventos (entrada genérica)

Para leitores de qualquer marca que enviem as picagens por um programa intermédio. Em Fontes de eventos, escreva o identificador (minúsculas, números, - e _; 3 a 32), o nome e o motivo, e prima Criar fonte. Cada fonte tem o seu segredo, que aparece uma só vez: copie-o logo para o programa que envia e prima Já copiei, esconder.

• Rodar segredo cria um segredo novo (o antigo deixa de valer).
• Revogar fonte corta a fonte de imediato. Use-o se suspeitar que o segredo foi comprometido.
• Os pedidos levam assinatura, um valor único (nonce) e a hora; o relógio do emissor tem de estar certo (margem de 5 minutos).

Importações e execuções

As importações de cadastro e de picagens por CSV estão nos capítulos Preparar e Receber as picagens. Em Últimas execuções vê cada sincronização, com o estado e o último erro. Enquanto uma sincronização está a correr, a vista actualiza-se de 5 em 5 segundos.

Erros que aparecem

A lista completa e o procedimento para cada incidente (aplicação, base de dados, disco, cópias de segurança) estão no docs/RUNBOOK.md.

Capítulo 14Problemas frequentes e referência rápida

Para: Todos

O sistema recusa uma acção

Folha de consulta

Mais ajuda

• Dentro do sistema: o botão ? (Ajuda) no topo de cada vista.
• Os termos: o glossário de assiduidade.
• Experimentar sem risco: a demonstração interactiva, com dados fictícios.
• Falar connosco: o pedido de demonstração.