coati-payroll 0.0.2__py3-none-any.whl

coati_payroll/nomina_engine/calculators/salary_calculator.py

@@ -0,0 +1,86 @@
+# Copyright 2025 BMO Soluciones, S.A.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#    http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+"""Salary calculator for payroll processing."""
+
+from __future__ import annotations
+
+from datetime import date, timedelta
+from decimal import Decimal, ROUND_HALF_UP
+
+from coati_payroll.model import Planilla, ConfiguracionCalculos
+from ..repositories.config_repository import ConfigRepository
+
+
+class SalaryCalculator:
+    """Calculator for salary period calculations."""
+
+    def __init__(self, config_repository: ConfigRepository):
+        self.config_repo = config_repository
+
+    def calculate_period_salary(
+        self, salario_mensual: Decimal, planilla: Planilla, periodo_inicio: date, periodo_fin: date, fecha_calculo: date
+    ) -> Decimal:
+        """Calculate salary for the pay period based on actual days."""
+        if not planilla or not planilla.tipo_planilla:
+            return salario_mensual
+
+        if not periodo_fin or not periodo_inicio:
+            return salario_mensual
+
+        dias_periodo = (periodo_fin - periodo_inicio).days + 1
+
+        if dias_periodo <= 0:
+            from ..validators import ValidationError
+
+            raise ValidationError(f"Período inválido: inicio ({periodo_inicio}) posterior a fin ({periodo_fin})")
+        if dias_periodo > 366:
+            from ..validators import ValidationError
+
+            raise ValidationError(
+                f"Período excesivamente largo: {dias_periodo} días. Los períodos no deben exceder 366 días."
+            )
+
+        tipo_planilla = planilla.tipo_planilla
+        periodicidad = tipo_planilla.periodicidad.lower() if tipo_planilla.periodicidad else ""
+
+        if periodicidad == "mensual":
+            is_first_of_month = periodo_inicio.day == 1
+            next_day = periodo_fin + timedelta(days=1)
+            is_last_of_month = next_day.day == 1
+            same_month = periodo_inicio.year == periodo_fin.year and periodo_inicio.month == periodo_fin.month
+
+            if is_first_of_month and is_last_of_month and same_month:
+                return salario_mensual
+
+        elif periodicidad == "quincenal":
+            config = self.config_repo.get_for_empresa(planilla.empresa_id)
+            dias_configurados = tipo_planilla.dias or config.dias_quincena
+            if dias_periodo == dias_configurados:
+                divisor = Decimal(str(config.dias_mes_nomina)) / Decimal(str(config.dias_quincena))
+                return (salario_mensual / divisor).quantize(Decimal("0.01"), rounding=ROUND_HALF_UP)
+
+        config = self.config_repo.get_for_empresa(planilla.empresa_id)
+        dias_base = Decimal(str(config.dias_mes_nomina))
+        salario_diario = (salario_mensual / dias_base).quantize(Decimal("0.01"), rounding=ROUND_HALF_UP)
+        salario_periodo = (salario_diario * Decimal(str(dias_periodo))).quantize(
+            Decimal("0.01"), rounding=ROUND_HALF_UP
+        )
+
+        return salario_periodo
+
+    def calculate_hourly_rate(self, salario_mensual: Decimal, config: ConfiguracionCalculos) -> Decimal:
+        """Calculate hourly rate from monthly salary."""
+        dias_base = Decimal(str(config.dias_mes_nomina))
+        horas_dia = Decimal(str(config.horas_jornada_diaria))
+        return (salario_mensual / dias_base / horas_dia).quantize(Decimal("0.01"), rounding=ROUND_HALF_UP)

coati_payroll/nomina_engine/domain/__init__.py

@@ -0,0 +1,27 @@
+# Copyright 2025 BMO Soluciones, S.A.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#    http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+"""Domain models for payroll processing."""
+
+from .payroll_context import PayrollContext
+from .employee_calculation import EmployeeCalculation, EmpleadoCalculo
+from .calculation_items import DeduccionItem, PercepcionItem, PrestacionItem
+
+__all__ = [
+    "PayrollContext",
+    "EmployeeCalculation",
+    "EmpleadoCalculo",
+    "DeduccionItem",
+    "PercepcionItem",
+    "PrestacionItem",
+]

