Documentación del Módulo de Recursos Humanos (RRHH)
Versión: 2.0
Fecha: 2026-01-12
1. Resumen Ejecutivo
El módulo de Recursos Humanos (RRHH) es el componente central para la gestión del capital humano de la organización. Su propósito es automatizar y centralizar todo el ciclo de vida del colaborador, desde su incorporación hasta su cese, garantizando el cumplimiento normativo legal, la exactitud en el cálculo de nóminas y la integración fluida con la contabilidad financiera.
Valor para el Negocio:
- Eficiencia Operativa: Automatización del cálculo de planillas, reduciendo errores manuales y tiempo de procesamiento.
- Cumplimiento Normativo: Gestión de conceptos de ley (AFP, ONP, EsSalud, 5ta Categoría) y generación de archivos para entidades bancarias y PLAME.
- Integridad Financiera: Generación automática de asientos contables de provisión y gasto, asegurando que la información de RRHH cuadre perfectamente con Contabilidad.
- Control de Asistencia y Permisos: Gestión centralizada de vacaciones y ausencias con impacto directo y automático en el cálculo de nómina.
- Gestión de Saldos de Vacaciones: Control automático del devengue, uso y vencimiento de días de vacación según ley peruana.
2. Arquitectura del Módulo
2.1. Componentes Principales
graph TB
subgraph "Gestión de Empleados"
EMP[Employee]
EC[EmploymentContract]
EBA[EmployeeBankAccount]
ES[EmployeeSchedule]
end
subgraph "Nómina"
PS[PayrollSetting]
PC[PayrollConcept]
PP[PayrollPeriod]
PM[PayrollMovement]
PR[PayrollRun]
PRI[PayrollRunItem]
PRIC[PayrollRunItemConcept]
end
subgraph "Ausencias y Asistencia"
LT[LeaveType]
LR[LeaveRequest]
AR[AttendanceRecord]
VB[VacationBalance]
VM[VacationMovement]
HOL[Holiday]
end
subgraph "Catálogos"
JP[JobPosition]
AR2[Area]
SCH[Schedule]
PS2[PensionSystem]
HI[HealthInsurance]
end
EMP --> EC
EMP --> EBA
EMP --> LR
EMP --> AR
EMP --> VB
EC --> ES
EC --> PRI
PP --> PR
PR --> PRI
PRI --> PRIC
PC --> PRIC
LT --> LR
LR --> VB
3. Flujos del Proceso
3.1. Gestión del Ciclo de Vida del Empleado
graph TD
A[Candidato Seleccionado] -->|Registro| B(Crear Ficha Empleado)
B --> C{Tiene Contrato?}
C -->|No| D[Crear Contrato Laboral]
C -->|Sí| E[Validar Activo]
D --> F[Estado: ACTIVO]
F --> G{Evento Laboral}
G -->|Vacaciones| H[Solicitud Permiso]
G -->|Asistencia| I[Registro Diario]
G -->|Renovación| J[Nuevo Contrato]
G -->|Renuncia/Despido| K[Finalizar Contrato]
K --> L[Cálculo Liquidación]
L --> M[Estado: CESADO]
3.2. Flujo de Nómina (PayrollRun)
stateDiagram-v2
[*] --> BORRADOR
BORRADOR --> CALCULANDO: Iniciar Cálculo
CALCULANDO --> BORRADOR: Error / Reintentar
CALCULANDO --> EN_REVISION: Cálculo Exitoso
EN_REVISION --> APROBADO: Visto Bueno Gerencia
EN_REVISION --> BORRADOR: Rechazar / Corregir
APROBADO --> PROCESADO: Generar TXT Banco
PROCESADO --> PUBLICADO: Boletas Disponibles
APROBADO --> ANULADO: Anular Proceso
PROCESADO --> ANULADO: Anular Proceso
BORRADOR --> ANULADO: Anular Proceso
note right of PROCESADO
Genera Asiento Contable
y Archivos de Pago
end note
note right of PUBLICADO
Estado final: boletas
visibles para empleados
end note
Estados de PayrollRun:
| Estado | Valor | Descripción | Acciones Permitidas |
|---|---|---|---|
| BORRADOR | borrador |
Estado inicial, en edición | Calcular, Anular |
| CALCULANDO | calculando |
Procesando cálculo automático | Esperar resultado |
| EN_REVISION | en_revision |
Listo para revisión gerencial | Aprobar, Rechazar, Anular |
| APROBADO | aprobado |
Aprobado, listo para pago | Procesar, Anular |
| PROCESADO | procesado |
Archivos de pago generados | Publicar, Anular |
| PUBLICADO | publicado |
Boletas disponibles para empleados | - (Estado final) |
| ANULADO | anulado |
Proceso cancelado | - (Estado final) |
3.3. Flujo de Periodo de Nómina (PayrollPeriod)
stateDiagram-v2
[*] --> BORRADOR
BORRADOR --> LISTO: Validar Configuración
LISTO --> PROCESANDO: Iniciar Runs
LISTO --> BORRADOR: Revertir
PROCESANDO --> CERRADO: Todos los Runs Completados
PROCESANDO --> LISTO: Revertir
CERRADO --> PROCESANDO: Reabrir (si permitido)
Estados de PayrollPeriod:
| Estado | Valor | Descripción |
|---|---|---|
| BORRADOR | borrador |
Periodo en configuración |
| LISTO | listo |
Listo para procesar nóminas |
| PROCESANDO | procesando |
Runs de nómina en ejecución |
| CERRADO | cerrado |
Periodo cerrado, inmutable |
3.4. Flujo de Solicitudes de Permiso (LeaveRequest)
stateDiagram-v2
[*] --> PENDIENTE
PENDIENTE --> APROBADO: Aprobar
PENDIENTE --> RECHAZADO: Rechazar
PENDIENTE --> CANCELADO: Cancelar
APROBADO --> EN_PROGRESO: Inicia el Periodo
APROBADO --> CANCELADO: Cancelar
EN_PROGRESO --> COMPLETADO: Termina el Periodo
EN_PROGRESO --> CANCELADO: Cancelar
Estados de LeaveRequest:
| Estado | Valor | Afecta Nómina | Editable |
|---|---|---|---|
| PENDIENTE | pendiente |
No | Sí |
| APROBADO | aprobado |
Sí | No |
| RECHAZADO | rechazado |
No | No |
| CANCELADO | cancelado |
No | No |
| EN_PROGRESO | en_progreso |
Sí | No |
| COMPLETADO | completado |
Sí | No |
4. Lógica de Negocio y Reglas
4.1. Reglas de Contratación
- Unicidad de Contrato: Un empleado solo puede tener un contrato activo a la vez.
- Sin Superposición de Fechas: Los contratos del mismo empleado no pueden tener fechas superpuestas.
- Validación Bancaria: Para pagos bancarios, la cuenta debe ser válida y estar a nombre del empleado.
- Sistema de Pensiones: Todo contrato debe tener un sistema de pensiones asignado (AFP u ONP).
4.2. Reglas de Nómina
- Inmutabilidad: Items y montos son inmodificables en estado
APROBADOo superior. - Unicidad de Run por Periodo/Sucursal: Solo puede existir un PayrollRun activo por periodo y sucursal.
- Configuración Obligatoria: Un PayrollRun requiere un
PayrollSettingactivo para la sucursal. - Cálculo Automático:
- Tardanzas:
(Sueldo / 30 / 8 / 60) * MinutosTardanza - Asignación Familiar: Automática según configuración de
PayrollSetting - AFP/ONP: Calculado según tasas de
PensionFundRate - EsSalud: 9% del sueldo bruto (aporte empleador)
- Renta 5ta: Según escala UIT vigente
- Tardanzas:
4.3. Reglas de Vacaciones
- Devengue Proporcional: 2.5 días por mes trabajado (30 días / 12 meses).
- Vencimiento: Los días de vacaciones vencen 18 meses después de devengados (ley peruana).
- Saldo Negativo: No se permite saldo de vacaciones negativo sin autorización especial.
- Días Hábiles: Las vacaciones se calculan excluyendo feriados y fines de semana.
4.4. Reglas de Asistencia
- Único por Día: Solo puede existir un registro de asistencia por empleado por día.
- Consistencia de Horas: La hora de salida debe ser posterior a la hora de entrada.
- Contrato Activo: El empleado debe tener un contrato activo para registrar asistencia.
- Justificación: Las tardanzas pueden justificarse con documento de soporte.
5. Modelo de Datos Detallado
5.1. Entidades Principales
| Entidad | Descripción | Atributos Clave |
|---|---|---|
| Employee | Datos personales e identidad | n_doc, cuspp, names, paternal_surname, birthdate, email, user_id |
| EmploymentContract | Condiciones laborales | contract_code, base_salary, is_active, start_date, end_date, payment_method, work_modality |
| EmployeeBankAccount | Cuentas bancarias del empleado | bank_id, account_number, cci, account_type, is_primary |
| EmployeeSchedule | Asignación de horarios | employee_id, contract_id, schedule_id, valid_from, valid_until |
5.2. Entidades de Nómina
| Entidad | Descripción | Atributos Clave |
|---|---|---|
| PayrollSetting | Configuración global de nómina | branch_id, minimum_wage, uit_value, essalud_rate, family_allowance_amount, status |
| PayrollConcept | Definición de Haberes/Descuentos | code, type (Ingreso/Descuento/Aporte), category, is_taxable, affects_essalud, debit_account_id, credit_account_id |
| PayrollPeriod | Periodo fiscal (Mes/Año) | period_code, month, year, start_date, end_date, status |
| PayrollMovement | Incidencia económica variable | employee_id, concept_id, period_id, amount, source |
| PayrollRun | Proceso de cálculo | period_id, branch_id, status, total_gross_pay, total_deductions, total_net_pay, journal_entry_id |
| PayrollRunItem | Línea de boleta por empleado | payroll_run_id, employee_id, contract_id, gross_pay, total_income, total_deductions, net_pay |
| PayrollRunItemConcept | Detalle de concepto por item | payroll_run_item_id, concept_id, amount, quantity, is_manual |
5.3. Entidades de Ausencias y Asistencia
| Entidad | Descripción | Atributos Clave |
|---|---|---|
| LeaveType | Tipos de permiso | code, name, category, is_paid, requires_attachment, max_days_per_year, affects_vacation_balance |
| LeaveRequest | Solicitud de ausencia | employee_id, leave_type_id, start_date, end_date, total_days, work_days, status, approved_by |
| AttendanceRecord | Marcación diaria | employee_id, work_date, check_in_time, check_out_time, worked_minutes, late_minutes, extra_minutes, status |
| VacationBalance | Saldo de vacaciones anual | employee_id, contract_id, period_year, entitled_days, used_days, available_days, expiry_date |
| VacationMovement | Movimiento de vacaciones | vacation_balance_id, movement_type, days, reason |
| Holiday | Feriados | date, name, type, is_recurring, branch_id |
5.4. Catálogos
| Entidad | Descripción | Atributos Clave |
|---|---|---|
| Schedule | Horarios base | name, start_time, end_time, break_minutes, is_active |
| JobPosition | Cargos | name, description, is_active |
| Area | Áreas/Departamentos | name, code, is_active |
| PensionSystem | Sistemas de pensiones (AFP/ONP) | code, name, type, commission_rate |
| HealthInsurance | EPS/Seguros de salud | name, code, is_active |
6. Casos de Uso
6.1. Gestión de Personal
- CU-01: Registro de Nuevo Empleado: Creación de ficha con datos personales, documentos y fotografía.
- CU-02: Creación de Contrato: Definición de condiciones laborales, cuenta bancaria, sistema de pensiones.
- CU-03: Renovación de Contrato: Cierre de contrato anterior y creación de nuevo contrato.
- CU-04: Cese de Empleado: Finalización de contrato con cálculo de liquidación de beneficios.
6.2. Gestión de Tiempo
- CU-05: Registro de Asistencia: Marcación manual o por QR con cálculo automático de tardanzas.
- CU-06: Justificación de Tardanza: Registro de motivo y documento de soporte.
- CU-07: Solicitud de Vacaciones: Creación, aprobación y descuento automático de saldo.
- CU-08: Solicitud de Permiso: Creación de permisos médicos, personales, etc.
6.3. Nómina
- CU-09: Configuración de PayrollSetting: Definición de parámetros como RMV, UIT, tasas.
- CU-10: Apertura de Periodo: Creación del periodo mensual con fechas de cálculo.
- CU-11: Registro de Movimientos: Ingreso de bonos, descuentos, adelantos variables.
- CU-12: Procesamiento de Nómina: Cálculo automático de boletas para todos los empleados.
- CU-13: Aprobación y Pago: Revisión gerencial, generación de archivos de pago bancario.
- CU-14: Publicación de Boletas: Disponibilidad de boletas para empleados.
7. Guía de Configuración
7.1. Configuración de Nómina (PayrollSetting)
Antes de procesar nóminas, debe existir un PayrollSetting APROBADO para la sucursal.
Campos de Configuración:
| Campo | Descripción | Ejemplo |
|---|---|---|
minimum_wage |
Remuneración Mínima Vital (RMV) | 1025.00 |
uit_value |
Unidad Impositiva Tributaria | 5150.00 |
essalud_rate |
Porcentaje EsSalud empleador | 9.00% |
family_allowance_amount |
Monto asignación familiar | 102.50 |
fifth_category_exempt_uits |
UITs exentas de 5ta categoría | 7 |
overtime_rate_25 |
Tasa hora extra 25% | 1.25 |
overtime_rate_35 |
Tasa hora extra 35% | 1.35 |
Estados del PayrollSetting:
| Estado | Descripción |
|---|---|
borrador |
En edición, puede modificarse |
pendiente |
Enviado para aprobación |
aprobado |
Activo, se usa para cálculos |
rechazado |
No aprobado, requiere correcciones |
expirado |
Vencido, no se usa |
7.2. Conceptos de Nómina (PayrollConcept)
Define los rubros que aparecerán en la boleta.
Tipos de Concepto:
| Tipo | Código | Descripción |
|---|---|---|
| Ingreso | ingreso |
Suma al bruto (sueldos, bonos) |
| Descuento | descuento |
Resta del bruto (AFP, impuestos) |
| Aporte | aporte |
Aporte empleador (EsSalud, CTS) |
Categorías:
| Categoría | Descripción |
|---|---|
remuneracion_basica |
Sueldo base |
asignaciones |
Asignación familiar, movilidad |
bonificaciones |
Bonos, gratificaciones |
descuentos_legales |
AFP, ONP, 5ta categoría |
aportes_empleador |
EsSalud, CTS |
adelantos |
Adelantos de sueldo |
otros_ingresos |
Otros ingresos variables |
otros_descuentos |
Otros descuentos |
Configuración Contable:
- Cuenta Débito: Generalmente cuentas de Gasto (Clase 6) para ingresos del trabajador.
- Cuenta Crédito: Cuentas de Pasivo (Clase 4) para obligaciones por pagar.
- Afectaciones: Marcar
is_taxable(Renta 5ta),affects_essalud(9%).
7.3. Tipos de Permiso (LeaveType)
Categorías de Permiso:
| Categoría | Código | Descripción | Afecta Vacaciones |
|---|---|---|---|
vacation |
Vacaciones | Descanso vacacional anual | Sí |
medical |
Médico | Descanso médico con certificado | No |
personal |
Personal | Permiso personal sin goce | No |
maternity |
Maternidad | Licencia pre y post natal | No |
paternity |
Paternidad | Licencia por nacimiento | No |
bereavement |
Duelo | Fallecimiento de familiar | No |
other |
Otro | Otros permisos | Configurable |
Límites según Ley Peruana:
- Vacaciones: 30 días por año
- Licencia por Paternidad: 10 días
- Licencia por Fallecimiento: 3 días (familiar directo)
7.4. Feriados (Holiday)
Registrar los días no laborables del año. Afecta directamente al cálculo de días hábiles para vacaciones y la expectativa de asistencia.
Tipos de Feriado:
| Tipo | Descripción |
|---|---|
nacional |
Feriado nacional (aplica a todas las sucursales) |
regional |
Feriado regional (aplica a una región) |
local |
Feriado local (aplica a una sucursal) |
8. Eventos del Sistema
El módulo emite eventos que pueden ser escuchados para integraciones o notificaciones.
8.1. Eventos de Nómina
| Evento | Descripción | Payload |
|---|---|---|
PayrollRunStatusChanged |
Cambio de estado de PayrollRun | payrollRun, previousStatus, newStatus |
PayrollPeriodStatusChanged |
Cambio de estado de Periodo | payrollPeriod, previousStatus, newStatus |
PayrollPeriodReady |
Periodo listo para procesar | payrollPeriod |
PayrollPeriodClosed |
Periodo cerrado | payrollPeriod |
8.2. Eventos de Configuración
| Evento | Descripción |
|---|---|
PayrollSettingSubmitted |
Configuración enviada para aprobación |
PayrollSettingApproved |
Configuración aprobada |
PayrollSettingRejected |
Configuración rechazada |
PayrollSettingStatusChanged |
Cambio de estado general |
8.3. Eventos de Permisos
| Evento | Descripción |
|---|---|
LeaveRequestCreated |
Nueva solicitud creada |
LeaveRequestApproved |
Solicitud aprobada |
LeaveRequestRejected |
Solicitud rechazada |
LeaveRequestStatusChanged |
Cambio de estado general |
9. Matriz de Roles y Permisos (RBAC)
| Recurso | Super-Admin / Admin | RRHH Manager | Empleado (Portal) |
|---|---|---|---|
| Empleados | Total | Total | Ver Propio Perfil |
| Contratos | Total | Total | Ver Propio |
| Cuentas Bancarias | Total | Total | Ver Propias |
| Nómina (Run) | Total + Aprobar | Crear/Editar | Solo Ver Boletas |
| Movimientos | Total | Total | Ver Propios |
| PayrollSetting | Total + Aprobar | Crear/Editar | - |
| Asistencia | Total | Total | Marcar/Ver Propia |
| Vacaciones | Aprobar/Rechazar | Aprobar/Rechazar | Solicitar |
| Saldo Vacaciones | Total | Total | Ver Propio |
| Configuración | Total | Ver | - |
Permisos Especiales:
restore.recursos-humanos.*: Restaurar registros eliminados (Papelera).force_delete.*: Eliminación definitiva (Solo Super-Admin).approve_payroll_setting: Aprobar configuraciones de nómina.approve_payroll_run: Aprobar procesos de nómina.
10. Reportes y Exportación
10.1. Exportadores Disponibles
| Exportador | Recurso | Descripción |
|---|---|---|
AttendanceRecordExporter |
Asistencia | Tiempos, tardanzas y horas extra |
EmployeeExporter |
Empleados | Datos filiatorios y de contacto |
EmployeeBankAccountExporter |
Cuentas Bancarias | Cuentas de empleados |
EmployeeScheduleExporter |
Horarios | Asignaciones de horario |
EmploymentContractExporter |
Contratos | Condiciones laborales históricas |
PayrollConceptExporter |
Conceptos | Catálogo de conceptos configurados |
PayrollPeriodExporter |
Periodos | Estado de las nóminas procesadas |
PayrollSettingExporter |
Configuración | Parámetros de nómina |
ScheduleExporter |
Horarios Base | Catálogo de horarios |
JobPositionExporter |
Cargos | Catálogo de posiciones |
PensionSystemExporter |
AFP/ONP | Sistemas de pensiones |
HealthInsuranceExporter |
Seguros | EPS y seguros de salud |
Acceso: Botón "Exportar" en la cabecera de las tablas correspondientes.
10.2. Widgets del Dashboard
| Widget | Descripción |
|---|---|
HumanResourcesStatsWidget |
Estadísticas generales de RRHH |
ContractsExpiringWidget |
Contratos próximos a vencer |
PendingLeaveRequestsWidget |
Solicitudes de permiso pendientes |
RecentPayrollRunsWidget |
Últimos procesos de nómina |
11. Servicios
11.1. PayrollCalculationService
Servicio para cálculos especiales de nómina.
Métodos:
| Método | Descripción | Parámetros |
|---|---|---|
calculateTerminationPayment() |
Calcula liquidación de beneficios sociales | contract, terminationDate |
generateLastPaySlip() |
Genera última boleta con proporcional | contract, periodStart, periodEnd |
Cálculos de Liquidación:
- Vacaciones Truncas: Días devengados no gozados.
- Gratificación Trunca: Proporcional de julio/diciembre.
- CTS: Compensación por tiempo de servicios.
12. Solución de Problemas (Troubleshooting)
Error: "No se puede eliminar este movimiento porque ya fue aprobado"
- Causa: Intentas borrar un
PayrollMovementque ya está vinculado a un cálculo cerrado. - Solución: Debes anular primero el
PayrollRunasociado o solicitar al aprobador que revierta el estado.
Error: "Ya existe un contrato activo para este empleado"
- Causa: Se intenta crear un contrato nuevo sin cerrar el anterior.
- Solución: Edita el contrato actual y define una
Fecha Fin.
Error: "Saldo de vacaciones insuficiente"
- Causa: La solicitud excede los días disponibles.
- Solución: Verificar el reporte de
VacationBalance. Si es un "Adelanto", requerirá autorización especial manual.
Error: "No se puede editar, el proceso está APROBADO"
- Causa: Integridad de datos bloquea cambios en nóminas cerradas.
- Solución: Utiliza la acción "Retornar a Borrador" (si tienes permisos) o "Anular" si el proceso debe rehacerse desde cero.
Error: "No existe configuración de nómina activa para esta sucursal"
- Causa: No hay un
PayrollSettingen estadoaprobadopara la sucursal. - Solución: Crear y aprobar un
PayrollSettingantes de procesar nóminas.
Error: "Las fechas del contrato se superponen con otro contrato"
- Causa: El empleado ya tiene un contrato que cubre las fechas indicadas.
- Solución: Ajustar las fechas del nuevo contrato o cerrar el contrato anterior.
Error: "El tipo de permiso requiere documento adjunto"
- Causa: El
LeaveTypetienerequires_attachment = true. - Solución: Adjuntar el documento requerido (ej: certificado médico).
Error: "El máximo de días consecutivos permitidos es X"
- Causa: La solicitud excede el límite
max_consecutive_daysdel tipo de permiso. - Solución: Dividir la solicitud en periodos más cortos o solicitar autorización especial.
13. Integraciones
13.1. Integración con Contabilidad
El módulo genera automáticamente asientos contables al procesar nóminas:
- Asiento de Provisión: Al aprobar el PayrollRun.
- Asiento de Gasto: Al procesar el pago.
Los conceptos deben tener configuradas las cuentas debit_account_id y credit_account_id.
13.2. Archivo de Pago Bancario
Al procesar un PayrollRun, se genera un archivo TXT con el formato del banco configurado para depósito masivo de haberes.
13.3. PLAME / T-REGISTRO
El sistema permite exportar información para:
- Declaración mensual de PDT PLAME.
- Registro de trabajadores en T-REGISTRO.
14. Anexos
14.1. Enums del Módulo
| Enum | Valores |
|---|---|
PayrollRunStatus |
borrador, calculando, en_revision, aprobado, procesado, publicado, anulado |
PayrollPeriodStatus |
borrador, listo, procesando, cerrado |
LeaveRequestStatus |
pendiente, aprobado, rechazado, cancelado, en_progreso, completado |
PayrollSettingStatus |
borrador, pendiente, aprobado, rechazado, expirado |
PayrollConceptType |
ingreso, descuento, aporte |
PayrollConceptCategory |
remuneracion_basica, asignaciones, bonificaciones, descuentos_legales, etc. |
LeaveTypeCategory |
vacation, medical, personal, maternity, paternity, bereavement, other |
AttendanceStatus |
presente, ausente, tardanza, falta_justificada, permiso |
AttendanceSource |
manual, qr, biometrico, importacion |
ContractType |
indefinido, plazo_fijo, tiempo_parcial, formativo |
PaymentMethod |
deposito_bancario, efectivo, cheque |
PaymentFrequency |
mensual, quincenal, semanal |
WorkModality |
presencial, remoto, hibrido |
VacationMovementType |
accrual, usage, adjustment, carryover, expiry |
Documentación generada automáticamente el 2026-01-12. Versión 2.0.