sinpapel 0.7.0__py3-none-any.whl

sinpapel/__init__.py

@@ -0,0 +1,25 @@
+"""Sinpapel — Trámites y Workflow reutilizable.
+
+WorkflowEngine se importa explícitamente desde sinpapel.services.workflow_engine
+(no re-exportado aquí porque carga sinpapel.models y rompería el import order
+durante Django app loading).
+"""
+from sinpapel.decorators import workflow_enabled
+from sinpapel.exceptions import (
+    SinpapelError,
+    WorkflowConfigurationError,
+    WorkflowDuplicateKeyError,
+)
+from sinpapel.registry import WorkflowConfig, WorkflowRegistry
+
+__version__ = "0.7.0"
+
+__all__ = [
+    "SinpapelError",
+    "WorkflowConfigurationError",
+    "WorkflowDuplicateKeyError",
+    "WorkflowConfig",
+    "WorkflowRegistry",
+    "workflow_enabled",
+    "__version__",
+]

sinpapel/apps.py

@@ -0,0 +1,19 @@
+"""Sinpapel — App config.
+
+Trámites/workflow reusable extraído desde creditos (E12). Modelos viven en
+sinpapel.models pero las tablas SQL siguen siendo `creditos_*` durante la
+extracción (S12.2 vía db_table override; rename diferido a parking lot).
+"""
+from django.apps import AppConfig
+
+
+class SinpapelConfig(AppConfig):
+    default_auto_field = "django.db.models.BigAutoField"
+    name = "sinpapel"
+    verbose_name = "Sinpapel — Trámites y Workflow"
+
+    def ready(self):
+        # S13.2: registrar signal handlers para invalidación de cache
+        # (post_save/post_delete/m2m_changed sobre Estado/VersionFlujo/
+        # ConfigT/RequisitoEstadoDocumento)
+        from sinpapel import signals  # noqa: F401  side-effect: registers receivers

sinpapel/cache.py