coati_payroll/nomina_engine/domain/calculation_items.py

@@ -0,0 +1,52 @@
+# Copyright 2025 BMO Soluciones, S.A.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#    http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+"""Calculation items - immutable domain models for payroll items."""
+
+from __future__ import annotations
+
+from decimal import Decimal
+from typing import NamedTuple
+
+
+class DeduccionItem(NamedTuple):
+    """Represents a deduction to be applied."""
+
+    codigo: str
+    nombre: str
+    monto: Decimal
+    prioridad: int
+    es_obligatoria: bool
+    deduccion_id: str | None = None
+    tipo: str = "deduccion"  # deduccion, prestamo, adelanto
+
+
+class PercepcionItem(NamedTuple):
+    """Represents a perception to be applied."""
+
+    codigo: str
+    nombre: str
+    monto: Decimal
+    orden: int
+    gravable: bool
+    percepcion_id: str | None = None
+
+
+class PrestacionItem(NamedTuple):
+    """Represents an employer benefit to be calculated."""
+
+    codigo: str
+    nombre: str
+    monto: Decimal
+    orden: int
+    prestacion_id: str | None = None

coati_payroll/nomina_engine/domain/employee_calculation.py

@@ -0,0 +1,53 @@
+# Copyright 2025 BMO Soluciones, S.A.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#    http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+"""Employee calculation domain models."""
+
+from __future__ import annotations
+
+from decimal import Decimal
+from typing import Any
+
+from coati_payroll.model import Empleado, Planilla
+from .calculation_items import DeduccionItem, PercepcionItem, PrestacionItem
+
+
+class EmpleadoCalculo:
+    """Container for employee calculation data during payroll processing.
+
+    This is a mutable container used during payroll processing.
+    For backward compatibility, this class maintains the same interface
+    as the original implementation.
+    """
+
+    def __init__(self, empleado: Empleado, planilla: Planilla):
+        self.empleado = empleado
+        self.planilla = planilla
+        self.salario_base = Decimal(str(empleado.salario_base or 0))
+        self.salario_mensual = Decimal(str(empleado.salario_base or 0))
+        self.percepciones: list[PercepcionItem] = []
+        self.deducciones: list[DeduccionItem] = []
+        self.prestaciones: list[PrestacionItem] = []
+        self.total_percepciones = Decimal("0.00")
+        self.total_deducciones = Decimal("0.00")
+        self.total_prestaciones = Decimal("0.00")
+        self.salario_bruto = Decimal("0.00")
+        self.salario_neto = Decimal("0.00")
+        self.tipo_cambio = Decimal("1.00")
+        self.moneda_origen_id = empleado.moneda_id
+        self.novedades: dict[str, Decimal] = {}
+        self.variables_calculo: dict[str, Any] = {}
+
+
+# Alias for backward compatibility
+EmployeeCalculation = EmpleadoCalculo

coati_payroll/nomina_engine/domain/payroll_context.py

@@ -0,0 +1,44 @@
+# Copyright 2025 BMO Soluciones, S.A.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#    http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+"""Payroll execution context - immutable domain model."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from datetime import date
+from typing import Optional, TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from ..results.validation_result import ValidationResult
+
+
+@dataclass(frozen=True)
+class PayrollContext:
+    """Immutable context for payroll execution."""
+
+    planilla_id: str
+    periodo_inicio: date
+    periodo_fin: date
+    fecha_calculo: date
+    usuario: Optional[str] = None
+    validation_result: "ValidationResult | None" = None
+    errors: list[str] = field(default_factory=list)
+    warnings: list[str] = field(default_factory=list)
+
+    def __post_init__(self):
+        """Initialize default validation_result if None."""
+        if self.validation_result is None:
+            from ..results.validation_result import ValidationResult
+
+            object.__setattr__(self, "validation_result", ValidationResult())

coati_payroll/nomina_engine/engine.py

