coati-payroll 0.0.2__py3-none-any.whl

coati_payroll/nomina_engine/validators/planilla_validator.py

@@ -0,0 +1,136 @@
+# 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 Planilla."""
+
+from __future__ import annotations
+
+from sqlalchemy import or_, and_
+
+from coati_payroll.audit_helpers import obtener_conceptos_en_borrador
+from coati_payroll.model import Nomina
+from coati_payroll.enums import NominaEstado
+from ..domain.payroll_context import PayrollContext
+from ..results.validation_result import ValidationResult
+from ..validators.base_validator import BaseValidator
+from ..repositories.planilla_repository import PlanillaRepository
+
+
+class PlanillaValidator(BaseValidator):
+    """Validates that a planilla is ready for execution."""
+
+    def __init__(self, planilla_repository: PlanillaRepository):
+        self.planilla_repo = planilla_repository
+
+    def validate(self, context: PayrollContext) -> ValidationResult:
+        """Validate planilla."""
+        result = ValidationResult()
+
+        planilla = self.planilla_repo.get_by_id(context.planilla_id)
+        if not planilla:
+            result.add_error("La planilla no existe.")
+            return result
+
+        if not planilla.activo:
+            result.add_error("La planilla no está activa.")
+
+        if not planilla.planilla_empleados:
+            result.add_error("La planilla no tiene empleados asignados.")
+
+        if not planilla.tipo_planilla:
+            result.add_error("La planilla no tiene tipo de planilla configurado.")
+
+        if not planilla.moneda:
+            result.add_error("La planilla no tiene moneda configurada.")
+
+        # Validate period not duplicated
+        if not self._validate_periodo_no_duplicado(planilla, context):
+            result.add_error("El período se solapa con una nómina existente.")
+
+        # Check for draft concepts and add warnings (not errors - allow test runs)
+        self._check_draft_concepts(planilla, result)
+
+        return result
+
+    def _validate_periodo_no_duplicado(self, planilla, context: PayrollContext) -> bool:
+        """Validate that period doesn't overlap with existing nominas."""
+        from sqlalchemy import select
+
+        existing = (
+            self.planilla_repo.session.execute(
+                select(Nomina).filter(
+                    Nomina.planilla_id == planilla.id,
+                    Nomina.estado.in_(
+                        [
+                            NominaEstado.GENERADO,
+                            NominaEstado.APROBADO,
+                            NominaEstado.APLICADO,
+                            NominaEstado.PAGADO,
+                        ]
+                    ),
+                    or_(
+                        # Existing start falls within our period
+                        and_(
+                            Nomina.periodo_inicio >= context.periodo_inicio,
+                            Nomina.periodo_inicio <= context.periodo_fin,
+                        ),
+                        # Existing end falls within our period
+                        and_(
+                            Nomina.periodo_fin >= context.periodo_inicio,
+                            Nomina.periodo_fin <= context.periodo_fin,
+                        ),
+                        # Our period is completely within existing period
+                        and_(
+                            Nomina.periodo_inicio <= context.periodo_inicio,
+                            Nomina.periodo_fin >= context.periodo_fin,
+                        ),
+                    ),
+                )
+            )
+            .scalars()
+            .first()
+        )
+
+        return existing is None
+
+    def _check_draft_concepts(self, planilla, result: ValidationResult) -> None:
+        """Check for draft concepts and add warnings.
+
+        Draft concepts are allowed in payroll runs (for testing), but we warn
+        the user to carefully validate results.
+        """
+        conceptos_borrador = obtener_conceptos_en_borrador(planilla.id)
+
+        if conceptos_borrador["percepciones"]:
+            percepciones_nombres = [p.nombre for p in conceptos_borrador["percepciones"]]
+            result.add_warning(
+                f"ADVERTENCIA: {len(percepciones_nombres)} percepción(es) en estado BORRADOR: "
+                f"{', '.join(percepciones_nombres)}. "
+                "Valide cuidadosamente los resultados de la nómina."
+            )
+
+        if conceptos_borrador["deducciones"]:
+            deducciones_nombres = [d.nombre for d in conceptos_borrador["deducciones"]]
+            result.add_warning(
+                f"ADVERTENCIA: {len(deducciones_nombres)} deducción(es) en estado BORRADOR: "
+                f"{', '.join(deducciones_nombres)}. "
+                "Valide cuidadosamente los resultados de la nómina."
+            )
+
+        if conceptos_borrador["prestaciones"]:
+            prestaciones_nombres = [p.nombre for p in conceptos_borrador["prestaciones"]]
+            result.add_warning(
+                f"ADVERTENCIA: {len(prestaciones_nombres)} prestación(es) en estado BORRADOR: "
+                f"{', '.join(prestaciones_nombres)}. "
+                "Valide cuidadosamente los resultados de la nómina."
+            )

coati_payroll/plugin_manager.py