@@ -0,0 +1,169 @@
+"""sinpapel.cache — helpers para cachear catálogos workflow.
+
+S13.1 (E13a): cache layer transparente al motor (WorkflowEngine).
+S13.2 agregará invalidación signal-based (post_save/post_delete).
+
+Behavior:
+- Cache miss → DB query → cache populate → return
+- Cache hit → return desde memoria (0 SQL queries)
+- DB miss (lookup no existe) → return None / [] (NO cachea — D1: no negative caching)
+- Cache backend down → degrada a "siempre miss" (raise nunca)
+
+Settings:
+- SINPAPEL_CACHE_ALIAS: backend name (default 'default')
+- SINPAPEL_CACHE_TIMEOUT: TTL en segundos (default 3600 = 1h)
+
+Usage:
+    from sinpapel.cache import (
+        get_estado_by_name,
+        get_active_version_flujo,
+        get_transitions_for,
+        get_requisitos_for,
+    )
+
+    estado = get_estado_by_name("EN_REVISION")
+    flujo = get_active_version_flujo("solicitud")
+    transitions = get_transitions_for(flujo.id, estado.id)
+
+CAVEAT: Sin S13.2 (signal invalidation), mutaciones admin de Estado/
+VersionFlujo/ConfiguracionTransicion NO invalidan cache automáticamente.
+TTL 1h limita stale data al peor escenario. S13.2 resuelve con signals.
+"""
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+from django.conf import settings
+from django.core.cache import caches
+
+if TYPE_CHECKING:
+    from sinpapel.models import (
+        ConfiguracionTransicion,
+        Estado,
+        RequisitoEstadoDocumento,
+        VersionFlujo,
+    )
+
+
+# Cache key namespace. Hardcoded (D3) — no configurable; sirve como
+# namespace contra otros cache users del consumer (creditos cache, etc.)
+_KEY_PREFIX = "sinpapel"
+
+
+# ─────────────────────────────────────────────────────────────────────────────
+# Settings readers (D9: lazy lookup en cada llamada — override_settings safe)
+# ─────────────────────────────────────────────────────────────────────────────
+
+
+def _cache_alias() -> str:
+    """Backend cache alias. Configurable via SINPAPEL_CACHE_ALIAS."""
+    return getattr(settings, "SINPAPEL_CACHE_ALIAS", "default")
+
+
+def _cache_timeout() -> int:
+    """TTL en segundos. Configurable via SINPAPEL_CACHE_TIMEOUT."""
+    return getattr(settings, "SINPAPEL_CACHE_TIMEOUT", 3600)
+
+
+def _cache():
+    """Retorna el cache backend configurado."""
+    return caches[_cache_alias()]
+
+
+# ─────────────────────────────────────────────────────────────────────────────
+# Helpers (D2: local imports lazy anti-circular con sinpapel.models)
+# ─────────────────────────────────────────────────────────────────────────────
+
+
+def get_estado_by_name(nombre: str) -> "Estado | None":
+    """Get Estado por nombre con cache.
+
+    Returns None si no existe (defensive — D6 reemplaza DoesNotExist).
+    NO cachea None (D1: no negative caching).
+    """
+    key = f"{_KEY_PREFIX}:estado:nombre:{nombre}"
+    cache = _cache()
+    obj = cache.get(key)
+    if obj is None:
+        from sinpapel.models import Estado
+
+        obj = Estado.objects.filter(nombre=nombre).first()
+        if obj is not None:
+            cache.set(key, obj, _cache_timeout())
+    return obj
+
+
+def get_active_version_flujo(workflow_key: str) -> "VersionFlujo | None":
+    """Get VersionFlujo activo (activo=True) por nombre/workflow_key con cache."""
+    key = f"{_KEY_PREFIX}:flujo:active:{workflow_key}"
+    cache = _cache()
+    obj = cache.get(key)
+    if obj is None:
+        from sinpapel.models import VersionFlujo
+
+        obj = VersionFlujo.objects.filter(activo=True, nombre=workflow_key).first()
+        if obj is not None:
+            cache.set(key, obj, _cache_timeout())
+    return obj
+
+
+def get_transitions_for(
+    flujo_id: int,
+    estado_origen_id: int,
+) -> "list[ConfiguracionTransicion]":
+    """Get ConfiguracionTransicion list desde estado_origen en un flujo.
+
+    Lista pre-evaluada con select_related("estado_destino") +
+    prefetch_related("grupos_permitidos") para evitar N+1 queries en callers
+    (engine, permissions S13.6).
+    """
+    key = f"{_KEY_PREFIX}:transitions:{flujo_id}:{estado_origen_id}"
+    cache = _cache()
+    items = cache.get(key)
+    if items is None:
+        from sinpapel.models import ConfiguracionTransicion
+
+        items = list(
+            ConfiguracionTransicion.objects.filter(
+                flujo_id=flujo_id,
+                estado_origen_id=estado_origen_id,
+            )
+            .select_related("estado_destino")
+            .prefetch_related("grupos_permitidos")
+        )
+        cache.set(key, items, _cache_timeout())
+    return items
+
+
+def get_requisitos_for(estado_id: int) -> "list[RequisitoEstadoDocumento]":
+    """Get RequisitoEstadoDocumento list por estado con select_related."""
+    key = f"{_KEY_PREFIX}:requisitos:{estado_id}"
+    cache = _cache()
+    items = cache.get(key)
+    if items is None:
+        from sinpapel.models import RequisitoEstadoDocumento
+
+        items = list(
+            RequisitoEstadoDocumento.objects.filter(estado_id=estado_id)
+            .select_related("tipo_documento")
+        )
+        cache.set(key, items, _cache_timeout())
+    return items
+
+
+# ─────────────────────────────────────────────────────────────────────────────
+# Test/admin helper
+# ─────────────────────────────────────────────────────────────────────────────
+
+
+def clear_all() -> None:
+    """Borra TODO el cache backend (NO solo entries sinpapel:).
+
+    SOLO usar en tests + management commands. NO en producción —
+    invalidación granular llega en S13.2 (signal-based).
+
+    Razón pattern delete: cache.delete_pattern("sinpapel:*") solo soportado
+    por django-redis, no por LocMemCache/Memcached default. cache.clear()
+    es portable (D4). Tests-only scope acepta el blast.
+    """
+    _cache().clear()

sinpapel/decorators.py