@@ -0,0 +1,188 @@
+# Copyright 2025 BMO Soluciones, S.A.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#    http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+"""Main payroll engine orchestrator - refactored implementation."""
+
+from __future__ import annotations
+
+from datetime import date
+
+from coati_payroll.model import db, Planilla, Nomina
+from coati_payroll.log import TRACE_LEVEL_NUM, is_trace_enabled, log
+from .domain.employee_calculation import EmpleadoCalculo
+from .services.payroll_execution_service import PayrollExecutionService
+
+
+class NominaEngine:
+    """Engine for executing payroll runs.
+
+    This engine processes a Planilla configuration and generates a complete
+    Nomina with all employee calculations. It handles:
+
+    1. Perceptions (ingresos) - add to gross salary
+    2. Deductions (deducciones) - subtract from net salary, in priority order
+    3. Benefits (prestaciones) - employer costs, don't affect employee pay
+    4. Automatic deductions - loans and advances from Adelanto table
+    5. Accumulated annual values - for progressive tax calculations
+    """
+
+    def __init__(
+        self,
+        planilla: Planilla,
+        periodo_inicio: date,
+        periodo_fin: date,
+        fecha_calculo: date | None = None,
+        usuario: str | None = None,
+    ):
+        """Initialize the payroll engine.
+
+        Args:
+            planilla: The Planilla to execute
+            periodo_inicio: Start date of the payroll period
+            periodo_fin: End date of the payroll period
+            fecha_calculo: Date of calculation (defaults to today)
+            usuario: Username executing the payroll
+        """
+        self.planilla = planilla
+        self.periodo_inicio = periodo_inicio
+        self.periodo_fin = periodo_fin
+        self.fecha_calculo = fecha_calculo or date.today()
+        self.usuario = usuario
+        self.nomina: Nomina | None = None
+        self.empleados_calculo: list[EmpleadoCalculo] = []
+        self.errors: list[str] = []
+        self.warnings: list[str] = []
+
+        # Initialize execution service
+        self.execution_service = PayrollExecutionService(db.session)
+
+    def _trace(self, message: str) -> None:
+        """Trace helper for logging."""
+        if is_trace_enabled():
+            log.log(TRACE_LEVEL_NUM, message)
+
+    def validar_planilla(self) -> bool:
+        """Validate that the planilla is ready for execution.
+
+        Returns:
+            True if valid, False otherwise
+        """
+        from .domain.payroll_context import PayrollContext
+
+        context = PayrollContext(
+            planilla_id=self.planilla.id,
+            periodo_inicio=self.periodo_inicio,
+            periodo_fin=self.periodo_fin,
+            fecha_calculo=self.fecha_calculo,
+            usuario=self.usuario,
+        )
+
+        validation_result = self.execution_service.planilla_validator.validate(context)
+        if not validation_result.is_valid:
+            self.errors.extend(validation_result.errors)
+            return False
+
+        return True
+
+    def ejecutar(self) -> Nomina | None:
+        """Execute the payroll run.
+
+        Returns:
+            The generated Nomina record, or None if execution failed
+        """
+        # Validate planilla
+        if not self.validar_planilla():
+            return None
+
+        # Execute payroll using service
+        nomina, empleados_calculo, errors, warnings = self.execution_service.execute_payroll(
+            self.planilla,
+            self.periodo_inicio,
+            self.periodo_fin,
+            self.fecha_calculo,
+            self.usuario,
+        )
+
+        self.nomina = nomina
+        self.empleados_calculo = empleados_calculo
+        self.errors = errors
+        self.warnings = warnings
+
+        if nomina:
+            # Commit the transaction
+            db.session.commit()
+            return nomina
+        else:
+            # Rollback on failure
+            db.session.rollback()
+            return None
+
+
+def ejecutar_nomina(
+    planilla_id: str,
+    periodo_inicio: date,
+    periodo_fin: date,
+    fecha_calculo: date | None = None,
+    usuario: str | None = None,
+) -> tuple[Nomina | None, list[str], list[str]]:
+    """Execute a payroll run for a planilla.
+
+    Convenience function for executing a payroll run.
+
+    Args:
+        planilla_id: ID of the Planilla to execute
+        periodo_inicio: Start date of the payroll period
+        periodo_fin: End date of the payroll period
+        fecha_calculo: Date of calculation (defaults to today)
+        usuario: Username executing the payroll
+
+    Returns:
+        Tuple of (Nomina or None, list of errors, list of warnings)
+    """
+    # Eagerly load all relationships needed for payroll processing
+    from sqlalchemy.orm import joinedload
+    from sqlalchemy import select
+    from coati_payroll.model import PlanillaIngreso, PlanillaDeduccion, PlanillaPrestacion, PlanillaEmpleado
+
+    planilla = (
+        db.session.execute(
+            select(Planilla)
+            .options(
+                joinedload(Planilla.planilla_percepciones).joinedload(PlanillaIngreso.percepcion),
+                joinedload(Planilla.planilla_deducciones).joinedload(PlanillaDeduccion.deduccion),
+                joinedload(Planilla.planilla_prestaciones).joinedload(PlanillaPrestacion.prestacion),
+                joinedload(Planilla.planilla_empleados).joinedload(PlanillaEmpleado.empleado),
+                joinedload(Planilla.planilla_reglas_calculo),
+                joinedload(Planilla.tipo_planilla),
+                joinedload(Planilla.moneda),
+            )
+            .filter(Planilla.id == planilla_id)
+        )
+        .unique()
+        .scalar_one_or_none()
+    )
+
+    if not planilla:
+        return None, ["Planilla no encontrada."], []
+
+    engine = NominaEngine(
+        planilla=planilla,
+        periodo_inicio=periodo_inicio,
+        periodo_fin=periodo_fin,
+        fecha_calculo=fecha_calculo,
+        usuario=usuario,
+    )
+
+    nomina = engine.ejecutar()
+
+    return nomina, engine.errors, engine.warnings

