HCM — Recursos Humanos

O módulo HCM ("Human Capital Management") cobre o ciclo completo de gestão de pessoal: cadastro CLT/MEI, cálculo automático de folha (INSS/IRRF/FGTS 2026), ponto eletrônico, solicitações de férias/licença e o portal de autoatendimento do colaborador (ESS). Integra-se com o módulo Contábil via BullMQ para geração automática de lançamentos na aprovação da folha.

Visão Geral

Característica	Detalhe
Módulo backend	backend/src/hr/
Módulo eSocial	backend/src/esocial/
Portal ESS	backend/src/ess/
Permissão	Admin ou Superadmin (leitura: Staff nas rotas de ponto)
Rota principal	/t/:slug/admin/hr
Portal ESS	/t/:slug/ess

Schemas

Schema	Descrição	Arquivo
Employee	Funcionário CLT ou prestador MEI. PII (CPF, conta bancária, salário) criptografados com AES-256-GCM	schemas/employee.schema.ts
PayrollRun	Competência de folha de pagamento — draft → approved → paid	schemas/payroll-run.schema.ts
PayrollLine	Linha de folha por funcionário — proventos, descontos INSS/IRRF/VT, encargos patronais	schemas/payroll-line.schema.ts
Timesheet	Ponto diário (entrada/saída) — um registro por funcionário por dia	schemas/timesheet.schema.ts
LeaveRequest	Solicitação de férias/licença — pending → approved → rejected	schemas/leave-request.schema.ts
LeaveAccrual	Saldo acumulado de férias (acréscimo automático via cron mensal)	schemas/leave-accrual.schema.ts

Employee — campos principais

Campo	Tipo	Descrição
workerType	clt | mei	Regime de trabalho
cpfHash	string	SHA-256(cpf + tenantSalt) — índice único e lookup
cpfEncrypted	EncryptedField	CPF em AES-256-GCM (ver Security PII)
bankAccountEncrypted	EncryptedField	Dados bancários criptografados
baseSalaryCipher	EncryptedField	Salário-base em centavos, criptografado
baseSalaryCents	number	Salário bruto em centavos (campo legado — removido após migração PII)
pisNit	string	PIS/NIT — obrigatório para eSocial
cboCupation	string	CBO — obrigatório para eSocial
esocialCategory	string	Categoria eSocial (ex: 101 = empregado geral)
status	active | on_leave | terminated | inactive
lgpdRetentionExpiresAt	Date	Data a partir da qual o cron LGPD pode anonimizar (5 anos após demissão — CLT Art. 11)

PayrollRun — ciclo de vida

draft  ──→  approved  ──→  paid
              ↓
     JournalEntry gerada automaticamente
     (conta Folha a Pagar / Encargos Patronais)

O campo journalEntryId liga a folha aprovada ao lançamento contábil criado pelo PayrollAccountingBridge.

PayrollLine — estrutura de descontos

Campo	Descrição
baseCents	Salário-base do período
grossCents	Bruto = base + adicionais (additions[])
netCents	Líquido = bruto − descontos
deductions[]	Array: inss, irrf, vt, pensao, other
deductionsCipher	Mesmo array JSON-stringified + AES-256-GCM criptografado
inssPatronalCents	INSS patronal (20% geral / 0% Simples)
fgtsCents	FGTS (8% do bruto)
sistemaSCents	Sistema S — SENAI/SESC/SEBRAE (3,3% restaurantes)
ratFapCents	RAT base 1% × FAP

Serviços

Serviço	Responsabilidade	Arquivo
HrService	CRUD de Employee, LeaveRequest; termination (seta lgpdRetentionExpiresAt)	hr.service.ts
PayrollService	Geração de PayrollRun + PayrollLine; aprovação com bridge contábil	payroll.service.ts
TimesheetService	Clock-in/out; agregação mensal; correção administrativa	timesheet.service.ts
LeaveAccrualCron	Cron @Cron('0 1 1 * *') — adiciona dias de férias todo dia 1 do mês	leave-accrual.cron.ts

Tabelas Tributárias 2026

Arquivo: backend/src/hr/payroll-tables.ts

INSS Empregado 2026 (progressivo)

Faixa salarial (R$)	Alíquota
0,01 a 1.518,00	7,5%
1.518,01 a 2.793,00	9,0%
2.793,01 a 4.190,00	12,0%
4.190,01 a 7.786,02	14,0%
Acima de 7.786,02	Teto R$ 908,86

Modelo progressivo (destravado): cada faixa é calculada separadamente, não o salário todo na alíquota do topo.

IRRF 2026 (Lei 14.663/2023 + correção projetada)

Base de cálculo = bruto − INSS − dedução por dependente (R$ 235,47/dep.)

Base de cálculo (R$)	Alíquota	Parcela a deduzir
Até 2.824,00	Isento	—
2.824,01 a 3.751,05	7,5%	R$ 211,80
3.751,06 a 4.664,68	15%	R$ 492,97
4.664,69 a 5.831,95	22,5%	R$ 842,27
Acima de 5.831,95	27,5%	R$ 1.133,87

Encargos Patronais