@@ -0,0 +1,121 @@
+"""Sinpapel — @workflow_enabled decorator.
+
+Decorator factory que marca un modelo Django como elegible para el motor de
+workflow dinámico (ADR-007). Valida campos requeridos, registra en
+WorkflowRegistry, e inyecta 3 métodos uniformes.
+
+Uso:
+    @workflow_enabled(state_field="estado", workflow_key="solicitud")
+    class Solicitud(Trazable):
+        estado = models.ForeignKey(Estado, ...)
+
+Tras decorar:
+    s = Solicitud.objects.first()
+    s.available_transitions(user)  # lista de Estado destino válidos
+    s.can_transition_to("X", user)  # (bool, str | None)
+    s.transition("X", user, comentarios="...")  # ejecuta transición
+"""
+from __future__ import annotations
+
+import re
+from typing import TYPE_CHECKING
+
+from django.core.exceptions import FieldDoesNotExist
+
+from sinpapel.exceptions import WorkflowConfigurationError
+from sinpapel.injection import (
+    available_transitions,
+    can_transition_to,
+    preview_transition,
+    transition,
+)
+from sinpapel.registry import WorkflowConfig, WorkflowRegistry
+
+if TYPE_CHECKING:
+    from django.db import models
+
+
+# S13.4: endpoint_slug debe ser URL-safe (kebab-case lowercase + digits + hyphens)
+_SLUG_PATTERN = re.compile(r"^[a-z0-9-]+$")
+
+
+def workflow_enabled(
+    *,
+    state_field: str,
+    workflow_key: str,
+    version_field: str | None = None,
+    expose_endpoints: bool = False,
+    endpoint_slug: str | None = None,
+):
+    """Marca un modelo Django como elegible para el motor de workflow dinámico.
+
+    Args:
+        state_field: nombre del FK al modelo sinpapel.Estado (ej. "estado")
+        workflow_key: identificador único del workflow (ej. "solicitud",
+                      "tramite_sep"). Debe ser único en el proyecto.
+        version_field: nombre opcional del FK a sinpapel.VersionFlujo. Si None,
+                      el motor resuelve flujo activo por otra vía (ej. via Producto
+                      en el caso de Solicitud).
+        expose_endpoints: S13.4 — si True, el modelo se incluye en
+                      `WorkflowRegistry.list_exposed()` y sinpapel-drf auto-genera
+                      endpoints REST `/sinpapel/api/<slug>/<pk>/{action}/`.
+                      Default False preserva backward compat.
+        endpoint_slug: S13.4 — URL slug para los endpoints generados (kebab-case,
+                      [a-z0-9-]+). Si None, default = workflow_key + 's'.
+
+    Raises:
+        WorkflowConfigurationError: state_field o version_field no existen en el modelo,
+                                    O endpoint_slug no es URL-safe ([a-z0-9-]+)
+        WorkflowDuplicateKeyError: workflow_key ya está registrado por otro modelo
+
+    Returns:
+        decorator function que retorna la clase decorada (sin alterar la clase
+        más allá de inyectar métodos)
+    """
+    # S13.4 (D9): validar endpoint_slug en factory time, antes del decorator wrapper
+    if endpoint_slug is not None and not _SLUG_PATTERN.match(endpoint_slug):
+        raise WorkflowConfigurationError(
+            f"endpoint_slug '{endpoint_slug}' must match [a-z0-9-]+ "
+            f"(only lowercase letters, digits, hyphens; URL-safe kebab-case)"
+        )
+
+    def decorator(model_class: type["models.Model"]) -> type["models.Model"]:
+        # 1. Validar campos requeridos
+        try:
+            model_class._meta.get_field(state_field)
+        except FieldDoesNotExist as e:
+            raise WorkflowConfigurationError(
+                f"Model {model_class.__name__} has no field '{state_field}' "
+                f"(required by @workflow_enabled state_field=)"
+            ) from e
+
+        if version_field is not None:
+            try:
+                model_class._meta.get_field(version_field)
+            except FieldDoesNotExist as e:
+                raise WorkflowConfigurationError(
+                    f"Model {model_class.__name__} has no field '{version_field}' "
+                    f"(required by @workflow_enabled version_field=)"
+                ) from e
+
+        # 2. Registrar en singleton
+        config = WorkflowConfig(
+            model=model_class,
+            state_field=state_field,
+            workflow_key=workflow_key,
+            version_field=version_field,
+            expose_endpoints=expose_endpoints,
+            endpoint_slug=endpoint_slug,
+        )
+        WorkflowRegistry.register(workflow_key, config)
+
+        # 3. Inyectar métodos + storage del config en la clase
+        model_class._workflow_config = config  # type: ignore[attr-defined]
+        model_class.available_transitions = available_transitions  # type: ignore[attr-defined]
+        model_class.can_transition_to = can_transition_to  # type: ignore[attr-defined]
+        model_class.transition = transition  # type: ignore[attr-defined]
+        model_class.preview_transition = preview_transition  # type: ignore[attr-defined]
+
+        return model_class
+
+    return decorator