@@ -0,0 +1,176 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+from importlib import import_module
+from importlib.metadata import distributions
+
+from flask import Flask
+
+from coati_payroll.log import log
+from coati_payroll.model import PluginRegistry, db
+
+
+PLUGIN_DISTRIBUTION_PREFIX = "coati-payroll-plugin-"
+
+
+@dataclass(frozen=True)
+class DiscoveredPlugin:
+    distribution_name: str
+    plugin_id: str
+    version: str | None
+
+
+def _distribution_to_plugin_id(distribution_name: str) -> str:
+    if not distribution_name.startswith(PLUGIN_DISTRIBUTION_PREFIX):
+        return distribution_name
+    return distribution_name[len(PLUGIN_DISTRIBUTION_PREFIX) :]
+
+
+def _plugin_id_to_module_name(plugin_id: str) -> str:
+    return f"coati_payroll_plugin_{plugin_id.replace('-', '_')}"
+
+
+def discover_installed_plugins() -> list[DiscoveredPlugin]:
+    found: list[DiscoveredPlugin] = []
+
+    for dist in distributions():
+        name = (dist.metadata.get("Name") or "").strip()
+        if not name or not name.startswith(PLUGIN_DISTRIBUTION_PREFIX):
+            continue
+
+        plugin_id = _distribution_to_plugin_id(name)
+        version = (dist.version or "").strip() or None
+        found.append(DiscoveredPlugin(distribution_name=name, plugin_id=plugin_id, version=version))
+
+    found.sort(key=lambda p: p.distribution_name)
+    return found
+
+
+def sync_plugin_registry() -> None:
+    installed = {p.distribution_name: p for p in discover_installed_plugins()}
+
+    rows = db.session.execute(db.select(PluginRegistry)).scalars().all()
+    by_name = {r.distribution_name: r for r in rows}
+
+    changed = False
+
+    for name, plugin in installed.items():
+        if name in by_name:
+            if by_name[name].plugin_id != plugin.plugin_id:
+                by_name[name].plugin_id = plugin.plugin_id
+                changed = True
+            if by_name[name].version != plugin.version:
+                by_name[name].version = plugin.version
+                changed = True
+            if by_name[name].installed is not True:
+                by_name[name].installed = True
+                changed = True
+            continue
+
+        record = PluginRegistry()
+        record.distribution_name = name
+        record.plugin_id = plugin.plugin_id
+        record.version = plugin.version
+        record.active = False
+        record.installed = True
+        db.session.add(record)
+        changed = True
+
+    for name, record in by_name.items():
+        if name in installed:
+            continue
+        if record.installed is not False:
+            record.installed = False
+            changed = True
+        if record.active:
+            record.active = False
+            changed = True
+
+    if changed:
+        db.session.commit()
+
+
+def _load_plugin_module(distribution_name: str, plugin_id: str):
+    module_name = _plugin_id_to_module_name(plugin_id)
+    try:
+        return import_module(module_name)
+    except ModuleNotFoundError as exc:
+        raise ModuleNotFoundError(
+            f"Plugin '{distribution_name}' is installed but does not provide module '{module_name}'."
+        ) from exc
+
+
+def load_plugin_module(plugin_id: str):
+    module_name = _plugin_id_to_module_name(plugin_id)
+    return import_module(module_name)
+
+
+def register_active_plugins(app: Flask) -> None:
+    active_plugins = (
+        db.session.execute(db.select(PluginRegistry).filter_by(active=True, installed=True)).scalars().all()
+    )
+
+    for plugin in active_plugins:
+        try:
+            module = _load_plugin_module(plugin.distribution_name, plugin.plugin_id)
+
+            register = getattr(module, "register_blueprints", None)
+            if register is None or not callable(register):
+                raise AttributeError("Missing callable 'register_blueprints(app)'")
+
+            register(app)
+        except (ModuleNotFoundError, AttributeError) as exc:
+            log.warning(f"Plugin '{plugin.distribution_name}' could not be registered: {exc}")
+            plugin.active = False
+            plugin.installed = False
+            try:
+                db.session.commit()
+            except Exception:
+                db.session.rollback()
+        except Exception as exc:
+            log.warning(f"Plugin '{plugin.distribution_name}' failed during registration: {exc}")
+            plugin.active = False
+            try:
+                db.session.commit()
+            except Exception:
+                db.session.rollback()
+
+
+def get_active_plugins_menu_entries() -> list[dict]:
+    active_plugins = (
+        db.session.execute(db.select(PluginRegistry).filter_by(active=True, installed=True)).scalars().all()
+    )
+
+    entries: list[dict] = []
+    for plugin in active_plugins:
+        try:
+            module = _load_plugin_module(plugin.distribution_name, plugin.plugin_id)
+
+            getter = getattr(module, "get_menu_entry", None)
+            if callable(getter):
+                entry = getter()
+            else:
+                entry = getattr(module, "MENU_ENTRY", None)
+
+            if not isinstance(entry, dict):
+                continue
+
+            label = entry.get("label")
+            icon = entry.get("icon")
+            url = entry.get("url")
+            if not label or not url:
+                continue
+
+            entries.append(
+                {
+                    "distribution_name": plugin.distribution_name,
+                    "plugin_id": plugin.plugin_id,
+                    "label": label,
+                    "icon": icon,
+                    "url": url,
+                }
+            )
+        except Exception as exc:
+            log.warning(f"Plugin '{plugin.distribution_name}' menu entry could not be loaded: {exc}")
+
+    return entries

