Fluxo principal
Login, validação de contexto da empresa, execução por módulo e auditoria de operações sensíveis.
Visão Geral do Sistema
O FRH é uma plataforma SaaS de RH com operação multiempresa, trilha de auditoria e módulos para cadastro, ponto, folha, eSocial, equipamentos e monitoramento. O acesso é controlado por perfil e permissão, com isolamento por tenant.
Arquitetura
Backend .NET 8 (Domain/Application/Infrastructure/API) e front-end HTML + JavaScript.
Conceitos chave
X-Tenant-Id, deduplicação por NSR/serial, eventos auditáveis e validação de conformidade.
Mapa Completo de Módulos e Telas
Inventário operacional das principais telas para cobrir todo o sistema em um único manual.
| Domínio | Telas principais | Objetivo operacional |
|---|---|---|
| Nucleo | /login.html, /index.html, /modulos.html, /notificacoes.html | Acesso, painel executivo, navegação por módulo e comunicação operacional. |
| Portal do Colaborador | /portal-colaborador.html | Área exclusiva do colaborador, PWA, notificações, contracheques, solicitações, biometria facial e ponto móvel com localização/prova de vida. |
| Cadastros RH | /cadastros.html, /cadastros-funcionarios.html, /cadastros-empresas.html, /cadastros-usuarios.html, /cadastros-perfis.html, /livro-registro.html | Base cadastral de pessoas, empresas, usuários, perfis, políticas e livro de registro. |
| Ponto e Escalas | /cadastros-ponto.html, /cadastros-turnos.html, /cadastros-banco.html, /folha-ponto.html, /auditoria-ponto.html | Jornada, marcações, banco de horas, espelho mensal e rastreabilidade de alterações. |
| Rotinas RH | /cadastros-ferias.html, /cadastros-atestados.html, /aprovacoes.html | Ciclo de solicitação, análise e aprovação de rotinas trabalhistas. |
| Folha de Pagamento | /folha-pagamento.html, /folha-base-operacional.html, /folha-catalogo-rubricas.html, /folha-operacao-mensal.html, /folha-geracao-manual.html, /folha-tributos.html | Configuração, rubricas, cálculo automático de INSS/IRRF/FGTS/salário família e emissão de contracheque. |
| Cálculos Especiais | /rescisoes.html, /decimo-terceiro.html, /fgts-digital.html | Verbas rescisórias, 13º salário e consolidação de guias de FGTS. |
| Compliance e Legal | /compliance-folha.html, /relatorios-legais.html, /saude-seguranca-trabalho.html | Documentos assinados digitalmente, CAGED/RAIS/DIRF e evidências de SST (NR-17/CAT/PPP). |
| eSocial | /esocial-ambiente.html, /esocial-dados.html, /esocial-eventos-manual.html | Ambiente, credenciais, matriz de eventos, geração assistida e transmissão de lotes. |
| Equipamentos e Integrações | /cadastros-coletores.html, /admin-equipamentos.html, /admin-validacao.html, /controlid-provisionamento.html, /topdata-comandos.html, /operacao-terminais.html, /ferramentas.html | Cadastro de equipamentos, sincronização, validação de canal e operação por fabricante. |
| Biometria e Credenciais | /biometria.html, /credenciais.html | Cadastro biométrico e meios de autenticação do colaborador. |
| Monitoramento e Analytics | /monitor-eventos.html, /monitoramento.html, /analytics.html | Monitor em tempo real, saúde de coletores e relatórios com exportação CSV/PDF. |
| Governança e SaaS | /admin-configuracao.html, /admin-auditoria.html, /licenciamento.html, /licencas-planos.html, /escritorios-contabilidade.html, /configuracao-email.html | Configurações globais, trilha de auditoria, planos, licenciamento e escritórios de contabilidade parceiros. |
| Controle de Acesso | /controle-acesso-dashboard.html, /controle-acesso-pessoas.html, /controle-acesso-credenciais.html, /controle-acesso-grupos.html, /controle-acesso-equipamentos.html, /controle-acesso-monitoramento.html | Unidades, locais, pessoas, visitantes, grupos, credenciais, equipamentos, permissões e eventos físicos. O acesso depende da licença e das permissões do perfil. |
| Financeiro e comercial | /financeiro.html, /operacoes-tesouraria.html, /conciliacao-bancaria.html, /bi-financeiro.html, /relatorios-financeiros.html, /faturas-licenciamento.html, /comercial-precos-revenda.html, /comercial-contratos.html | Caixas, contas, movimentos, títulos, conciliação, fluxo, BI, relatórios, faturamento, contratos e preços por revenda. O acesso depende da permissão financeira/comercial e da licença do módulo. |
| Pagamentos por empresa | /api/financeiro/pagamentos/integracao/status e /api/financeiro/pagamentos/integracao/configuracao | Cada empresa escolhe Itaú/Caixa para Pix e boleto e Rede/Stone/Cielo para cartão e link. Segredos ficam somente em referências do cofre; a ativação real é operacional. |
| Aplicativos web | /portal-colaborador.html, /controle-acesso-dashboard.html, /financeiro.html | Portais instaláveis no celular: Colaborador, Controle de Acesso e Financeiro. A instalação respeita a sessão, licença e permissão do usuário. |
Licenciamento, Menus e Permissões
O que aparece no menu
O sistema combina licença do módulo, empresa selecionada, perfil e permissão. Um link só aparece quando o usuário pode executar aquele contexto.
Seleção de módulos
Em /modulos.html aparecem somente aplicações liberadas para a empresa. Ao trocar de empresa, atualize a seleção antes de operar.
Sem acesso
Quando uma página não pertence ao perfil ou à licença, o portal redireciona para uma área permitida e a API continua protegendo a operação.
Administrador global
O administrador global pode selecionar empresas autorizadas e administrar planos. Essa visão não deve ser atribuída a usuários comuns.
Financeiro, Obrigações e Pagamentos
Rotina financeira
Cadastre contas, caixas e centros de custo; lance títulos; registre baixas; acompanhe fluxo, DRE e conciliação. Movimentos são auditáveis e estornos geram novos movimentos.
Obrigações legais
Folha, FGTS, INSS, IRRF, férias, rescisão e 13º geram cálculo interno. Conta a pagar só nasce após confirmação explícita com valor oficial e referência.
Pagamentos por cliente
O administrador financeiro configura os provedores da própria empresa. Nunca informe número completo de cartão ao FRH; use checkout/tokenização do provedor.
Produção
A ativação real depende de certificado, SecretRef, webhook, credenciais institucionais e validação operacional. O botão de validação não executa cobrança.
Controle de Acesso
O módulo organiza a operação física por empresa, com separação entre estrutura, pessoas, credenciais, regras de acesso, visitantes, equipamentos e eventos.
Estrutura
Cadastre unidades e locais de acesso antes de criar grupos e permissões. Mantenha cada item no contexto da empresa correta.
Pessoas e credenciais
Associe pessoas, cartões, PINs, RFID e biometria ao cadastro correto. Revise a situação da credencial antes de liberar o acesso.
Grupos e permissões
Defina horários, dias permitidos, locais e vínculos de pessoas. Alterações ficam sujeitas às permissões administrativas do perfil.
Equipamentos e eventos
Cadastre o equipamento, valide o canal e acompanhe sincronização, saúde, decisões e eventos no monitoramento.
Financeiro e Comercial
O módulo financeiro é organizado por empresa e combina tesouraria, títulos, conciliação, relatórios, BI, faturamento e integrações de pagamento.
Tesouraria
Cadastre contas e cartões, abra caixas, registre suprimentos e sangrias e acompanhe saldos e movimentos.
Títulos e fluxo
Crie contas a pagar e receber, consulte vencimentos, baixas e fluxo previsto/realizado sem misturar empresas.
Conciliação e BI
Importe extratos, revise linhas pendentes e use BI/relatórios para analisar caixa, DRE e indicadores financeiros.
Licenciamento e revenda
Administre planos, preços, contratos comerciais e faturas conforme o papel da empresa na estrutura de distribuição.
Cadastros: Contexto e Utilização
Funcionários
Use para consolidar CPF, PIS, admissão, salário base, turno e dados de contato. Impacta ponto, folha e eSocial.
Empresas
Use para CNPJ, parâmetros de folha, ambiente eSocial e políticas operacionais por tenant.
Usuarios e perfis
Use para RBAC. Controle quem pode registrar ponto, exportar dados, aprovar e administrar integrações.
Turnos e ponto
Use para jornada padrão, tolerâncias e base de cálculo de horas extras/noturnas/faltas.
Banco de horas e livro de registro
Use para lançar créditos/débitos de horas com visão legal, e para gerar o Livro de Registro de Empregados por colaborador.
Férias e atestados
Use para solicitar e aprovar férias e afastamentos médicos, com status e vínculo a documento comprobatório.
Coletores, biometria e credenciais
Use para cadastrar equipamentos de ponto, credenciais biométricas (digital/facial) e meios de acesso (cartão/crachá/PIN) por colaborador.
Operação Integrada: Ponto, Folha e eSocial
1. Fechamento de ponto
Valide o espelho mensal por colaborador e lote antes da geração de eventos de folha.
2. Processamento automático de eventos de ponto
Em /folha-operacao-mensal.html, processe por competência para gerar automaticamente horas extras, adicional noturno e desconto de faltas a partir das marcações reais (sem digitação manual).
3. Cálculo automático de encargos
Um único clique aplica INSS/IRRF progressivos, FGTS, salário família e descontos de vale-transporte/refeição, consolidando tudo na apuração do mês.
4. Emissão de contracheque
Imprima o espelho individual ou em lote (PDF), com rótulos claros e sem duplicidade de linhas entre rubricas manuais e valores calculados.
5. Lote eSocial
Ao final do processamento, opcionalmente crie o lote eSocial da competência já refletindo os tributos calculados no líquido do evento.
Folha de Pagamento: Cálculo Automático de Encargos Legais
A tela Operação Mensal (/folha-operacao-mensal.html) é o coração do módulo de folha: calcula automaticamente todos os encargos legais do colaborador a partir do salário, dependentes, benefícios cadastrados e das marcações de ponto já processadas.
INSS e IRRF
Tabelas progressivas versionadas (/folha-tributos.html), com dedução por dependente no IRRF e escolha automática entre desconto simplificado e legal quando aplicável.
FGTS
Cálculo de 8% sobre a base tributável, com base de cálculo exposta na apuração para conferência.
Salário família
Valor por filho conforme faixa de renda vigente (/folha-tributos.html), isento de INSS/IRRF/FGTS.
Horas extras e adicional noturno
Detectados automaticamente a partir do módulo de ponto real do colaborador — não é necessário informar horas manualmente.
Vale-transporte e vale-refeição
Desconto de VT limitado ao teto legal de 6% do salário (ou valor concedido, o que for menor); desconto de VR/outros benefícios configurável por percentual em /folha-base-operacional.html.
Rescisões e 13º salário
Em /rescisoes.html e /decimo-terceiro.html: cálculo completo de verbas rescisórias e 13º (avos, INSS, IRRF) com histórico de cálculos.
eSocial: Ambiente, Credenciais e Transmissão de Eventos
Ambiente controlado
Em /esocial-ambiente.html, alterne entre Homologação e Produção com confirmação explícita e trilha de auditoria da troca.
Credenciais e mapeamentos
Em /esocial-dados.html, gerencie certificado digital, procuração, matriz de eventos MVP e mapeamento de rubrica para código eSocial.
Geração assistida de eventos
Em /esocial-eventos-manual.html, o assistente sugere a cadeia mínima por competência (S-1200, S-1210, S-1299, S-2200 na admissão, S-2299 no desligamento).
Histórico e recibos
Consulte lotes enviados, protocolo, recibo e mensagens de retorno do governo, com filtro por status e texto livre.
Compliance, Documentos Legais e Saúde e Segurança do Trabalho
Modelos e assinatura digital
Em /compliance-folha.html, crie modelos de contracheque/contrato com tokens dinâmicos, gere PDF/XLS e assine digitalmente com verificação de integridade.
Relatórios legais
Em /relatorios-legais.html, consulte CAGED (movimentações), RAIS (resumo anual) e DIRF (IRRF retido), todos derivados dos eventos eSocial.
Saúde e segurança do trabalho
Em /saude-seguranca-trabalho.html, registre avaliações ergonômicas (NR-17), CAT (acidente de trabalho) e condições ambientais, base para emissão do PPP.
FGTS Digital
Em /fgts-digital.html, consolide internamente as guias por competência (folha, rescisões, multas, 13º) e controle status de pagamento.
Governança, Multiempresa e Modelo SaaS
Usuários e perfis (RBAC)
Em /cadastros-usuarios.html e /cadastros-perfis.html: controle de acesso por permissão granular, com builder visual e monitor de risco de perfis sensíveis.
Multiempresa
Em /cadastros-empresas.html, opere matriz/filiais no mesmo tenant com isolamento de dados por empresa.
Escritórios de contabilidade
Em /escritorios-contabilidade.html, vincule um escritório a várias empresas-cliente; o usuário do escritório alterna de empresa pelo seletor no topo.
Planos e licenciamento
Em /licencas-planos.html defina pacotes comerciais (módulos, limite de funcionários, duração); em /licenciamento.html aplique/renove a licença por empresa, com alerta automático antes do vencimento.
Servidor de email
Em /configuracao-email.html, configure o SMTP usado para alertas operacionais e avisos automáticos de expiração de licença.
Segurança da Conta: Troca de Senha
Qualquer usuário autenticado pode trocar a própria senha a qualquer momento, em qualquer tela do sistema, sem depender de suporte técnico.
Como trocar
Clique em "Trocar senha" na barra superior, informe a senha atual e a nova senha (mínimo 8 caracteres) duas vezes para confirmação.
Persistência garantida
A nova senha é validada e passa a valer imediatamente, inclusive após reinícios do servidor — não há retorno para uma senha padrão.
Redefinição administrativa
Um administrador com permissão de gestão de usuários pode redefinir a senha de outro usuário em /cadastros-usuarios.html, caso necessário.
Portal do Colaborador, PWA e Ponto Móvel
O Portal do Colaborador é uma área restrita. Usuários com perfil somente Colaborador não visualizam barra superior de módulos, menu administrativo, cadastros ou links de gestão.
Acesso correto
O usuário precisa ter perfil Colaborador e o funcionário ativo precisa estar vinculado ao usuário em Cadastros > Usuários/Funcionários.
Instalação PWA
Abra /portal-colaborador.html no celular, instale pelo navegador e mantenha permissões de câmera, localização e notificações habilitadas.
Notificações
O botão Ativar notificações usa Web Push próprio. Em produção, as chaves VAPID ficam configuradas no serviço FRH-API via ambiente do NSSM.
Ponto móvel
Exige empresa com ponto móvel habilitado, latitude/longitude da unidade, raio permitido, localização fresca e consentimentos de localização/selfie.
Biometria facial
O colaborador cadastra a selfie no portal. O administrador consulta e libera recadastro em /biometria.html, na seção Biometria Facial.
Erros de validação
Mensagens de ponto móvel exibem o primeiro detalhe retornado pela API: localização, raio, biometria ausente, prova de vida ou identidade facial.
Configuração da Empresa para Ponto Móvel
Em /cadastros-empresas.html, edite a empresa e preencha o bloco Ponto móvel. Se localização obrigatória estiver ativa, latitude e longitude da unidade são obrigatórias.
| Campo | Uso | Valor típico |
|---|---|---|
| Ponto móvel | Habilita ou bloqueia o registro pelo portal/PWA. | Habilitado para empresas aprovadas. |
| Localização obrigatória | Exige GPS e consentimento no dispositivo. | Obrigatória. |
| Selfie obrigatória | Exige biometria facial e prova de vida renovada. | Obrigatória. |
| Raio permitido | Distância máxima entre GPS do colaborador e centro da unidade. | 30 metros, ajustável por política. |
| Latitude/Longitude | Centro geográfico usado pelo validador do ponto móvel. | Coordenadas da unidade operacional. |
Equipamentos Homologados e Canais
| Fabricante | Modelo | Status | Canal | Endpoint principal |
|---|---|---|---|---|
| Topdata | Inner Rep Plus | Homologado em produção | Gateway direto e contingência AFD | /api/integracoes/ponto/topdata/inner-rep-plus/marcacoes |
| Topdata | Leitor Facial F4 | Homologado em campo | WebSocket + sync de funcionários | /api/coleta-ponto/equipamentos/{id}/sincronizar-funcionarios |
| Control iD | iDRep, iDFace, iDAccess, iDFit, iDFlex | Operacional | Nuvem e Direto | /api/integracoes/ponto/controlid/[modelo]/nuvem/marcacoes/lote |
| Generico | REP compatível AFD | Suportado | Arquivo | /api/coleta-ponto/equipamentos/{id}/afd-importacoes |
| Generico | HTTP Push | Suportado | HTTP | /api/coleta-ponto/equipamentos |
Cadastro Facial de Visitantes
O visitante consegue confirmar o convite, informar seus dados e cadastrar a facial pelo celular em /convite-visitante.html.
Convite e dados
Valide o token, preencha nome, documento, contato e cartão de aproximação quando aplicável.
Facial pelo celular
Abra a câmera, mova lentamente o rosto, capture a selfie e salve. A prova de vida é validada antes de registrar a biometria.
Reuso seguro
O sistema cria ou reaproveita a pessoa de acesso do convite e grava a facial em PessoaBiometriaFacial, com expiração junto ao convite.
Topdata: Operação Atual e Anti-regressão
Servidor e REP vigentes
Ambiente operacional protegido. Endereços, portas, chaves e credenciais de equipamentos não são publicados na Central de Ajuda; consulte o runbook interno autorizado.
Fluxo F4 WebSocket
Manter rota /ws/topdata/f4* no proxy e validar sincronização sem 405/not connected apos toda atualização.
Bridge e coletor
Não desativar caminho ativo sem evidências. Se FRH.TopdataBridge estiver operando, preserve essa trilha no deploy.
Checklist obrigatorio
Execute docs/topdata-homologation-checklist.md e docs/topdata-operacao-atual.md em toda janela de release.
Monitoramento e Auditoria
O monitor de eventos consolida marcações de hardware, auditoria de ponto e fila biométrica. Use filtro por serial + status para troubleshooting rápido.
Filtros disponiveis
Tipo, status, PIS/CPF, serial do equipamento, período e texto livre.
Atualização automática
Leitura quase em tempo real para análise de incidentes e regressão pos deploy.
Endpoint base
GET /api/monitor/eventos, com rastreio de origem e status dos canais de integração.
Segurança e Integrações
Topdata
Gateway com X-Topdata-ApiKey e trilha operacional guiada por checklist de homologação.
Control iD
Nuvem com X-ControlId-Cloud-Key e Direto com X-ControlId-Direct-Key, com foco em envio de marcações para FRH.
Escopo por tenant
Integrações exigem X-Tenant-Id válido para isolamento multiempresa e auditoria consistente.
O provisionamento de funcionários para equipamento Control iD foi descontinuado por regra oficial. O fluxo suportado é unidirecional: equipamento envia marcações para o FRH.
Troubleshooting Operacional
Sem eventos chegando
Validar chave do canal, X-Tenant-Id, endpoint no equipamento e conectividade de rede.
Eventos rejeitados
Conferir PIS/CPF, serial cadastrado, data/hora da marcação e permissão do endpoint.
Duplicidade de batidas
Revisar NSR + serial e verificar se houve reenvio da mesma marcação no coletor.
Falha em processamento de folha
Checar competência, percentual noturno e aviso de conflito de salário base manual.
eSocial bloqueado
Validar ambiente, credencial ativa e matriz de dependências antes de enviar lote.
Deploy sem refletir no site
Confirmar AppDirectory ativo do FRH-API, copiar para wwwroot correto e atualizar versionadores dos assets compartilhados. Para mudanças estáticas, não é necessário reiniciar a API.
Colaborador vendo menu administrativo
Validar se /portal-colaborador.html está usando js/portal.js?v=20260906-portal-hotfix ou posterior. Colaborador puro deve ficar restrito ao portal.
Biometria facial não aparece
Em /biometria.html, selecione o funcionário marcado com "facial cadastrada". A lista mostra somente a biometria do funcionário selecionado.
Capturas de Tela com Contexto e Utilização
Como usar: autentique, confirme tenant ativo e prossiga para o dashboard.
Como usar: monitore KPI e entre no módulo com pendência operacional.
Como usar: priorize Funcionários, Empresas, Usuários e Perfis antes da operação diária.
Como usar: registre serial/canal e valide o endpoint correto por fabricante.
Como usar: execute validações por serial e acompanhe status antes de liberar produção.
Como usar: associe credenciais ao funcionário correto para evitar rejeição de batidas.
Como usar: valide qualidade da coleta e status de sincronização com equipamento.
Como usar: execute smoke checks e registre evidências no ciclo de release.
Como usar: acompanhe caixas, contas, títulos, conciliação e fluxo conforme as permissões do perfil.
Como usar: navegue por pessoas, credenciais, grupos, equipamentos e monitoramento no contexto da empresa selecionada.