Saltar a contenido

CfgComisionPromotor — fuerza_ventas.cfg_comision_promotor

Configuración de comisión del promotor comercial con vigencia temporal.

import uuid
from datetime import date, datetime
from decimal import Decimal
from typing import Optional

from sqlalchemy import (
    BigInteger,
    Boolean,
    CheckConstraint,
    Date,
    ForeignKeyConstraint,
    Index,
    Numeric,
    UniqueConstraint,
    text,
)
from sqlalchemy.dialects.postgresql import TIMESTAMP, UUID
from sqlalchemy.orm import Mapped, mapped_column

from app.db.base import Base


class CfgComisionPromotor(Base):
    """
    Configuración de comisión del promotor comercial con vigencia temporal.

    Permite parametrizar las comisiones directas, supervisadas, cupos de venta
    y bonos asignados al promotor según el modelo comercial aplicable.

    Legacy:
        i127t_promotor (comisión sobrescrita sin histórico)
    """

    __tablename__ = "cfg_comision_promotor"

    __table_args__ = (
        UniqueConstraint(
            "empresa_id",
            "id",
            name="uq_cfg_comision_promotor_empresa_id",
        ),
        CheckConstraint(
            "(((porcentaje >= (0)::numeric) AND (porcentaje <= (100)::numeric)) "
            "AND ((porcentaje_supervisado >= (0)::numeric) AND (porcentaje_supervisado <= (100)::numeric)) "
            "AND ((porcentaje_cupo IS NULL) OR ((porcentaje_cupo >= (0)::numeric) AND (porcentaje_cupo <= (100)::numeric))))",
            name="ck_cfg_comision_promotor_porcentajes",
        ),
        ForeignKeyConstraint(
            ["empresa_id", "promotor_id"],
            ["fuerza_ventas.mae_promotores.empresa_id", "fuerza_ventas.mae_promotores.id"],
            ondelete="RESTRICT",
            name="fk_cfg_comision_promotor_promotor",
        ),
        Index(
            "ix_cfg_comision_promotor_empresa_id",
            "empresa_id",
        ),
        Index(
            "ix_cfg_comision_promotor_empresa_promotor",
            "empresa_id",
            "promotor_id",
        ),
        Index(
            "ix_cfg_comision_promotor_empresa_modelo",
            "empresa_id",
            "modelo_comercial_id",
        ),
        Index(
            "ix_cfg_comision_promotor_empresa_vigencia",
            "empresa_id",
            "vigente_desde",
        ),
        Index(
            "ix_cfg_comision_promotor_empresa_activo",
            "empresa_id",
            "is_activo",
        ),
        {
            "schema": "fuerza_ventas",
            "comment": "Configuración de comisión del promotor comercial, con vigencia temporal desde fecha de aplicación e histórico.",
        },
    )

    # Clave Primaria UUID
    id: Mapped[uuid.UUID] = mapped_column(
        UUID(as_uuid=True),
        primary_key=True,
        server_default=text("gen_random_uuid()"),
        comment="Identificador único UUID.",
    )

    # Multi-Tenant & Relaciones
    empresa_id: Mapped[int] = mapped_column(
        BigInteger,
        nullable=False,
        comment="Identificador BIGINT de la empresa en core.identidad (RLS).",
    )

    promotor_id: Mapped[uuid.UUID] = mapped_column(
        UUID(as_uuid=True),
        nullable=False,
        comment="Referencia a fuerza_ventas.mae_promotores — promotor comercial al que aplica la configuración.",
    )

    modelo_comercial_id: Mapped[uuid.UUID] = mapped_column(
        UUID(as_uuid=True),
        nullable=False,
        comment="Referencia a clientes.cat_modelos_comerciales — modelo o modalidad comercial aplicable.",
    )

    # Parámetros y Porcentajes de Comisión
    porcentaje: Mapped[Decimal] = mapped_column(
        Numeric(5, 2),
        nullable=False,
        server_default=text("0.00"),
        comment="Porcentaje de comisión aplicado sobre las ventas propias del promotor.",
    )

    porcentaje_supervisado: Mapped[Decimal] = mapped_column(
        Numeric(5, 2),
        nullable=False,
        server_default=text("0.00"),
        comment="Porcentaje de comisión aplicado sobre las ventas de los promotores supervisados.",
    )

    is_individual: Mapped[bool] = mapped_column(
        Boolean,
        nullable=False,
        server_default=text("true"),
        comment="Indica si la comisión se calcula de forma individual (no compartida).",
    )

    tope_venta: Mapped[Optional[Decimal]] = mapped_column(
        Numeric(14, 2),
        nullable=True,
        comment="Monto tope de venta sobre el que se calcula la comisión, si aplica un límite.",
    )

    cupo_venta: Mapped[Optional[Decimal]] = mapped_column(
        Numeric(14, 2),
        nullable=True,
        comment="Cupo de venta objetivo del promotor para este período.",
    )

    porcentaje_cupo: Mapped[Optional[Decimal]] = mapped_column(
        Numeric(5, 2),
        nullable=True,
        comment="Porcentaje de bono asociado al cumplimiento del cupo de venta.",
    )

    bono_cupo: Mapped[Optional[Decimal]] = mapped_column(
        Numeric(12, 2),
        nullable=True,
        comment="Monto de bono por cumplimiento de cupo, si aplica.",
    )

    # Vigencia Temporal
    vigente_desde: Mapped[date] = mapped_column(
        Date,
        nullable=False,
        server_default=text("CURRENT_DATE"),
        comment="Fecha desde la que rige esta configuración de comisión.",
    )

    # Auditoría General
    is_activo: Mapped[bool] = mapped_column(
        Boolean,
        nullable=False,
        server_default=text("true"),
        comment="Estado lógico del registro.",
    )

    created_at: Mapped[datetime] = mapped_column(
        TIMESTAMP(timezone=True),
        nullable=False,
        server_default=text("now()"),
        comment="Fecha de creación.",
    )

    updated_at: Mapped[datetime] = mapped_column(
        TIMESTAMP(timezone=True),
        nullable=False,
        server_default=text("now()"),
        comment="Fecha de última actualización.",
    )

    deleted_at: Mapped[Optional[datetime]] = mapped_column(
        TIMESTAMP(timezone=True),
        nullable=True,
        comment="Fecha de eliminación lógica.",
    )

    created_by: Mapped[Optional[uuid.UUID]] = mapped_column(
        UUID(as_uuid=True),
        nullable=True,
        comment="Usuario creador.",
    )

    updated_by: Mapped[Optional[uuid.UUID]] = mapped_column(
        UUID(as_uuid=True),
        nullable=True,
        comment="Usuario modificador.",
    )