coati_payroll/nomina_engine/processors/__init__.py

@@ -0,0 +1,28 @@
+# Copyright 2025 BMO Soluciones, S.A.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#    http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+"""Processors for specialized payroll operations."""
+
+from .loan_processor import LoanProcessor
+from .accumulation_processor import AccumulationProcessor
+from .vacation_processor import VacationProcessor
+from .novelty_processor import NoveltyProcessor
+from .accounting_processor import AccountingProcessor
+
+__all__ = [
+    "LoanProcessor",
+    "AccumulationProcessor",
+    "VacationProcessor",
+    "NoveltyProcessor",
+    "AccountingProcessor",
+]

coati_payroll/nomina_engine/processors/accounting_processor.py

@@ -0,0 +1,171 @@
+# Copyright 2025 BMO Soluciones, S.A.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#    http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+"""Accounting processor for creating payroll records."""
+
+from __future__ import annotations
+
+from datetime import date
+from decimal import Decimal
+
+from coati_payroll.model import db, Nomina, NominaEmpleado, NominaDetalle, Prestacion, PrestacionAcumulada
+from ..domain.employee_calculation import EmpleadoCalculo
+
+
+class AccountingProcessor:
+    """Processor for creating accounting records (NominaEmpleado, NominaDetalle, PrestacionAcumulada)."""
+
+    def create_nomina_empleado(self, emp_calculo: EmpleadoCalculo, nomina: Nomina) -> NominaEmpleado:
+        """Create NominaEmpleado record with all details."""
+        empleado = emp_calculo.empleado
+
+        nomina_empleado = NominaEmpleado(
+            nomina_id=nomina.id,
+            empleado_id=empleado.id,
+            salario_bruto=emp_calculo.salario_bruto,
+            total_ingresos=emp_calculo.total_percepciones,
+            total_deducciones=emp_calculo.total_deducciones,
+            salario_neto=emp_calculo.salario_neto,
+            moneda_origen_id=emp_calculo.moneda_origen_id,
+            tipo_cambio_aplicado=emp_calculo.tipo_cambio,
+            cargo_snapshot=empleado.cargo,
+            area_snapshot=empleado.area,
+            centro_costos_snapshot=empleado.centro_costos,
+            sueldo_base_historico=emp_calculo.salario_base,
+        )
+        db.session.add(nomina_empleado)
+        db.session.flush()
+
+        # Create detail records for perceptions
+        orden = 0
+        for percepcion in emp_calculo.percepciones:
+            orden += 1
+            detalle = NominaDetalle(
+                nomina_empleado_id=nomina_empleado.id,
+                tipo="ingreso",
+                codigo=percepcion.codigo,
+                descripcion=percepcion.nombre,
+                monto=percepcion.monto,
+                orden=orden,
+                percepcion_id=percepcion.percepcion_id,
+            )
+            db.session.add(detalle)
+
+        # Create detail records for deductions
+        for deduccion in emp_calculo.deducciones:
+            orden += 1
+            detalle = NominaDetalle(
+                nomina_empleado_id=nomina_empleado.id,
+                tipo="deduccion",
+                codigo=deduccion.codigo,
+                descripcion=deduccion.nombre,
+                monto=deduccion.monto,
+                orden=orden,
+                deduccion_id=deduccion.deduccion_id,
+            )
+            db.session.add(detalle)
+
+        # Create detail records for benefits
+        for prestacion in emp_calculo.prestaciones:
+            orden += 1
+            detalle = NominaDetalle(
+                nomina_empleado_id=nomina_empleado.id,
+                tipo="prestacion",
+                codigo=prestacion.codigo,
+                descripcion=prestacion.nombre,
+                monto=prestacion.monto,
+                orden=orden,
+                prestacion_id=prestacion.prestacion_id,
+            )
+            db.session.add(detalle)
+
+        return nomina_empleado
+
+    def create_prestacion_transactions(
+        self,
+        emp_calculo: EmpleadoCalculo,
+        nomina: Nomina,
+        planilla,
+        periodo_fin: date,
+        fecha_calculo: date,
+    ) -> None:
+        """Create transactional records for accumulated benefits."""
+        empleado = emp_calculo.empleado
+        periodo_anio = periodo_fin.year
+        periodo_mes = periodo_fin.month
+        moneda_id = planilla.moneda_id
+
+        for prestacion_item in emp_calculo.prestaciones:
+            if not prestacion_item.prestacion_id:
+                continue
+
+            prestacion = db.session.get(Prestacion, prestacion_item.prestacion_id)
+            if not prestacion:
+                continue
+
+            # Get the previous balance
+            from sqlalchemy import select
+
+            ultima_transaccion = (
+                db.session.execute(
+                    select(PrestacionAcumulada)
+                    .filter(
+                        PrestacionAcumulada.empleado_id == empleado.id,
+                        PrestacionAcumulada.prestacion_id == prestacion.id,
+                    )
+                    .order_by(
+                        PrestacionAcumulada.fecha_transaccion.desc(),
+                        PrestacionAcumulada.creado.desc(),
+                    )
+                    .limit(1)
+                )
+                .unique()
+                .scalars()
+                .first()
+            )
+
+            saldo_anterior = ultima_transaccion.saldo_nuevo if ultima_transaccion else Decimal("0.00")
+
+            # For monthly settlement benefits, reset balance if new month
+            if prestacion.tipo_acumulacion == "mensual":
+                if ultima_transaccion and (
+                    ultima_transaccion.anio != periodo_anio or ultima_transaccion.mes != periodo_mes
+                ):
+                    saldo_anterior = Decimal("0.00")
+
+            # Calculate new balance
+            monto_transaccion = prestacion_item.monto
+            saldo_nuevo = saldo_anterior + monto_transaccion
+
+            # Create the transaction record
+            transaccion = PrestacionAcumulada(
+                empleado_id=empleado.id,
+                prestacion_id=prestacion.id,
+                fecha_transaccion=fecha_calculo,
+                tipo_transaccion="adicion",
+                anio=periodo_anio,
+                mes=periodo_mes,
+                moneda_id=moneda_id,
+                monto_transaccion=monto_transaccion,
+                saldo_anterior=saldo_anterior,
+                saldo_nuevo=saldo_nuevo,
+                nomina_id=nomina.id,
+                observaciones=(
+                    f"Provisión nómina {nomina.periodo_inicio.strftime('%Y-%m-%d')} - "
+                    f"{nomina.periodo_fin.strftime('%Y-%m-%d')}"
+                ),
+                procesado_por=nomina.generado_por,
+                creado_por=nomina.generado_por,
+            )
+
+            db.session.add(transaccion)