coati-payroll 0.0.2__py3-none-any.whl

coati_payroll/nomina_engine/services/snapshot_service.py

@@ -0,0 +1,295 @@
+"""Snapshot Service for Payroll Recalculation Consistency.
+
+This service captures immutable snapshots of all configuration data needed
+to ensure payroll calculations can be recalculated consistently.
+"""
+
+from __future__ import annotations
+
+from datetime import date
+from typing import Any
+
+from coati_payroll.model import (
+    ConfiguracionCalculos,
+    Percepcion,
+    Deduccion,
+    Prestacion,
+    Planilla,
+    TipoCambio,
+    db,
+)
+
+
+class SnapshotService:
+    """Service for capturing configuration snapshots for payroll consistency."""
+
+    def __init__(self, session):
+        self.session = session
+
+    def capture_configuration_snapshot(self, empresa_id: str) -> dict[str, Any]:
+        """Capture complete company configuration snapshot.
+
+        Args:
+            empresa_id: Company ID
+
+        Returns:
+            Dictionary with all configuration values
+        """
+        config = self.session.execute(
+            db.select(ConfiguracionCalculos).filter(
+                ConfiguracionCalculos.empresa_id == empresa_id,
+                ConfiguracionCalculos.activo.is_(True),
+            )
+        ).scalar_one_or_none()
+
+        if not config:
+            return {}
+
+        return {
+            "empresa_id": config.empresa_id,
+            "pais_id": config.pais_id,
+            "dias_mes_nomina": config.dias_mes_nomina,
+            "dias_anio_nomina": config.dias_anio_nomina,
+            "horas_jornada_diaria": str(config.horas_jornada_diaria),
+            "dias_mes_vacaciones": config.dias_mes_vacaciones,
+            "dias_anio_vacaciones": config.dias_anio_vacaciones,
+            "considerar_bisiesto_vacaciones": config.considerar_bisiesto_vacaciones,
+            "dias_anio_financiero": config.dias_anio_financiero,
+            "meses_anio_financiero": config.meses_anio_financiero,
+            "dias_quincena": config.dias_quincena,
+            "liquidacion_modo_dias": config.liquidacion_modo_dias,
+            "liquidacion_factor_calendario": config.liquidacion_factor_calendario,
+            "liquidacion_factor_laboral": config.liquidacion_factor_laboral,
+            "dias_mes_antiguedad": config.dias_mes_antiguedad,
+            "dias_anio_antiguedad": config.dias_anio_antiguedad,
+            "activo": config.activo,
+        }
+
+    def capture_exchange_rates_snapshot(self, planilla: Planilla, fecha_calculo: date) -> dict[str, Any]:
+        """Capture exchange rates snapshot for all currencies used.
+
+        Args:
+            planilla: Planilla being processed
+            fecha_calculo: Calculation date
+
+        Returns:
+            Dictionary with exchange rates by currency
+        """
+        rates = {}
+
+        # Get all unique currencies from employees in this planilla
+        from coati_payroll.model import Empleado, PlanillaEmpleado
+
+        empleados = (
+            self.session.execute(
+                db.select(Empleado)
+                .join(PlanillaEmpleado)
+                .filter(
+                    PlanillaEmpleado.planilla_id == planilla.id,
+                    PlanillaEmpleado.activo.is_(True),
+                    Empleado.activo.is_(True),
+                )
+            )
+            .scalars()
+            .all()
+        )
+
+        monedas_usadas = {emp.moneda_id for emp in empleados if emp.moneda_id}
+        monedas_usadas.add(planilla.moneda_id)
+
+        # Get exchange rates for each currency
+        for moneda_id in monedas_usadas:
+            if moneda_id == planilla.moneda_id:
+                rates[moneda_id] = {"tasa": "1.00", "fecha": fecha_calculo.isoformat()}
+            else:
+                tipo_cambio = (
+                    self.session.execute(
+                        db.select(TipoCambio)
+                        .filter(
+                            TipoCambio.moneda_origen_id == moneda_id,
+                            TipoCambio.moneda_destino_id == planilla.moneda_id,
+                            TipoCambio.fecha_vigencia <= fecha_calculo,
+                        )
+                        .order_by(TipoCambio.fecha_vigencia.desc())
+                    )
+                    .scalars()
+                    .first()
+                )
+
+                if tipo_cambio:
+                    rates[moneda_id] = {
+                        "tasa": str(tipo_cambio.tasa),
+                        "fecha": tipo_cambio.fecha_vigencia.isoformat(),
+                        "moneda_destino_id": tipo_cambio.moneda_destino_id,
+                    }
+
+        return rates
+
+    def capture_catalogs_snapshot(self, planilla: Planilla) -> dict[str, Any]:
+        """Capture complete catalogs snapshot (percepciones, deducciones, prestaciones).
+
+        Args:
+            planilla: Planilla being processed
+
+        Returns:
+            Dictionary with all catalog items and their formulas
+        """
+        snapshot = {
+            "percepciones": [],
+            "deducciones": [],
+            "prestaciones": [],
+        }
+
+        # Capture Percepciones linked to this planilla
+        from coati_payroll.model import PlanillaIngreso
+
+        percepciones_ids = (
+            self.session.execute(
+                db.select(PlanillaIngreso.percepcion_id).filter(
+                    PlanillaIngreso.planilla_id == planilla.id,
+                    PlanillaIngreso.activo.is_(True),
+                )
+            )
+            .scalars()
+            .all()
+        )
+
+        if percepciones_ids:
+            percepciones = (
+                self.session.execute(
+                    db.select(Percepcion).filter(
+                        Percepcion.id.in_(percepciones_ids),
+                        Percepcion.activo.is_(True),
+                    )
+                )
+                .scalars()
+                .all()
+            )
+        else:
+            percepciones = []
+
+        for p in percepciones:
+            snapshot["percepciones"].append(
+                {
+                    "id": p.id,
+                    "codigo": p.codigo,
+                    "nombre": p.nombre,
+                    "descripcion": p.descripcion,
+                    "formula_tipo": p.formula_tipo,
+                    "formula": p.formula,
+                    "monto_default": str(p.monto_default) if p.monto_default else None,
+                    "porcentaje": str(p.porcentaje) if p.porcentaje else None,
+                    "gravable": p.gravable,
+                    "base_calculo": p.base_calculo,
+                    "estado_aprobacion": p.estado_aprobacion,
+                }
+            )
+
+        # Capture Deducciones linked to this planilla
+        from coati_payroll.model import PlanillaDeduccion
+
+        deducciones_ids = (
+            self.session.execute(
+                db.select(PlanillaDeduccion.deduccion_id).filter(
+                    PlanillaDeduccion.planilla_id == planilla.id,
+                    PlanillaDeduccion.activo.is_(True),
+                )
+            )
+            .scalars()
+            .all()
+        )
+
+        if deducciones_ids:
+            deducciones = (
+                self.session.execute(
+                    db.select(Deduccion).filter(
+                        Deduccion.id.in_(deducciones_ids),
+                        Deduccion.activo.is_(True),
+                    )
+                )
+                .scalars()
+                .all()
+            )
+        else:
+            deducciones = []
+
+        for d in deducciones:
+            snapshot["deducciones"].append(
+                {
+                    "id": d.id,
+                    "codigo": d.codigo,
+                    "nombre": d.nombre,
+                    "descripcion": d.descripcion,
+                    "formula_tipo": d.formula_tipo,
+                    "formula": d.formula,
+                    "monto_default": str(d.monto_default) if d.monto_default else None,
+                    "porcentaje": str(d.porcentaje) if d.porcentaje else None,
+                    "antes_impuesto": d.antes_impuesto,
+                    "base_calculo": d.base_calculo,
+                    "estado_aprobacion": d.estado_aprobacion,
+                }
+            )
+
+        # Capture Prestaciones linked to this planilla
+        from coati_payroll.model import PlanillaPrestacion
+
+        prestaciones_ids = (
+            self.session.execute(
+                db.select(PlanillaPrestacion.prestacion_id).filter(
+                    PlanillaPrestacion.planilla_id == planilla.id,
+                    PlanillaPrestacion.activo.is_(True),
+                )
+            )
+            .scalars()
+            .all()
+        )
+
+        if prestaciones_ids:
+            prestaciones = (
+                self.session.execute(
+                    db.select(Prestacion).filter(
+                        Prestacion.id.in_(prestaciones_ids),
+                        Prestacion.activo.is_(True),
+                    )
+                )
+                .scalars()
+                .all()
+            )
+        else:
+            prestaciones = []
+
+        for pr in prestaciones:
+            snapshot["prestaciones"].append(
+                {
+                    "id": pr.id,
+                    "codigo": pr.codigo,
+                    "nombre": pr.nombre,
+                    "descripcion": pr.descripcion,
+                    "formula_tipo": pr.formula_tipo,
+                    "formula": pr.formula,
+                    "monto_default": str(pr.monto_default) if pr.monto_default else None,
+                    "porcentaje": str(pr.porcentaje) if pr.porcentaje else None,
+                    "base_calculo": pr.base_calculo,
+                    "tipo_acumulacion": pr.tipo_acumulacion,
+                    "estado_aprobacion": pr.estado_aprobacion,
+                }
+            )
+
+        return snapshot
+
+    def capture_complete_snapshot(self, planilla: Planilla, fecha_calculo: date) -> dict[str, Any]:
+        """Capture complete snapshot of all configuration data.
+
+        Args:
+            planilla: Planilla being processed
+            fecha_calculo: Calculation date
+
+        Returns:
+            Complete snapshot dictionary
+        """
+        return {
+            "configuracion": self.capture_configuration_snapshot(planilla.empresa_id),
+            "tipos_cambio": self.capture_exchange_rates_snapshot(planilla, fecha_calculo),
+            "catalogos": self.capture_catalogs_snapshot(planilla),
+            "fecha_captura": fecha_calculo.isoformat(),
+        }

