Flujo de liquidación de nómina (Nomina Modular)

1) Objetivo del flujo

Estandarizar el orden de operación para liquidar nómina por periodo (mensual o quincenal), asegurando que el sistema use los insumos correctos (empresa, empleados, turnos, novedades, incapacidades, préstamos) y genere resultados persistidos y trazables.

2) Pre-requisitos (antes de liquidar)

1. Empresa configurada
2. SMMLV, auxilio de transporte, periodicidad de pago, datos generales.
3. Estructura organizacional
4. Cargos y asignación de cargo al empleado.
5. Turnos/configuración (administrativo vs rotativo) y divisor de horas.
6. Empleados completos
7. Salario base, horas diarias, fecha de ingreso, afiliaciones, etc.
8. Insumos del periodo
9. Novedades (horas extra, dominicales, variables, viáticos, ausentismos).
10. Turnos (para rotativos, con desglose JSON).
11. Incapacidades (si aplica).
12. Préstamos (si aplica).

3) Flujo recomendado (operativo) – Nómina del periodo

Paso A — Preparar el periodo

1. Definir el periodo a liquidar
2. Mensual: YYYY-MM-mensual
3. Quincenal: YYYY-MM-quincena1 o YYYY-MM-quincena2
4. Validar compatibilidad mensual vs quincenal para el mes
5. No se permite liquidar mensual si ya existen quincenas del mismo mes.
6. No se permite liquidar quincenas si ya existe mensual del mismo mes.

Paso B — Cargar insumos por empleado

Por cada empleado:

1. Leer configuración de sueldo/cargo/turno del empleado (divisor horas, si es rotativo).
2. Cargar novedades del periodo:
3. Opción 1: parámetros simples (tabla novedades_nomina).
4. Opción 2: novedades detalladas (tabla novedades_nomina_detalle) y su agregación al formato simple para compatibilidad.
5. Cargar turnos del rango del periodo (si es rotativo).
6. Cargar incapacidades que crucen el rango del periodo.
7. Cargar préstamos activos.

Paso C — Calcular

1. Calcular salario del periodo, horas/recargos (según aplique) y devengados.
2. Calcular IBC (piso/techo proporcional al periodo).
3. Calcular deducciones de ley y descuentos (incluye préstamos con límite 50%).
4. Calcular prestaciones (cesantías, intereses, prima, vacaciones) como acumulados del periodo.

Paso D — Persistir resultados y auditoría

1. Eliminar nómina existente del empleado para ese periodo (si existía).
2. Insertar el resultado calculado en nominas.
3. Registrar auditoría de la operación (usuario, empleado, periodo).

Paso E — Revisar y cerrar

1. Revisar totales (devengado, deducción, neto) por empleado.
2. Generar reportes/exportaciones según necesidad (PDF/Excel en módulos que lo soportan).

4) Flujo real implementado (referencias de código)

Nómina del periodo (pantalla “Nómina”)

• UI y orquestación: gestion_nomina.py
• Construye el periodo.
• Valida compatibilidad mensual/quincenal contra la tabla nominas.
• Carga insumos (novedades simples, turnos para recargos/HE, incapacidades).
• Calcula por empleado y persiste resultados.
• Motor de cálculo: NominaController.calcular_nomina_empleado
• Calcula salario, devengados, IBC, deducciones, neto, prestaciones y serializa detalles_json.
• Persistencia: database.py
• nominas, novedades_nomina, novedades_turnos, incapacidades, prestamos, auditoria.

Liquidación masiva (pantalla “Liq. Nómina”)

• UI: liquidacion_masiva.py
• “Generar Liquidación Automática” crea una previsualización (no inserta en nominas).
• “Guardar Borrador” persiste en liquidaciones + liquidacion_detalle.
• “Confirmar Liquidación” marca estado como completada.

Liquidación de contrato (pantalla “Liq. Contrato”)

• Cálculo: NominaController.calcular_liquidacion_contrato
• Calcula prestaciones finales a fecha de retiro.

5) Checklist de verificación (para validar que se sigue el flujo)

Antes de liquidar:

• Empresa existe y tiene SMMLV/auxilio/periodicidad configurados.
• Empleados tienen cargo/sueldo/horas diarias y turno definido.
• Novedades registradas para el periodo (simples o detalladas).
• Incapacidades registradas con fechas correctas.
• Turnos rotativos cargados (si aplica) dentro del rango del periodo.

Durante la liquidación:

• No hay choque mensual vs quincenal (validación activa).
• Para cada empleado se recalcula y se guarda un único registro de nómina por periodo.
• Los resultados incluyen detalles_json con devengados/deducciones/IBC/prestaciones.
• Se registra auditoría de cálculo.

Después de liquidar:

• La tabla nominas tiene los registros esperados del periodo.
• Los totales por empleado (devengado/deducción/neto) son coherentes.
• Las liquidaciones masivas, si se usan, quedan en estado borrador o completada según el flujo.

6) Revisión de consistencia del sistema vs flujo (hallazgos y ajustes)

Se revisó el flujo real contra el flujo recomendado y se ajustaron puntos que impedían seguirlo correctamente:

1. Fecha de pago en quincena 2
2. Ajuste: se calcula con el último día real del mes (incluye meses de 31 días y febrero).
3. Código: NominaController.calcular_periodo_info
4. Periodicidad usada en validación de jornada
5. Ajuste: la validación usa la periodicidad derivada del periodo (mensual/quincenal), evitando inconsistencias cuando el usuario liquida un tipo distinto al configurado en empresa.
6. Código: NominaController.calcular_nomina_empleado
7. Días del periodo calculados por rango real
8. Ajuste: el número de días del periodo se calcula como diferencia real entre fechas; evita sub/sobre liquidación en quincena 2 (meses de 28/29/31 días).
9. Código: NominaController.calcular_nomina_empleado
10. Ausentismos aplicados a la liquidación
11. Ajuste: los “Ausentismos (horas)” reducen el salario del periodo (impactando devengado e IBC).
12. Código: NominaController.calcular_nomina_empleado
13. Consistencia de estado en liquidaciones masivas
14. Ajuste: el bloqueo mensual/quincenal en “Liq. Nómina” ahora usa estado='completada' (consistente con el resto del módulo).
15. Código: liquidacion_masiva.py