sinpapel/exceptions.py

@@ -0,0 +1,22 @@
+"""Sinpapel — Exceptions específicas del paquete."""
+
+
+class SinpapelError(Exception):
+    """Base exception para errores del paquete sinpapel."""
+
+
+class WorkflowConfigurationError(SinpapelError, ValueError):
+    """Raised cuando la configuración de @workflow_enabled es inválida.
+
+    Casos:
+    - state_field no existe en el modelo decorado
+    - version_field se especifica pero no existe en el modelo
+    """
+
+
+class WorkflowDuplicateKeyError(SinpapelError, ValueError):
+    """Raised cuando se intenta registrar dos modelos distintos con el mismo workflow_key.
+
+    Permitido: re-registrar el MISMO modelo con la misma key (idempotente,
+    útil cuando Django re-importa módulos en dev auto-reload).
+    """

sinpapel/forms.py

@@ -0,0 +1,186 @@
+"""Sinpapel — Form/Serializer Factory for MetadatosCapturables.
+
+Generates Django Forms and DRF Serializers dynamically from
+SCHEMA_METADATOS definitions.
+"""
+from __future__ import annotations
+
+from datetime import date
+from decimal import Decimal
+from typing import Any, TypeVar
+
+from django import forms
+from django.utils.translation import gettext_lazy as _
+
+from sinpapel.mixins import CampoMetadato
+
+F = TypeVar("F", bound=forms.Form)
+
+
+class _LazyDRFMap:
+    """Descriptor que carga el mapa DRF bajo demanda."""
+
+    def __get__(
+        self, obj: Any | None, owner: type[Any] | None = None
+    ) -> dict[type, type[Any]]:
+        from rest_framework import serializers
+
+        return {
+            str: serializers.CharField,
+            int: serializers.IntegerField,
+            bool: serializers.BooleanField,
+            Decimal: serializers.DecimalField,
+            date: serializers.DateField,
+        }
+
+
+class MetaFormFactory:
+    """Genera Django Forms / DRF Serializers desde SCHEMA_METADATOS."""
+
+    _DJANGO_FIELD_MAP: dict[type, type[forms.Field]] = {
+        str: forms.CharField,
+        int: forms.IntegerField,
+        bool: forms.BooleanField,
+        Decimal: forms.DecimalField,
+        date: forms.DateField,
+    }
+
+    _DRF_FIELD_MAP: dict[type, type[Any]] = _LazyDRFMap()  # type: ignore[assignment]
+
+    @classmethod
+    def build_form(
+        cls,
+        schema: list[CampoMetadato],
+        name: str | None = None,
+        **form_class_kwargs: Any,
+    ) -> type[F]:
+        """Construye una subclase de django.forms.Form a partir de un schema.
+
+        Nota sobre ``default``:
+            En Django Forms, ``default`` se mapea a ``initial``, lo cual solo
+            pre-rellena el widget. No actúa como valor por omisión real
+            durante la validación. En DRF, ``default`` sí es un valor por
+            omisión verdadero.
+
+        Args:
+            schema: lista de CampoMetadato
+            name: nombre opcional para la clase generada
+            **form_class_kwargs: kwargs adicionales para la clase Form
+
+        Returns:
+            Subclase de forms.Form con los campos definidos
+        """
+        field_names = {c.nombre for c in schema}
+        overlap = field_names & set(form_class_kwargs)
+        if overlap:
+            raise ValueError(
+                f"Los siguientes kwargs colisionan con nombres de campo: {overlap}"
+            )
+
+        attrs: dict[str, forms.Field] = {}
+        for campo in schema:
+            if campo.choices is not None:
+                field_class = forms.ChoiceField
+            else:
+                try:
+                    field_class = cls._DJANGO_FIELD_MAP[campo.tipo]
+                except KeyError:
+                    raise ValueError(f"Tipo no soportado: {campo.tipo}") from None
+            kwargs = cls._build_field_kwargs(campo, is_django=True)
+            attrs[campo.nombre] = field_class(**kwargs)
+
+        class_name = name or (
+            "DynamicMetaForm" if not schema else f"DynamicMetaForm_{schema[0].nombre}"
+        )
+        return type(class_name, (forms.Form,), {**attrs, **form_class_kwargs})
+
+    @classmethod
+    def build_serializer(
+        cls,
+        schema: list[CampoMetadato],
+        name: str | None = None,
+        **serializer_class_kwargs: Any,
+    ) -> type[Any]:
+        """Construye una subclase de rest_framework.serializers.Serializer.
+
+        Requiere que 'djangorestframework' esté instalado.
+
+        Nota sobre ``default``:
+            En DRF, ``default`` actúa como valor por omisión real durante la
+            serialización/deserialización. En Django Forms, ``default`` se
+            mapea a ``initial`` (solo pre-rellena el widget).
+
+        Args:
+            schema: lista de CampoMetadato
+            name: nombre opcional para la clase generada
+            **serializer_class_kwargs: kwargs adicionales para la clase Serializer
+
+        Returns:
+            Subclase de serializers.Serializer con los campos definidos
+
+        Raises:
+            ImportError: si djangorestframework no está instalado
+        """
+        try:
+            from rest_framework import serializers
+        except ImportError as exc:
+            raise ImportError(
+                "MetaFormFactory.build_serializer() requiere 'djangorestframework'. "
+                "Instálalo con: pip install djangorestframework"
+            ) from exc
+
+        field_names = {c.nombre for c in schema}
+        overlap = field_names & set(serializer_class_kwargs)
+        if overlap:
+            raise ValueError(
+                f"Los siguientes kwargs colisionan con nombres de campo: {overlap}"
+            )
+
+        attrs: dict[str, serializers.Field] = {}
+        for campo in schema:
+            if campo.choices is not None:
+                field_class = serializers.ChoiceField
+            else:
+                try:
+                    field_class = cls._DRF_FIELD_MAP[campo.tipo]
+                except KeyError:
+                    raise ValueError(f"Tipo no soportado: {campo.tipo}") from None
+            kwargs = cls._build_field_kwargs(campo, is_django=False)
+            attrs[campo.nombre] = field_class(**kwargs)
+
+        class_name = name or (
+            "DynamicMetaSerializer"
+            if not schema
+            else f"DynamicMetaSerializer_{schema[0].nombre}"
+        )
+        return type(
+            class_name,
+            (serializers.Serializer,),
+            {**attrs, **serializer_class_kwargs},
+        )
+
+    @classmethod
+    def _build_field_kwargs(
+        cls, campo: CampoMetadato, *, is_django: bool
+    ) -> dict[str, Any]:
+        """Construye kwargs para un campo Django o DRF desde CampoMetadato."""
+        kwargs: dict[str, Any] = {
+            "required": campo.requerido,
+            "label": campo.etiqueta or campo.nombre.replace("_", " ").title(),
+            "help_text": campo.ayuda,
+        }
+
+        if campo.default is not None:
+            if is_django:
+                kwargs["initial"] = campo.default
+            else:
+                kwargs["default"] = campo.default
+
+        if campo.choices is not None:
+            kwargs["choices"] = [(c, c) for c in campo.choices]
+
+        if campo.tipo is Decimal and campo.choices is None:
+            kwargs["max_digits"] = 15
+            kwargs["decimal_places"] = 2
+
+        return kwargs