coati_payroll/nomina_engine/validators/__init__.py

@@ -0,0 +1,31 @@
+# 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.
+"""Validators for payroll processing."""
+
+from .base_validator import BaseValidator, NominaEngineError, ValidationError, CalculationError
+from .planilla_validator import PlanillaValidator
+from .employee_validator import EmployeeValidator
+from .period_validator import PeriodValidator
+from .currency_validator import CurrencyValidator
+
+__all__ = [
+    "BaseValidator",
+    "NominaEngineError",
+    "ValidationError",
+    "CalculationError",
+    "PlanillaValidator",
+    "EmployeeValidator",
+    "PeriodValidator",
+    "CurrencyValidator",
+]

coati_payroll/nomina_engine/validators/base_validator.py

@@ -0,0 +1,48 @@
+# 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.
+"""Base validator interface and exceptions."""
+
+from __future__ import annotations
+
+from abc import ABC, abstractmethod
+
+from ..domain.payroll_context import PayrollContext
+from ..results.validation_result import ValidationResult
+
+
+class NominaEngineError(Exception):
+    """Base exception for payroll engine errors."""
+
+    pass
+
+
+class ValidationError(NominaEngineError):
+    """Exception for validation errors."""
+
+    pass
+
+
+class CalculationError(NominaEngineError):
+    """Exception for calculation errors."""
+
+    pass
+
+
+class BaseValidator(ABC):
+    """Base validator interface."""
+
+    @abstractmethod
+    def validate(self, context: PayrollContext) -> ValidationResult:
+        """Validate the given context."""
+        pass

