coati-payroll 0.0.2__py3-none-any.whl

coati_payroll/liquidacion_engine/engine.py

@@ -0,0 +1,267 @@
+# 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.
+
+"""Liquidación engine orchestrator."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from datetime import date, timedelta
+from decimal import Decimal
+
+from sqlalchemy import select
+
+from coati_payroll.enums import NominaEstado
+from coati_payroll.model import (
+    ConfiguracionCalculos,
+    Empleado,
+    Liquidacion,
+    LiquidacionDetalle,
+    Nomina,
+    NominaEmpleado,
+    AdelantoAbono,
+    Adelanto,
+    db,
+)
+from coati_payroll.nomina_engine.repositories.config_repository import ConfigRepository
+from coati_payroll.nomina_engine.processors.loan_processor import LoanProcessor
+
+
+@dataclass(frozen=True)
+class LiquidacionResult:
+    liquidacion: Liquidacion | None
+    errors: list[str]
+    warnings: list[str]
+
+
+class LiquidacionEngine:
+    """Engine for calculating employee termination settlements (liquidaciones)."""
+
+    def __init__(self, empleado: Empleado, fecha_calculo: date | None = None, usuario: str | None = None):
+        self.empleado = empleado
+        self.fecha_calculo = fecha_calculo or date.today()
+        self.usuario = usuario
+        self.errors: list[str] = []
+        self.warnings: list[str] = []
+
+        self._config_repo = ConfigRepository(db.session)
+
+    def _get_config(self) -> ConfiguracionCalculos:
+        return self._config_repo.get_for_empresa(self.empleado.empresa_id)
+
+    def determinar_ultimo_dia_pagado(self) -> date:
+        """Get the last day covered by the employee's last applied/paid payroll."""
+        stmt = (
+            select(Nomina.periodo_fin)
+            .join(NominaEmpleado, NominaEmpleado.nomina_id == Nomina.id)
+            .where(
+                NominaEmpleado.empleado_id == self.empleado.id,
+                Nomina.estado.in_([NominaEstado.APLICADO, NominaEstado.PAGADO]),
+            )
+            .order_by(Nomina.periodo_fin.desc())
+            .limit(1)
+        )
+
+        ultimo = db.session.execute(stmt).scalar_one_or_none()
+        if ultimo:
+            return ultimo
+
+        fecha_alta = self.empleado.fecha_alta
+        if not fecha_alta:
+            self.warnings.append("Empleado sin fecha de alta; usando fecha de cálculo como referencia.")
+            return self.fecha_calculo
+
+        return fecha_alta - timedelta(days=1)
+
+    def _get_factor_dias(self, config: ConfiguracionCalculos) -> int:
+        modo = (config.liquidacion_modo_dias or "calendario").strip().lower()
+        if modo == "laboral":
+            return int(config.liquidacion_factor_laboral or 28)
+        return int(config.liquidacion_factor_calendario or 30)
+
+    def calcular(self, liquidacion: Liquidacion) -> Liquidacion | None:
+        """Calculate a liquidacion record in-place."""
+        config = self._get_config()
+
+        ultimo_dia_pagado = self.determinar_ultimo_dia_pagado()
+        liquidacion.ultimo_dia_pagado = ultimo_dia_pagado
+        liquidacion.fecha_calculo = self.fecha_calculo
+
+        if self.fecha_calculo <= ultimo_dia_pagado:
+            liquidacion.dias_por_pagar = 0
+            self.warnings.append("La fecha de cálculo es menor o igual al último día pagado.")
+        else:
+            liquidacion.dias_por_pagar = (self.fecha_calculo - ultimo_dia_pagado).days
+
+        # Clear previous details (support recalculation)
+        liquidacion.detalles.clear()
+
+        # Income for pending days
+        factor_dias = self._get_factor_dias(config)
+        salario_mensual = Decimal(str(self.empleado.salario_base or 0))
+        if factor_dias <= 0:
+            self.errors.append("Factor de días inválido en configuración.")
+            return None
+
+        tasa_dia = (salario_mensual / Decimal(str(factor_dias))).quantize(Decimal("0.01"))
+        monto_dias = (tasa_dia * Decimal(str(liquidacion.dias_por_pagar))).quantize(Decimal("0.01"))
+
+        if liquidacion.dias_por_pagar > 0 and monto_dias > 0:
+            liquidacion.detalles.append(
+                LiquidacionDetalle(
+                    tipo="ingreso",
+                    codigo="DIAS_POR_PAGAR",
+                    descripcion="Días por pagar",
+                    monto=monto_dias,
+                    orden=1,
+                )
+            )
+
+        # Apply pending loans/advances as deductions
+        saldo_disponible = monto_dias
+        loan_processor = LoanProcessor(
+            nomina=None,
+            fecha_calculo=self.fecha_calculo,
+            periodo_inicio=ultimo_dia_pagado,
+            periodo_fin=self.fecha_calculo,
+            liquidacion=liquidacion,
+            calcular_interes=False,
+        )
+
+        # Defaults match Planilla priorities; liquidation uses fixed priorities for now
+        deducciones = []
+        deducciones.extend(
+            loan_processor.process_loans(
+                empleado_id=self.empleado.id,
+                saldo_disponible=saldo_disponible,
+                aplicar_prestamos=True,
+                prioridad_prestamos=250,
+            )
+        )
+        for d in deducciones:
+            saldo_disponible -= d.monto
+
+        deducciones_adv = loan_processor.process_advances(
+            empleado_id=self.empleado.id,
+            saldo_disponible=saldo_disponible,
+            aplicar_adelantos=True,
+            prioridad_adelantos=251,
+        )
+        deducciones.extend(deducciones_adv)
+
+        orden = 1
+        total_deducciones = Decimal("0.00")
+        for item in deducciones:
+            orden += 1
+            total_deducciones += item.monto
+            liquidacion.detalles.append(
+                LiquidacionDetalle(
+                    tipo="deduccion",
+                    codigo=item.codigo,
+                    descripcion=item.nombre,
+                    monto=item.monto,
+                    orden=orden,
+                )
+            )
+
+        total_bruto = monto_dias
+        total_neto = (total_bruto - total_deducciones).quantize(Decimal("0.01"))
+        liquidacion.total_bruto = total_bruto
+        liquidacion.total_deducciones = total_deducciones
+        liquidacion.total_neto = total_neto
+
+        liquidacion.errores_calculo = {"errors": self.errors} if self.errors else {}
+        liquidacion.advertencias_calculo = list(self.warnings)
+
+        return liquidacion
+
+
+def recalcular_liquidacion(liquidacion_id: str, fecha_calculo: date | None = None, usuario: str | None = None):
+    """Recalculate an existing liquidacion.
+
+    - Removes existing details
+    - Reverts any AdelantoAbono records created by this liquidation
+    - Re-runs calculation
+    """
+    liquidacion = db.session.get(Liquidacion, liquidacion_id)
+    if not liquidacion:
+        return None, ["Liquidación no encontrada."], []
+
+    if liquidacion.estado != "borrador":
+        return None, ["Solo se pueden recalcular liquidaciones en borrador."], []
+
+    empleado = db.session.get(Empleado, liquidacion.empleado_id)
+    if not empleado:
+        return None, ["Empleado no encontrado."], []
+
+    # Revert loan/advance payments applied by this liquidation
+    abonos = (
+        db.session.execute(select(AdelantoAbono).where(AdelantoAbono.liquidacion_id == liquidacion.id)).scalars().all()
+    )
+
+    for abono in abonos:
+        adelanto = db.session.get(Adelanto, abono.adelanto_id)
+        if adelanto:
+            # Undo the payment (add back to saldo)
+            adelanto.saldo_pendiente = (
+                Decimal(str(adelanto.saldo_pendiente)) + Decimal(str(abono.monto_abonado))
+            ).quantize(Decimal("0.01"))
+            if adelanto.saldo_pendiente > 0 and adelanto.estado == "pagado":
+                adelanto.estado = "aprobado"
+        db.session.delete(abono)
+
+    # Remove existing details
+    liquidacion.detalles.clear()
+
+    engine = LiquidacionEngine(
+        empleado=empleado, fecha_calculo=fecha_calculo or liquidacion.fecha_calculo, usuario=usuario
+    )
+    calculated = engine.calcular(liquidacion)
+    if not calculated:
+        db.session.rollback()
+        return None, engine.errors, engine.warnings
+
+    db.session.commit()
+    return calculated, engine.errors, engine.warnings
+
+
+def ejecutar_liquidacion(
+    empleado_id: str,
+    concepto_id: str | None,
+    fecha_calculo: date | None = None,
+    usuario: str | None = None,
+) -> tuple[Liquidacion | None, list[str], list[str]]:
+    """Convenience function to create and calculate a liquidacion."""
+    empleado = db.session.get(Empleado, empleado_id)
+    if not empleado:
+        return None, ["Empleado no encontrado."], []
+
+    liquidacion = Liquidacion(
+        empleado_id=empleado.id,
+        concepto_id=concepto_id,
+        fecha_calculo=fecha_calculo or date.today(),
+        estado="borrador",
+    )
+    db.session.add(liquidacion)
+    db.session.flush()
+
+    engine = LiquidacionEngine(empleado=empleado, fecha_calculo=fecha_calculo, usuario=usuario)
+    calculated = engine.calcular(liquidacion)
+
+    if not calculated:
+        db.session.rollback()
+        return None, engine.errors, engine.warnings
+
+    db.session.commit()
+    return calculated, engine.errors, engine.warnings