coati_payroll/queue/__init__.py

@@ -0,0 +1,33 @@
+# 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.
+"""Queue module for background job processing.
+
+This module provides a unified interface for background job processing
+with automatic backend selection:
+- Dramatiq + Redis (production/high-scale deployments)
+- Huey + Filesystem (fallback for environments without Redis)
+
+Usage:
+    from coati_payroll.queue import get_queue_driver
+
+    queue = get_queue_driver()
+    queue.enqueue('calculate_employee_payroll', employee_id=123, payroll_id=456)
+"""
+
+from __future__ import annotations
+
+from coati_payroll.queue.driver import QueueDriver
+from coati_payroll.queue.selector import get_queue_driver
+
+__all__ = ["QueueDriver", "get_queue_driver"]

coati_payroll/queue/driver.py

@@ -0,0 +1,127 @@
+# 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.
+"""Abstract base class for queue drivers."""
+
+from __future__ import annotations
+
+from abc import ABC, abstractmethod
+from typing import Any, Callable
+
+
+class QueueDriver(ABC):
+    """Abstract base class for queue drivers.
+
+    All queue implementations (Dramatiq, Huey) must implement this interface
+    to provide a consistent API for background job processing.
+    """
+
+    @abstractmethod
+    def enqueue(self, task_name: str, *args: Any, delay: int | None = None, **kwargs: Any) -> Any:
+        """Enqueue a task for background processing.
+
+        Args:
+            task_name: Name of the task function to execute
+            *args: Positional arguments to pass to the task
+            delay: Optional delay in seconds before task execution
+            **kwargs: Keyword arguments to pass to the task
+
+        Returns:
+            Task identifier or result promise (implementation-specific)
+
+        Raises:
+            NotImplementedError: Must be implemented by subclass
+        """
+        raise NotImplementedError
+
+    @abstractmethod
+    def register_task(
+        self,
+        func: Callable,
+        name: str | None = None,
+        max_retries: int = 3,
+        min_backoff: int = 15000,
+        max_backoff: int = 86400000,
+    ) -> Callable:
+        """Register a function as a background task.
+
+        Args:
+            func: Function to register as a task
+            name: Optional name for the task (defaults to function name)
+            max_retries: Maximum number of retry attempts
+            min_backoff: Minimum backoff time in milliseconds
+            max_backoff: Maximum backoff time in milliseconds
+
+        Returns:
+            Decorated function that can be called normally or enqueued
+
+        Raises:
+            NotImplementedError: Must be implemented by subclass
+        """
+        raise NotImplementedError
+
+    @abstractmethod
+    def is_available(self) -> bool:
+        """Check if this queue driver is available and ready to use.
+
+        Returns:
+            True if driver is available, False otherwise
+        """
+        raise NotImplementedError
+
+    @abstractmethod
+    def get_stats(self) -> dict[str, Any]:
+        """Get queue statistics.
+
+        Returns:
+            Dictionary with queue statistics (pending, processing, completed, etc.)
+        """
+        raise NotImplementedError
+
+    @abstractmethod
+    def get_task_result(self, task_id: Any) -> dict[str, Any]:
+        """Get the result of a task by its ID.
+
+        Args:
+            task_id: Task identifier returned by enqueue()
+
+        Returns:
+            Dictionary with task status and result:
+            {
+                "status": "pending" | "processing" | "completed" | "failed",
+                "result": Any (if completed),
+                "error": str (if failed),
+                "progress": dict (if driver supports it)
+            }
+        """
+        raise NotImplementedError
+
+    @abstractmethod
+    def get_bulk_results(self, task_ids: list[Any]) -> dict[str, Any]:
+        """Get results for multiple tasks (for bulk feedback: x of y completed).
+
+        Args:
+            task_ids: List of task identifiers
+
+        Returns:
+            Dictionary with aggregated status:
+            {
+                "total": int,
+                "completed": int,
+                "failed": int,
+                "pending": int,
+                "processing": int,
+                "tasks": dict[task_id, status]
+            }
+        """
+        raise NotImplementedError

coati_payroll/queue/drivers/__init__.py

@@ -0,0 +1,22 @@
+# 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.
+"""Queue driver implementations."""
+
+from __future__ import annotations
+
+from coati_payroll.queue.drivers.dramatiq_driver import DramatiqDriver
+from coati_payroll.queue.drivers.huey_driver import HueyDriver
+from coati_payroll.queue.drivers.noop_driver import NoopQueueDriver
+
+__all__ = ["DramatiqDriver", "HueyDriver", "NoopQueueDriver"]