coati_payroll/nomina_engine/validators/currency_validator.py

@@ -0,0 +1,50 @@
+# 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.
+"""Validator for currency and exchange rates."""
+
+from __future__ import annotations
+
+from datetime import date
+
+from ..domain.payroll_context import PayrollContext
+from ..results.validation_result import ValidationResult
+from ..validators.base_validator import BaseValidator
+from ..repositories.exchange_rate_repository import ExchangeRateRepository
+
+
+class CurrencyValidator(BaseValidator):
+    """Validates currency and exchange rate availability."""
+
+    def __init__(self, exchange_rate_repository: ExchangeRateRepository):
+        self.exchange_rate_repo = exchange_rate_repository
+
+    def validate(self, context: PayrollContext) -> ValidationResult:
+        """Validate currency - this is a placeholder as currency validation is done per-employee."""
+        result = ValidationResult()
+        return result
+
+    def validate_exchange_rate(self, moneda_origen_id: str, moneda_destino_id: str, fecha: date) -> ValidationResult:
+        """Validate that exchange rate exists for currency pair."""
+        result = ValidationResult()
+
+        if moneda_origen_id == moneda_destino_id:
+            return result  # Same currency, no exchange rate needed
+
+        rate = self.exchange_rate_repo.get_rate(moneda_origen_id, moneda_destino_id, fecha)
+        if rate is None:
+            result.add_error(
+                f"No se encontró tipo de cambio de {moneda_origen_id} a {moneda_destino_id} para la fecha {fecha}"
+            )
+
+        return result

