coati-payroll 0.0.2__py3-none-any.whl

coati_payroll/nomina_engine/__init__.py

@@ -0,0 +1,87 @@
+# 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 engine - Domain-driven architecture.
+
+This module provides a modular payroll execution engine organized by domain.
+Main modules:
+- domain: Domain models (immutable data structures)
+- validators: Business validations
+- calculators: Calculation logic
+- processors: Specialized processors (loans, vacations, etc.)
+- repositories: Data access layer
+- services: Business services
+- results: Result DTOs
+
+This package maintains backward compatibility with the original nomina_engine.py
+implementation while providing a new modular structure for future development.
+"""
+
+from __future__ import annotations
+
+from .engine import (
+    NominaEngine,
+    ejecutar_nomina,
+    EmpleadoCalculo,
+)
+
+# Export calculation items for backward compatibility
+from .domain.calculation_items import (
+    DeduccionItem,
+    PercepcionItem,
+    PrestacionItem,
+)
+
+# Export domain models
+from .domain import (
+    PayrollContext,
+    EmployeeCalculation,
+)
+
+# Export results
+from .results import (
+    ValidationResult,
+    ErrorResult,
+    PayrollResult,
+)
+
+# Export exceptions
+from .validators import (
+    NominaEngineError,
+    ValidationError,
+    CalculationError,
+)
+
+__all__ = [
+    # Main engine
+    "NominaEngine",
+    "ejecutar_nomina",
+    # Legacy compatibility
+    "EmpleadoCalculo",
+    "DeduccionItem",
+    "PercepcionItem",
+    "PrestacionItem",
+    # Domain models
+    "PayrollContext",
+    "EmployeeCalculation",
+    # Results
+    "ValidationResult",
+    "ErrorResult",
+    "PayrollResult",
+    # Exceptions
+    "NominaEngineError",
+    "ValidationError",
+    "CalculationError",
+]
+
+__version__ = "2.0.0"

coati_payroll/nomina_engine/calculators/__init__.py

@@ -0,0 +1,30 @@
+# 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.
+"""Calculators for payroll processing."""
+
+from .concept_calculator import ConceptCalculator
+from .salary_calculator import SalaryCalculator
+from .perception_calculator import PerceptionCalculator
+from .deduction_calculator import DeductionCalculator
+from .benefit_calculator import BenefitCalculator
+from .exchange_rate_calculator import ExchangeRateCalculator
+
+__all__ = [
+    "ConceptCalculator",
+    "SalaryCalculator",
+    "PerceptionCalculator",
+    "DeductionCalculator",
+    "BenefitCalculator",
+    "ExchangeRateCalculator",
+]

coati_payroll/nomina_engine/calculators/benefit_calculator.py

@@ -0,0 +1,79 @@
+# 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.
+"""Benefit calculator for payroll processing."""
+
+from __future__ import annotations
+
+from datetime import date
+from decimal import Decimal
+
+from coati_payroll.model import Planilla
+from ..domain.employee_calculation import EmpleadoCalculo
+from ..domain.calculation_items import PrestacionItem
+from .concept_calculator import ConceptCalculator
+
+
+class BenefitCalculator:
+    """Calculator for employer benefits (prestaciones)."""
+
+    def __init__(self, concept_calculator: ConceptCalculator):
+        self.concept_calculator = concept_calculator
+
+    def calculate(self, emp_calculo: EmpleadoCalculo, planilla: Planilla, fecha_calculo: date) -> list[PrestacionItem]:
+        """Calculate all benefits for an employee."""
+        prestaciones = []
+
+        for planilla_prestacion in planilla.planilla_prestaciones:
+            if not planilla_prestacion.activo:
+                continue
+
+            prestacion = planilla_prestacion.prestacion
+            if not prestacion or not prestacion.activo:
+                continue
+
+            # Check validity dates
+            if prestacion.vigente_desde and prestacion.vigente_desde > fecha_calculo:
+                continue
+            if prestacion.valido_hasta and prestacion.valido_hasta < fecha_calculo:
+                continue
+
+            # Calculate benefit amount
+            monto = self.concept_calculator.calculate(
+                emp_calculo,
+                prestacion.formula_tipo,
+                prestacion.monto_default,
+                prestacion.porcentaje,
+                prestacion.formula,
+                planilla_prestacion.monto_predeterminado,
+                planilla_prestacion.porcentaje,
+                codigo_concepto=prestacion.codigo,
+                base_calculo=getattr(prestacion, "base_calculo", None),
+                unidad_calculo=getattr(prestacion, "unidad_calculo", None),
+            )
+
+            # Apply ceiling if defined
+            if prestacion.tope_aplicacion and monto > Decimal(str(prestacion.tope_aplicacion)):
+                monto = Decimal(str(prestacion.tope_aplicacion))
+
+            if monto > 0:
+                item = PrestacionItem(
+                    codigo=prestacion.codigo,
+                    nombre=prestacion.nombre,
+                    monto=monto,
+                    orden=planilla_prestacion.orden or 0,
+                    prestacion_id=prestacion.id,
+                )
+                prestaciones.append(item)
+
+        return prestaciones

coati_payroll/nomina_engine/calculators/concept_calculator.py

@@ -0,0 +1,254 @@
+# 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.
+"""Concept calculator using Strategy pattern."""
+
+from __future__ import annotations
+
+from decimal import Decimal, ROUND_HALF_UP
+
+from coati_payroll.enums import FormulaType
+from coati_payroll.formula_engine import FormulaEngine, FormulaEngineError
+from coati_payroll.model import db, Deduccion, ReglaCalculo
+from ..domain.employee_calculation import EmpleadoCalculo
+
+
+class ConceptCalculator:
+    """Calculator for payroll concepts using Strategy pattern."""
+
+    def __init__(self, config_repository, warnings: list[str]):
+        self.config_repo = config_repository
+        self.warnings = warnings
+
+    def calculate(
+        self,
+        emp_calculo: EmpleadoCalculo,
+        formula_tipo: str,
+        monto_default: Decimal | None,
+        porcentaje: Decimal | None,
+        formula: dict | None,
+        monto_override: Decimal | None,
+        porcentaje_override: Decimal | None,
+        codigo_concepto: str | None = None,
+        base_calculo: str | None = None,
+        unidad_calculo: str | None = None,
+    ) -> Decimal:
+        """Calculate concept amount."""
+        # Use overrides if provided
+        if monto_override:
+            monto_calculado = Decimal(str(monto_override))
+        elif porcentaje_override:
+            monto_calculado = (emp_calculo.salario_base * Decimal(str(porcentaje_override)) / Decimal("100")).quantize(
+                Decimal("0.01"), rounding=ROUND_HALF_UP
+            )
+        else:
+            match formula_tipo:
+                case FormulaType.FIJO:
+                    monto_calculado = Decimal(str(monto_default or 0))
+
+                case FormulaType.PORCENTAJE_SALARIO | FormulaType.PORCENTAJE:
+                    if porcentaje:
+                        monto_calculado = (
+                            emp_calculo.salario_base * Decimal(str(porcentaje)) / Decimal("100")
+                        ).quantize(Decimal("0.01"), rounding=ROUND_HALF_UP)
+                    else:
+                        monto_calculado = Decimal("0.00")
+
+                case FormulaType.PORCENTAJE_BRUTO:
+                    if porcentaje:
+                        monto_calculado = (
+                            emp_calculo.salario_bruto * Decimal(str(porcentaje)) / Decimal("100")
+                        ).quantize(Decimal("0.01"), rounding=ROUND_HALF_UP)
+                    else:
+                        monto_calculado = Decimal("0.00")
+
+                case FormulaType.HORAS:
+                    monto_calculado = self._calculate_hours(emp_calculo, porcentaje, codigo_concepto, base_calculo)
+
+                case FormulaType.DIAS:
+                    monto_calculado = self._calculate_days(emp_calculo, porcentaje, codigo_concepto, base_calculo)
+
+                case FormulaType.FORMULA:
+                    monto_calculado = self._calculate_formula(emp_calculo, formula, codigo_concepto)
+
+                case FormulaType.REGLA_CALCULO:
+                    monto_calculado = self._calculate_regla_calculo(emp_calculo, codigo_concepto)
+
+                case _:
+                    monto_calculado = Decimal(str(monto_default or 0))
+
+        # Ensure calculated amounts are never negative
+        if monto_calculado < 0:
+            self.warnings.append(
+                f"Concepto '{codigo_concepto or 'desconocido'}': Configuración incorrecta resultó en "
+                f"monto negativo ({monto_calculado}). Ajustando a 0.00. "
+                f"Verifique la configuración del concepto (porcentaje o monto)."
+            )
+            return Decimal("0.00")
+
+        return monto_calculado
+
+    def _calculate_hours(
+        self,
+        emp_calculo: EmpleadoCalculo,
+        porcentaje: Decimal | None,
+        codigo_concepto: str | None,
+        base_calculo: str | None,
+    ) -> Decimal:
+        """Calculate based on hours."""
+        if not codigo_concepto or codigo_concepto not in emp_calculo.novedades:
+            return Decimal("0.00")
+
+        horas = emp_calculo.novedades[codigo_concepto]
+        if horas <= 0:
+            return Decimal("0.00")
+
+        # Determine base for calculation
+        if base_calculo == "salario_bruto":
+            base = emp_calculo.salario_bruto
+        else:
+            base = emp_calculo.salario_mensual
+
+        # Calculate hourly rate using configuration
+        config = self.config_repo.get_for_empresa(emp_calculo.planilla.empresa_id)
+        dias_base = Decimal(str(config.dias_mes_nomina))
+        horas_dia = Decimal(str(config.horas_jornada_diaria))
+        tasa_hora = (base / dias_base / horas_dia).quantize(Decimal("0.01"), rounding=ROUND_HALF_UP)
+
+        # Apply percentage
+        if porcentaje:
+            tasa_hora = (tasa_hora * Decimal(str(porcentaje)) / Decimal("100")).quantize(
+                Decimal("0.01"), rounding=ROUND_HALF_UP
+            )
+
+        # Calculate total for hours
+        return (tasa_hora * horas).quantize(Decimal("0.01"), rounding=ROUND_HALF_UP)
+
+    def _calculate_days(
+        self,
+        emp_calculo: EmpleadoCalculo,
+        porcentaje: Decimal | None,
+        codigo_concepto: str | None,
+        base_calculo: str | None,
+    ) -> Decimal:
+        """Calculate based on days."""
+        if not codigo_concepto or codigo_concepto not in emp_calculo.novedades:
+            return Decimal("0.00")
+
+        dias = emp_calculo.novedades[codigo_concepto]
+        if dias <= 0:
+            return Decimal("0.00")
+
+        # Determine base for calculation
+        if base_calculo == "salario_bruto":
+            base = emp_calculo.salario_bruto
+        else:
+            base = emp_calculo.salario_mensual
+
+        # Calculate daily rate using configuration
+        config = self.config_repo.get_for_empresa(emp_calculo.planilla.empresa_id)
+        dias_base = Decimal(str(config.dias_mes_nomina))
+        tasa_dia = (base / dias_base).quantize(Decimal("0.01"), rounding=ROUND_HALF_UP)
+
+        # Apply percentage
+        if porcentaje:
+            tasa_dia = (tasa_dia * Decimal(str(porcentaje)) / Decimal("100")).quantize(
+                Decimal("0.01"), rounding=ROUND_HALF_UP
+            )
+
+        # Calculate total for days
+        return (tasa_dia * dias).quantize(Decimal("0.01"), rounding=ROUND_HALF_UP)
+
+    def _calculate_formula(
+        self, emp_calculo: EmpleadoCalculo, formula: dict | None, codigo_concepto: str | None
+    ) -> Decimal:
+        """Calculate using formula engine."""
+        if not formula or not isinstance(formula, dict):
+            return Decimal("0.00")
+
+        try:
+            # Merge variables with formula inputs
+            inputs = {**emp_calculo.variables_calculo}
+            inputs["salario_bruto"] = emp_calculo.salario_bruto
+            inputs["total_percepciones"] = emp_calculo.total_percepciones
+            inputs["total_deducciones"] = emp_calculo.total_deducciones
+
+            # Calculate before-tax deductions already processed in this period
+            deducciones_antes_impuesto_periodo = Decimal("0.00")
+            for ded in emp_calculo.deducciones:
+                if ded.deduccion_id:
+                    ded_obj = db.session.get(Deduccion, ded.deduccion_id)
+                    if ded_obj and ded_obj.antes_impuesto:
+                        deducciones_antes_impuesto_periodo += ded.monto
+            inputs["deducciones_antes_impuesto_periodo"] = deducciones_antes_impuesto_periodo
+            # Legacy alias for backward compatibility (deprecated but kept to avoid breaking existing schemas)
+            inputs["inss_periodo"] = deducciones_antes_impuesto_periodo
+            # New generic aliases (preferred for new schemas)
+            inputs["pre_tax_deductions"] = deducciones_antes_impuesto_periodo
+            inputs["social_security_deduction"] = deducciones_antes_impuesto_periodo
+
+            engine = FormulaEngine(formula)
+            result = engine.execute(inputs)
+            return Decimal(str(result.get("output", 0))).quantize(Decimal("0.01"), rounding=ROUND_HALF_UP)
+        except FormulaEngineError as e:
+            self.warnings.append(f"Error en fórmula: {str(e)}")
+            return Decimal("0.00")
+
+    def _calculate_regla_calculo(self, emp_calculo: EmpleadoCalculo, codigo_concepto: str | None) -> Decimal:
+        """Calculate using ReglaCalculo."""
+        from sqlalchemy import select
+
+        # Find the ReglaCalculo linked to this deduction
+        regla = db.session.execute(
+            select(ReglaCalculo).filter_by(deduccion_id=codigo_concepto).filter(ReglaCalculo.activo.is_(True))
+        ).scalar_one_or_none()
+
+        if not regla:
+            # Try finding by deduccion_id matching deduccion's id
+            deduccion_obj = db.session.execute(select(Deduccion).filter_by(codigo=codigo_concepto)).scalar_one_or_none()
+            if deduccion_obj:
+                regla = db.session.execute(
+                    select(ReglaCalculo).filter_by(deduccion_id=deduccion_obj.id).filter(ReglaCalculo.activo.is_(True))
+                ).scalar_one_or_none()
+
+        if not regla or not regla.esquema_json:
+            self.warnings.append(f"ReglaCalculo no encontrada para deducción {codigo_concepto}")
+            return Decimal("0.00")
+
+        try:
+            # Prepare inputs for formula engine
+            inputs = {**emp_calculo.variables_calculo}
+            inputs["salario_bruto"] = emp_calculo.salario_bruto
+            inputs["total_percepciones"] = emp_calculo.total_percepciones
+            inputs["total_deducciones"] = emp_calculo.total_deducciones
+
+            # Calculate before-tax deductions already processed
+            deducciones_antes_impuesto_periodo = Decimal("0.00")
+            for ded in emp_calculo.deducciones:
+                if ded.deduccion_id:
+                    ded_obj = db.session.get(Deduccion, ded.deduccion_id)
+                    if ded_obj and ded_obj.antes_impuesto:
+                        deducciones_antes_impuesto_periodo += ded.monto
+            inputs["deducciones_antes_impuesto_periodo"] = deducciones_antes_impuesto_periodo
+            # Legacy alias for backward compatibility (deprecated but kept to avoid breaking existing schemas)
+            inputs["inss_periodo"] = deducciones_antes_impuesto_periodo
+            # New generic aliases (preferred for new schemas)
+            inputs["pre_tax_deductions"] = deducciones_antes_impuesto_periodo
+            inputs["social_security_deduction"] = deducciones_antes_impuesto_periodo
+
+            engine = FormulaEngine(regla.esquema_json)
+            result = engine.execute(inputs)
+            return Decimal(str(result.get("output", 0))).quantize(Decimal("0.01"), rounding=ROUND_HALF_UP)
+        except FormulaEngineError as e:
+            self.warnings.append(f"Error en ReglaCalculo {regla.codigo}: {str(e)}")
+            return Decimal("0.00")

coati_payroll/nomina_engine/calculators/deduction_calculator.py

@@ -0,0 +1,105 @@
+# 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.
+"""Deduction calculator for payroll processing."""
+
+from __future__ import annotations
+
+from datetime import date
+
+from coati_payroll.model import Planilla
+from ..domain.employee_calculation import EmpleadoCalculo
+from ..domain.calculation_items import DeduccionItem
+from .concept_calculator import ConceptCalculator
+
+
+class DeductionCalculator:
+    """Calculator for deductions (salary subtractions)."""
+
+    def __init__(self, concept_calculator: ConceptCalculator, warnings: list[str]):
+        self.concept_calculator = concept_calculator
+        self.warnings = warnings
+
+    def calculate(self, emp_calculo: EmpleadoCalculo, planilla: Planilla, fecha_calculo: date) -> list[DeduccionItem]:
+        """Calculate all deductions for an employee, applying priority order."""
+        deducciones_pendientes: list[DeduccionItem] = []
+
+        for planilla_deduccion in planilla.planilla_deducciones:
+            if not planilla_deduccion.activo:
+                continue
+
+            deduccion = planilla_deduccion.deduccion
+            if not deduccion or not deduccion.activo:
+                continue
+
+            # Check validity dates
+            if deduccion.vigente_desde and deduccion.vigente_desde > fecha_calculo:
+                continue
+            if deduccion.valido_hasta and deduccion.valido_hasta < fecha_calculo:
+                continue
+
+            # Calculate deduction amount
+            monto = self.concept_calculator.calculate(
+                emp_calculo,
+                deduccion.formula_tipo,
+                deduccion.monto_default,
+                deduccion.porcentaje,
+                deduccion.formula,
+                planilla_deduccion.monto_predeterminado,
+                planilla_deduccion.porcentaje,
+                codigo_concepto=deduccion.codigo,
+                base_calculo=getattr(deduccion, "base_calculo", None),
+                unidad_calculo=getattr(deduccion, "unidad_calculo", None),
+            )
+
+            if monto > 0:
+                item = DeduccionItem(
+                    codigo=deduccion.codigo,
+                    nombre=deduccion.nombre,
+                    monto=monto,
+                    prioridad=planilla_deduccion.prioridad,
+                    es_obligatoria=planilla_deduccion.es_obligatoria,
+                    deduccion_id=deduccion.id,
+                )
+                deducciones_pendientes.append(item)
+
+        # Sort by priority (lower number = higher priority)
+        deducciones_pendientes.sort(key=lambda x: x.prioridad)
+
+        # Apply deductions in priority order
+        saldo_disponible = emp_calculo.salario_bruto
+        deducciones_aplicadas = []
+
+        for deduccion in deducciones_pendientes:
+            monto_aplicar = min(deduccion.monto, saldo_disponible)
+
+            if monto_aplicar <= 0 and not deduccion.es_obligatoria:
+                self.warnings.append(
+                    f"Empleado {emp_calculo.empleado.primer_nombre} "
+                    f"{emp_calculo.empleado.primer_apellido}: "
+                    f"Deducción {deduccion.codigo} omitida por saldo insuficiente."
+                )
+                continue
+
+            item = DeduccionItem(
+                codigo=deduccion.codigo,
+                nombre=deduccion.nombre,
+                monto=monto_aplicar,
+                prioridad=deduccion.prioridad,
+                es_obligatoria=deduccion.es_obligatoria,
+                deduccion_id=deduccion.deduccion_id,
+            )
+            deducciones_aplicadas.append(item)
+            saldo_disponible -= monto_aplicar
+
+        return deducciones_aplicadas

coati_payroll/nomina_engine/calculators/exchange_rate_calculator.py

@@ -0,0 +1,51 @@
+# 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.
+"""Exchange rate calculator for payroll processing."""
+
+from __future__ import annotations
+
+from datetime import date
+from decimal import Decimal
+
+from coati_payroll.model import Empleado, Planilla
+from ..repositories.exchange_rate_repository import ExchangeRateRepository
+
+
+class ExchangeRateCalculator:
+    """Calculator for exchange rates."""
+
+    def __init__(self, exchange_rate_repository: ExchangeRateRepository):
+        self.exchange_rate_repo = exchange_rate_repository
+
+    def get_exchange_rate(self, empleado: Empleado, planilla: Planilla, fecha_calculo: date) -> Decimal:
+        """Get exchange rate for employee's currency to planilla currency."""
+        if not empleado.moneda_id:
+            return Decimal("1.00")
+
+        if empleado.moneda_id == planilla.moneda_id:
+            return Decimal("1.00")
+
+        rate = self.exchange_rate_repo.get_rate(empleado.moneda_id, planilla.moneda_id, fecha_calculo)
+        if rate is None:
+            from ..validators import CalculationError
+
+            raise CalculationError(
+                f"No se encontró tipo de cambio para empleado "
+                f"{empleado.primer_nombre} {empleado.primer_apellido}. "
+                f"Se requiere un tipo de cambio de {empleado.moneda.codigo if empleado.moneda else 'desconocido'} "
+                f"a {planilla.moneda.codigo if planilla.moneda else 'desconocido'} "
+                f"para la fecha {fecha_calculo.strftime('%d/%m/%Y')}."
+            )
+
+        return Decimal(str(rate))