sinpapel/injection.py

@@ -0,0 +1,114 @@
+"""Sinpapel — Métodos inyectados por @workflow_enabled.
+
+Estos métodos se vinculan a la clase decorada via setattr en el decorator.
+Se importan localmente desde decorators.py para evitar circular imports.
+
+Métodos:
+    available_transitions(self, user) -> list[Estado]
+    can_transition_to(self, target_state_name, user) -> tuple[bool, str | None]
+    transition(self, target_state_name, user, **kwargs)
+    preview_transition(self, target_state_name, user) -> dict
+
+Estrategia: `available_transitions` consulta `ConfiguracionTransicion` en DB
+directamente; `can_transition_to`, `transition` y `preview_transition` delegan en
+`sinpapel.services.workflow_engine.WorkflowEngine` (el único motor; `WorkflowService`
+no existe).
+"""
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Any
+
+if TYPE_CHECKING:
+    from django.contrib.auth.models import User
+
+    from sinpapel.models import Estado
+
+
+def available_transitions(self, user: "User") -> list["Estado"]:
+    """Retorna lista de Estado destino válidos desde el estado actual.
+
+    Consulta ConfiguracionTransicion filtrando por estado_origen.
+    No filtra por user permissions — eso lo hace can_transition_to.
+
+    Args:
+        user: usuario consultando (no se usa para filtrar en S12.3, reservado
+              para S12.4 cuando WorkflowEngine considere flujo activo + grupos)
+
+    Returns:
+        lista de instancias Estado destino válidos. Vacía si no hay estado actual.
+    """
+    from sinpapel.models import ConfiguracionTransicion
+
+    config = type(self)._workflow_config  # type: ignore[attr-defined]
+    estado_actual = getattr(self, config.state_field, None)
+    if estado_actual is None:
+        return []
+
+    transiciones = ConfiguracionTransicion.objects.filter(
+        estado_origen=estado_actual,
+    ).select_related("estado_destino")
+    return [t.estado_destino for t in transiciones]
+
+
+def can_transition_to(self, target_state_name: str, user: "User") -> tuple[bool, str | None]:
+    """Valida si la transición a target_state_name está permitida.
+
+    Delega a sinpapel.services.workflow_engine.WorkflowEngine (S12.4).
+
+    Args:
+        target_state_name: nombre del Estado destino (ej. "EN_JEFATURA")
+        user: usuario que intenta la transición
+
+    Returns:
+        tuple (puede: bool, mensaje: str | None)
+    """
+    # Import local: WorkflowEngine carga sinpapel.models, no top-level.
+    from sinpapel.services.workflow_engine import WorkflowEngine
+
+    return WorkflowEngine().puede_cambiar_estado(self, target_state_name, user)
+
+
+def transition(self, target_state_name: str, user: "User", **kwargs: Any) -> Any:
+    """Ejecuta la transición a target_state_name.
+
+    Delega a sinpapel.services.workflow_engine.WorkflowEngine (S12.4).
+
+    Args:
+        target_state_name: nombre del Estado destino
+        user: usuario que ejecuta la transición
+        **kwargs: parámetros adicionales (comentarios, condiciones,
+                  ip_address, firma_payload)
+
+    Returns:
+        dict con keys: success, instance_id, estado_anterior, estado_nuevo,
+        seguimiento_id, + extra del side_effects dispatch
+    """
+    from sinpapel.services.workflow_engine import WorkflowEngine
+
+    comentarios = kwargs.pop("comentarios", "")
+    return WorkflowEngine().cambiar_estado(
+        instance=self,
+        target_state_name=target_state_name,
+        user=user,
+        comentarios=comentarios,
+        **kwargs,
+    )
+
+
+def preview_transition(self, target_state_name: str, user: "User") -> dict:
+    """Simula la transición a target_state_name sin mutar ni persistir nada.
+
+    Delega a sinpapel.services.workflow_engine.WorkflowEngine.
+
+    Args:
+        target_state_name: nombre del Estado destino
+        user: usuario que consulta el preview
+
+    Returns:
+        dict con keys: permitido, razones_bloqueo, side_effects,
+        documentos_faltantes, predicados_fallidos, aprobadores_requeridos,
+        historial_reciente
+    """
+    from sinpapel.services.workflow_engine import WorkflowEngine
+
+    return WorkflowEngine().preview_transition(self, target_state_name, user)