Payroll en Sevastopol

Propósito

PayrollViewIsland opera el cálculo mensual de remuneraciones del tenant. Es el único punto donde el dominio remuneraciones produce liquidaciones persistentes, asientos contables y documentos legales (PDF de liquidación).

El motor matemático vive en PayrollService y PayrollEngine del Orchestrator — la island sólo coordina UI, parametriza overrides y dispara los pasos preview / generar / contabilizar / pdf.

Decisiones de UX

Decisión	Motivo
Preview obligatorio antes de generar	POST /preview ejecuta el motor sin escribir. El operador valida líquido, descuentos y aportes; al aprobar, POST /generar con force: true persiste reusando los _used_overrides que la simulación calculó.
Override automático de dias_trabajados por finiquito	Si el empleado tiene fecha_egreso dentro del periodo, la island ajusta días automáticamente (0 si terminó antes; eD − iD + 1 si ingresó y terminó en el mismo mes) y avisa con toast. Evita liquidar mes completo a quien ya no es trabajador del tenant.
Sin clamp a 30 días	El cálculo de días por término usa el día calendario del egreso, no un proxy de 30. Documentado explícitamente en código a pedido del usuario.
Cambio de estado vía modal	PATCH /:id/status con select del estado destino (BORRADOR → APROBADA → CONTABILIZADA). Forzar el modal evita cambios accidentales.
Descarga de PDF como blob	GET /:id/pdf se descarga como blob y se sirve al usuario con download attribute. El filename se toma del Content-Disposition cuando viene.
Eliminar con force: true	El borrado del backend exige force=true cuando hay asiento — la UI confirma con confirm nativo.
Filtros locales sobre 2000 registros	El backend devuelve hasta 2000 liquidaciones; los filtros (estado, texto sobre empleado) se aplican en cliente.
Sin override manual de la simulación	La UI no permite editar los overrides — el operador acepta o rehace. Las correcciones se hacen ajustando asistencia/permisos/vacaciones antes de re-simular.
Empleados activos para el modal de generación	GET /api/employees?scope=activos filtra para mostrar sólo candidatos válidos.

Flujo de cálculo

1. Seleccionar periodo activo en el workspace.
2. Verificar que el empleado tenga contrato vigente.
3. Abrir modal “Generar”.
4. Simular (/preview) — la UI muestra haberes, descuentos, aportes y _used_overrides.
5. Generar (/generar con force: true y los mismos overrides).
6. Cambiar estado a APROBADA y luego CONTABILIZADA vía modal.
7. Descargar PDF cuando se requiera entrega.

Endpoints

Método + ruta	Uso
GET /api/remuneraciones/payroll?tenant_id=&year=&mes=&limit=2000	Listado del periodo.
POST /api/remuneraciones/payroll/preview?tenant_id=	Simulación (snake_case).
POST /api/remuneraciones/payroll/generar?tenant_id=	Generación persistente.
PATCH /api/remuneraciones/payroll/:id/status?tenant_id=	Cambio de estado.
GET /api/remuneraciones/payroll/:id/details?tenant_id=	Detalle por conceptos.
GET /api/remuneraciones/payroll/:id/pdf?tenant_id=	Descarga PDF.
DELETE /api/remuneraciones/payroll/:id?tenant_id=&force=true	Eliminación.
GET /api/contracts?tenant_id=&empleado_id=&active=true	Contrato vigente para el cálculo.
GET /api/employees?tenant_id=&scope=activos	Empleados elegibles.

Backend de referencia

PayrollService hidrata el contexto laboral, ejecuta PayrollEngine, persiste líneas de detalle y produce el asiento contable + PDF.