coati_payroll/nomina_engine/calculators/perception_calculator.py

@@ -0,0 +1,75 @@
+# 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.
+"""Perception calculator for payroll processing."""
+
+from __future__ import annotations
+
+from datetime import date
+
+from coati_payroll.model import Planilla
+from ..domain.employee_calculation import EmpleadoCalculo
+from ..domain.calculation_items import PercepcionItem
+from .concept_calculator import ConceptCalculator
+
+
+class PerceptionCalculator:
+    """Calculator for perceptions (income additions)."""
+
+    def __init__(self, concept_calculator: ConceptCalculator):
+        self.concept_calculator = concept_calculator
+
+    def calculate(self, emp_calculo: EmpleadoCalculo, planilla: Planilla, fecha_calculo: date) -> list[PercepcionItem]:
+        """Calculate all perceptions for an employee."""
+        percepciones = []
+
+        for planilla_percepcion in planilla.planilla_percepciones:
+            if not planilla_percepcion.activo:
+                continue
+
+            percepcion = planilla_percepcion.percepcion
+            if not percepcion or not percepcion.activo:
+                continue
+
+            # Check validity dates
+            if percepcion.vigente_desde and percepcion.vigente_desde > fecha_calculo:
+                continue
+            if percepcion.valido_hasta and percepcion.valido_hasta < fecha_calculo:
+                continue
+
+            # Calculate perception amount
+            monto = self.concept_calculator.calculate(
+                emp_calculo,
+                percepcion.formula_tipo,
+                percepcion.monto_default,
+                percepcion.porcentaje,
+                percepcion.formula,
+                planilla_percepcion.monto_predeterminado,
+                planilla_percepcion.porcentaje,
+                codigo_concepto=percepcion.codigo,
+                base_calculo=getattr(percepcion, "base_calculo", None),
+                unidad_calculo=getattr(percepcion, "unidad_calculo", None),
+            )
+
+            if monto > 0:
+                item = PercepcionItem(
+                    codigo=percepcion.codigo,
+                    nombre=percepcion.nombre,
+                    monto=monto,
+                    orden=planilla_percepcion.orden or 0,
+                    gravable=percepcion.gravable,
+                    percepcion_id=percepcion.id,
+                )
+                percepciones.append(item)
+
+        return percepciones