Encargo	Taxa	Observação
INSS patronal	20%	Regime Geral; 0% no Simples Nacional (absorvido pelo DAS)
FGTS	8%	Sobre bruto CLT
Sistema S	3,3%	Restaurantes CNAE 56.11 (SENAI 1% + SESC 1,5% + SEBRAE 0,6% + outros 0,2%)
RAT/FAP	1% × FAP	Grau de Risco 1 para restaurantes; FAP padrão = 1,0
VT (desconto empregado)	6% do salário	Limitado ao custo real do VT

MEI — retenções

Retenção	Taxa
ISS municipal	3% (padrão)
CSLL (quando obrigatório)	1%

Endpoints

Funcionários

Método	Rota	Permissão	Descrição
GET	/t/:slug/admin/hr/employees	Admin	Listar (filtros: status, branchId, department)
POST	/t/:slug/admin/hr/employees	Admin	Cadastrar funcionário
GET	/t/:slug/admin/hr/employees/:id	Admin	Detalhe
PUT	/t/:slug/admin/hr/employees/:id	Admin	Atualizar
PATCH	/t/:slug/admin/hr/employees/:id/terminate	Admin	Demitir (define dismissalDate, dismissalReason, status = terminated, lgpdRetentionExpiresAt)

Folha de Pagamento

Método	Rota	Permissão	Descrição
GET	/t/:slug/admin/hr/payroll	Admin	Listar competências (filtros: year, status)
POST	/t/:slug/admin/hr/payroll/run	Admin	Gerar folha para período { month, year }
GET	/t/:slug/admin/hr/payroll/:id	Admin	Detalhe da folha
GET	/t/:slug/admin/hr/payroll/:id/lines	Admin	Linhas individuais por funcionário
POST	/t/:slug/admin/hr/payroll/:id/approve	Admin	Aprovar folha → gera JournalEntry via bridge

Ponto (Timesheet)

Método	Rota	Permissão	Descrição
GET	/t/:slug/admin/hr/timesheet	Admin	Listar registros
POST	/t/:slug/admin/hr/timesheet/clock-in	Admin/Staff	Bater ponto entrada
POST	/t/:slug/admin/hr/timesheet/clock-out	Admin/Staff	Bater ponto saída
GET	/t/:slug/admin/hr/timesheet/monthly/:employeeId	Admin	Agregado mensal (?month=&year=)
PATCH	/t/:slug/admin/hr/timesheet/:id/correct	Admin	Corrigir registro (intervalo, horas esperadas)

Férias e Licenças

Método	Rota	Permissão	Descrição
GET	/t/:slug/admin/hr/leaves	Admin	Listar (filtros: employeeId, status)
POST	/t/:slug/admin/hr/leaves	Admin/Staff	Criar solicitação
PATCH	/t/:slug/admin/hr/leaves/:id/status	Admin	Aprovar/rejeitar

Portal ESS (Employee Self-Service)

Rotas sob /t/:slug/ess/* — requerem autenticação do próprio funcionário.

Método	Rota	Descrição
GET	/t/:slug/ess/me	Perfil do funcionário logado
GET	/t/:slug/ess/timesheet/today	Registros de ponto do dia
POST	/t/:slug/ess/timesheet/clock-in	Bater entrada
POST	/t/:slug/ess/timesheet/clock-out	Bater saída
GET	/t/:slug/ess/payslips	Holerites (PayrollLine) do funcionário
GET	/t/:slug/ess/leaves	Solicitações de férias/licença do funcionário
POST	/t/:slug/ess/leaves	Abrir nova solicitação

Bridge Folha → Contabilidade (BullMQ)

Quando PayrollService.approvePayrollRun() é chamado, publica um job na fila accounting-queue:

PayrollService.approvePayrollRun()
        ↓
  accounting-queue (BullMQ/Redis)
        ↓
AccountingAutomationService.processPayroll()
        ↓
  JournalEntry:
    Débito  — 5.1.X Folha de Salários
    Débito  — 5.1.X Encargos Patronais (FGTS, INSS)
    Crédito — 2.1.X Salários a Pagar
    Crédito — 2.1.X FGTS a Recolher

O hook é fire-and-forget com @Optional() — o módulo HR funciona mesmo sem Redis configurado.

Componentes Frontend

View	Rota admin	Descrição
EmployeesView	/admin/hr/employees	Lista e cadastro de funcionários
PayrollRunView	/admin/hr/payroll	Gerar, visualizar e aprovar folhas
TimesheetAdminView	/admin/hr/timesheet	Ponto administrativo e correções
LeaveApprovalView	/admin/hr/leaves	Aprovar/rejeitar solicitações
EssHomeView	/t/:slug/ess	Portal ESS — dashboard do funcionário
EssPontoView	/t/:slug/ess/ponto	Clock-in / clock-out self-service
EssHolritesView	/t/:slug/ess/holrites	Holerites do funcionário
EssFeriasView	/t/:slug/ess/ferias	Solicitar e acompanhar férias

Relacionados

• eSocial — Eventos XML (S-2200/S-1200/S-2299) gerados a partir de Employee + PayrollRun
• LGPD — RH — Exportar e anonimizar PII de funcionários
• Security PII — Criptografia AES-256-GCM dos campos sensíveis
• Contabilidade — Bridge folha → lançamento contábil