coati_payroll/locale_config.py

@@ -0,0 +1,165 @@
+# 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.
+"""Language configuration and caching for internationalization."""
+
+from __future__ import annotations
+
+# <-------------------------------------------------------------------------> #
+# Standard library
+# <-------------------------------------------------------------------------> #
+from os import environ
+from threading import Lock
+
+# <-------------------------------------------------------------------------> #
+# Third party libraries
+# <-------------------------------------------------------------------------> #
+from flask import current_app
+
+# <-------------------------------------------------------------------------> #
+# Local modules
+# <-------------------------------------------------------------------------> #
+from coati_payroll.log import log
+
+# Supported languages
+SUPPORTED_LANGUAGES = ["en", "es"]
+DEFAULT_LANGUAGE = "en"
+
+# Cache for language setting with thread-safe access
+_language_cache = None
+_cache_lock = Lock()
+
+
+def get_language_from_db() -> str:
+    """Get the configured language from the database.
+
+    Returns the language code ('en' or 'es') from the global configuration table.
+    If no configuration exists, returns the default language.
+    Uses caching to avoid repeated database queries.
+
+    Returns:
+        str: Language code ('en' or 'es')
+    """
+    global _language_cache
+
+    # Check cache first (thread-safe)
+    with _cache_lock:
+        if _language_cache is not None:
+            return _language_cache
+
+    # Cache miss - query database
+    try:
+        from coati_payroll.model import ConfiguracionGlobal, db
+
+        with current_app.app_context():
+            config = db.session.execute(db.select(ConfiguracionGlobal)).scalar_one_or_none()
+
+            if config and config.idioma in SUPPORTED_LANGUAGES:
+                language = config.idioma
+            else:
+                language = DEFAULT_LANGUAGE
+
+            # Update cache (thread-safe)
+            with _cache_lock:
+                _language_cache = language
+
+            log.trace(f"Language loaded from database: {language}")
+            return language
+
+    except Exception as e:
+        log.warning(f"Error reading language from database: {e}")
+        return DEFAULT_LANGUAGE
+
+
+def set_language_in_db(language: str) -> None:
+    """Set the configured language in the database.
+
+    Updates the language setting in the global configuration table and
+    invalidates the cache to ensure the change is immediately reflected.
+
+    Args:
+        language: Language code ('en' or 'es')
+
+    Raises:
+        ValueError: If language is not supported
+    """
+    if language not in SUPPORTED_LANGUAGES:
+        raise ValueError(f"Unsupported language: {language}. Must be one of {SUPPORTED_LANGUAGES}")
+
+    from coati_payroll.model import ConfiguracionGlobal, db
+
+    with current_app.app_context():
+        config = db.session.execute(db.select(ConfiguracionGlobal)).scalar_one_or_none()
+
+        if config:
+            config.idioma = language
+        else:
+            # Create new configuration record
+            config = ConfiguracionGlobal()
+            config.idioma = language
+            db.session.add(config)
+
+        db.session.commit()
+
+        # Invalidate cache to force reload on next access
+        invalidate_language_cache()
+
+        log.info(f"Language updated to: {language}")
+
+
+def invalidate_language_cache() -> None:
+    """Invalidate the language cache.
+
+    Forces the next call to get_language_from_db() to query the database.
+    Call this after updating the language setting.
+    """
+    global _language_cache
+
+    with _cache_lock:
+        _language_cache = None
+
+    log.trace("Language cache invalidated")
+
+
+def initialize_language_from_env() -> None:
+    """Initialize language from COATI_LANG environment variable.
+
+    Called during application startup to set the initial language from
+    the environment variable if provided. Only updates the database if
+    no configuration exists yet.
+    """
+    env_lang = environ.get("COATI_LANG", "").strip().lower()
+
+    if not env_lang:
+        return
+
+    if env_lang not in SUPPORTED_LANGUAGES:
+        log.warning(f"Invalid COATI_LANG value: {env_lang}. " f"Must be one of {SUPPORTED_LANGUAGES}. Using default.")
+        return
+
+    try:
+        from coati_payroll.model import ConfiguracionGlobal, db
+
+        with current_app.app_context():
+            config = db.session.execute(db.select(ConfiguracionGlobal)).scalar_one_or_none()
+
+            # Only set from environment if no config exists yet
+            if not config:
+                config = ConfiguracionGlobal()
+                config.idioma = env_lang
+                db.session.add(config)
+                db.session.commit()
+                log.info(f"Language initialized from COATI_LANG: {env_lang}")
+
+    except Exception as e:
+        log.warning(f"Error initializing language from environment: {e}")