coati_payroll/nomina_engine/validators/employee_validator.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.
+"""Validator for Employee."""
+
+from __future__ import annotations
+
+from datetime import date
+from decimal import Decimal
+
+from coati_payroll.model import Empleado
+from ..domain.payroll_context import PayrollContext
+from ..results.validation_result import ValidationResult
+from ..validators.base_validator import BaseValidator
+
+
+class EmployeeValidator(BaseValidator):
+    """Validates that an employee is eligible for payroll processing."""
+
+    def validate(self, context: PayrollContext) -> ValidationResult:
+        """Validate employee - this method signature is required by BaseValidator."""
+        # This validator is called per-employee, not per-context
+        # So we provide a separate method
+        result = ValidationResult()
+        return result
+
+    def validate_employee(
+        self, empleado: Empleado, planilla_empresa_id: str | None, periodo_inicio: date, periodo_fin: date
+    ) -> ValidationResult:
+        """Validate employee for payroll processing."""
+        result = ValidationResult()
+
+        if not empleado.activo:
+            result.add_error(f"Empleado {empleado.codigo_empleado} no está activo")
+
+        if empleado.fecha_alta:
+            if empleado.fecha_alta > date.today():
+                result.add_error(
+                    f"Empleado {empleado.codigo_empleado}: fecha de ingreso ({empleado.fecha_alta}) "
+                    f"es posterior a la fecha actual"
+                )
+            if empleado.fecha_alta > periodo_fin:
+                result.add_error(
+                    f"Empleado {empleado.codigo_empleado}: fecha de ingreso ({empleado.fecha_alta}) "
+                    f"es posterior al período a procesar ({periodo_fin})"
+                )
+        else:
+            result.add_error(f"Empleado {empleado.codigo_empleado} no tiene fecha de ingreso definida")
+
+        if empleado.fecha_baja and empleado.fecha_baja < periodo_inicio:
+            result.add_error(
+                f"Empleado {empleado.codigo_empleado}: fecha de salida ({empleado.fecha_baja}) "
+                f"es anterior al inicio del período ({periodo_inicio})"
+            )
+
+        if not empleado.identificacion_personal:
+            result.add_error(f"Empleado {empleado.codigo_empleado} no tiene identificación personal")
+
+        if empleado.salario_base <= Decimal("0.00"):
+            result.add_error(
+                f"Empleado {empleado.codigo_empleado} tiene salario base inválido ({empleado.salario_base})"
+            )
+
+        if not empleado.empresa_id:
+            result.add_error(f"Empleado {empleado.codigo_empleado} no está asignado a ninguna empresa")
+
+        if planilla_empresa_id and empleado.empresa_id:
+            if empleado.empresa_id != planilla_empresa_id:
+                result.add_error(
+                    f"Empleado {empleado.codigo_empleado} pertenece a empresa diferente a la planilla. "
+                    f"Empleado empresa_id={empleado.empresa_id}, Planilla empresa_id={planilla_empresa_id}"
+                )
+
+        if not empleado.moneda_id:
+            result.add_error(f"Empleado {empleado.codigo_empleado} no tiene moneda definida")
+
+        return result

coati_payroll/nomina_engine/validators/period_validator.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.
+"""Validator for payroll period."""
+
+from __future__ import annotations
+
+
+from ..domain.payroll_context import PayrollContext
+from ..results.validation_result import ValidationResult
+from ..validators.base_validator import BaseValidator
+
+
+class PeriodValidator(BaseValidator):
+    """Validates payroll period."""
+
+    def validate(self, context: PayrollContext) -> ValidationResult:
+        """Validate period."""
+        result = ValidationResult()
+
+        if context.periodo_inicio > context.periodo_fin:
+            result.add_error(
+                f"Período inválido: inicio ({context.periodo_inicio}) posterior a fin ({context.periodo_fin})"
+            )
+
+        dias_periodo = (context.periodo_fin - context.periodo_inicio).days + 1
+        if dias_periodo <= 0:
+            result.add_error("El período debe tener al menos un día.")
+        elif dias_periodo > 366:
+            result.add_error(
+                f"Período excesivamente largo: {dias_periodo} días. Los períodos no deben exceder 366 días."
+            )
+
+        return result