Referência técnica de Pessoas

Domínios Hr e Payroll da pepper-api; telas em pepper-front/src/app/hr. Todas as rotas exigem x-access-token e o header requesting; o business é o ProfileBusiness.

Entidades

Coleção	Campos principais
Employee	dados pessoais, collaborator?, contractType, admissionDate, terminationDate, status, dependents, benefits[], terms[], termLog[]; position, jobTitle, department, weeklyHours, workDays, dailyHours e baseSalary espelham o termo vigente hoje
Employee.terms[]	effectiveDate, reason (admission, promotion, hoursChange, raise, collectiveAgreement, positionRevision, correction, other), position, positionRevision, jobTitle, department, weeklyHours, workDays, dailyHours, baseSalary, note, recordedAt, recordedBy
Employee.termLog[]	at (quando foi registrado), from (desde quando vale), action. Uma folha fechada antes de at e com competência ≥ from é revista para o retroativo.
Position	title, department, cbo, contractType, roleType? (papel do app), active, revisions[] { effectiveDate, weeklyHours, workDays, dailyHours, salary, reason, note }
Benefit	type, name, provider, employerCost {mode, value}, employeeDiscount {mode, value, cap}, active
Vacation	employee, período aquisitivo, startDate, endDate, days, soldDays, status, paymentDueDate, amounts
Payroll	competence, status (draft/closed), items[] (linha do motor, segments[], weeklyHours, additions[].retro {competence, payroll}), totals, fiscal
PayrollProvision	employee, competence, thirteenth, vacation, vacationThird, charges, total

Fichas anteriores à linha do tempo não têm terms. A linha do tempo é montada em memória a partir do salaryHistory, e os termos são gravados na primeira alteração, sem migração.

Rotas

Método e rota	Uso
GET/POST /hr/employees, GET/PUT /hr/employees/:id	Fichas. A edição de cargo, jornada ou salário vira um termo (compatibilidade).
POST /hr/employees/:id/terms/preview · POST /terms	Prévia e registro de alteração; syncRole alinha o papel do app
PUT · DELETE /hr/employees/:id/terms/:termId	Corrigir ou remover (?preview=true só calcula)
GET/POST /hr/positions, GET/PUT /hr/positions/:id	Cargos
POST /hr/positions/:id/revisions	Revisão com salaryMode (position/proportional/keep), employees, syncRoles, ?preview=true
POST /hr/positions/:id/sync-roles	Alinhar o papel do app dos ocupantes
GET /hr/integrations/collaborators · /roles	Integração opcional (available)
GET/POST/PUT /hr/benefits	Catálogo
GET /hr/vacations, /vacations/alerts, POST /vacations/preview, POST /vacations, PUT /:id/approve, /cancel	Férias
GET/POST /payroll, POST /payroll/preview, GET /payroll/:id, PUT /:id/recalculate, /items/:employeeId, /close, /reopen	Folha
POST /payroll/thirteenth · GET /payroll/provisions	13º e provisões

Motor

• utils/labor/terms.js:
  • timeline e termsAt;
  • monthlyHours (horas semanais × 5) e hourlyRate;
  • proportionalSalary;
  • minimumFor (mínimo × horas/44);
  • checkTerm (avisos).
• Payroll/build.js:
  • segmentsIn: trechos do mês por termo, em base 30;
  • buildItem: linha da folha;
  • totals e fifthBusinessDay.
• Payroll/retroactive.js:
  • pendingFor: diferenças a pagar na folha em rascunho;
  • impactOf: prévia antes e depois por competência.
• utils/labor/calc.js: INSS, IRRF (com o redutor de 2026), encargos, férias, 13º, provisão e benefícios.

Permissões

• RBAC: recursos Hr e Payroll.
• ProfileBusiness e ProfileAdmin: acesso total à própria empresa.
• ProfileCollaborator: só com papel Admin e na própria empresa. A policy usa isAdminCollaborator.
• Integrações (Hr/integrations/collaborators.js, roles.js): desligam-se sozinhas sem ProfileCollaborator, RoleType ou RoleCollaborator.