coati_payroll/log.py

@@ -0,0 +1,138 @@
+# Copyright 2022 - 2024 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.
+#
+"""Configuración de logs."""
+
+from __future__ import annotations
+
+# <-------------------------------------------------------------------------> #
+# Standard library
+# <-------------------------------------------------------------------------> #
+import logging
+from os import environ
+from sys import stdout
+
+# <-------------------------------------------------------------------------> #
+# Third-party libraries
+# <-------------------------------------------------------------------------> #
+
+# <-------------------------------------------------------------------------> #
+# Local modules
+# <-------------------------------------------------------------------------> #
+
+# Definir nivel TRACE
+TRACE_LEVEL_NUM = 5
+logging.addLevelName(TRACE_LEVEL_NUM, "TRACE")
+
+
+# Método adicional para usar logger.trace(...)
+def trace(self, message, *args, **kwargs):
+    """Log a message with TRACE level."""
+    if self.isEnabledFor(TRACE_LEVEL_NUM):
+        self._log(TRACE_LEVEL_NUM, message, args, **kwargs)
+
+
+logging.Logger.trace = trace
+
+# Configurar nivel desde variable de entorno (default: INFO)
+log_level_str = environ.get("LOG_LEVEL", "INFO").upper()
+
+# Soporte de niveles personalizados
+custom_levels = {
+    "TRACE": TRACE_LEVEL_NUM,
+    "DEBUG": logging.DEBUG,
+    "INFO": logging.INFO,
+    "WARNING": logging.WARNING,
+    "ERROR": logging.ERROR,
+    "CRITICAL": logging.CRITICAL,
+}
+
+# Nivel numérico, default INFO si no coincide
+numeric_level = custom_levels.get(log_level_str, logging.INFO)
+
+# Configurar logger raíz
+root_logger = logging.getLogger("now_lms")
+root_logger.setLevel(numeric_level)
+
+# Handler solo para stdout
+console_handler = logging.StreamHandler(stdout)
+console_handler.setLevel(numeric_level)
+formatter = logging.Formatter("%(asctime)s - %(name)s - %(levelname)s: %(message)s")
+console_handler.setFormatter(formatter)
+root_logger.addHandler(console_handler)
+
+# Configurar logger de Flask y Werkzeug al mismo nivel
+logging.getLogger("flask").setLevel(numeric_level)
+logging.getLogger("werkzeug").setLevel(numeric_level)
+
+# Configurar logger de SQLAlchemy al nivel WARNING
+logging.getLogger("sqlalchemy").setLevel(logging.WARNING)
+
+LOG_LEVEL = root_logger.getEffectiveLevel()
+
+log = root_logger
+logger = root_logger
+
+
+# Cached helper to avoid repeated debug/level checks on every trace call
+_TRACE_ACTIVE: bool | None = None
+
+
+def _compute_trace_active(debug_flag: bool | None = None) -> bool:
+    """Compute whether TRACE logging should be emitted.
+
+    Prefers an explicit debug_flag, then Flask's current_app.debug (if available),
+    then FLASK_DEBUG/FLASK_ENV environment hints. Also verifies the logger is
+    actually enabled for TRACE level.
+    """
+
+    # Determine debug flag
+    if debug_flag is None:
+        try:
+            from flask import current_app
+
+            debug_flag = bool(getattr(current_app, "debug", False))
+        except Exception:
+            debug_flag = False
+
+    if not debug_flag:
+        debug_env = environ.get("FLASK_DEBUG") or environ.get("FLASK_ENV")
+        if debug_env:
+            debug_flag = str(debug_env).lower() in {
+                "1",
+                "true",
+                "yes",
+                "on",
+                "development",
+                "dev",
+                "debug",
+            }
+
+    try:
+        return bool(debug_flag) and log.isEnabledFor(TRACE_LEVEL_NUM)
+    except Exception:
+        return False
+
+
+def is_trace_enabled(*, force_refresh: bool = False, debug_flag: bool | None = None) -> bool:
+    """Return cached TRACE-enabled flag, computing once unless refreshed.
+
+    This keeps per-log-call overhead minimal while allowing an explicit refresh
+    if runtime configuration changes.
+    """
+
+    global _TRACE_ACTIVE
+    if force_refresh or _TRACE_ACTIVE is None:
+        _TRACE_ACTIVE = _compute_trace_active(debug_flag)
+    return _TRACE_ACTIVE