Saltar a contenido

Especificación Técnica: mae_promotores

Esquema: fuerza_ventas
Base de Datos: crm
Tabla Legacy Origen: i127t_promotor (61 col)
Propósito: Perfil comercial del promotor de ventas. Aísla la identidad de usuario y credenciales (delegadas a core.identidad) y se enfoca en parámetros comerciales, metas, comisiones y cupos de crédito comercial.


1. Justificación y Mejoras de Arquitectura

  • Desacoplamiento de Identidad: La autenticación y perfiles de usuario residen en core.identidad. La tabla comercial conserva únicamente atributos del rol operativo de ventas (usuario_id y persona_id correlacionados de forma lógica sin foreign keys cross-database).
  • Integración con Catálogos de Comisión: Asocia la modalidad de liquidación de comisiones mediante FK compuesta (empresa_id, modalidad_pago_comision_id) hacia fuerza_ventas.cat_modalidades_pago_comision(empresa_id, id).
  • Integración con Catálogo de Tipos de Promotor: El rol del promotor (VENDEDOR, PREVENTISTA, AUTOVENTA, COBRADOR, MERCHANDISER, SUPERVISOR) se normaliza mediante FK compuesta (empresa_id, tipo_promotor_id) hacia fuerza_ventas.cat_tipos_promotor(empresa_id, id).
  • Aislamiento Multi-Tenant (RLS): Integra empresa_id BIGINT NOT NULL con políticas RLS obligatorias para segregar la fuerza de ventas por tenant.
  • Soporte de Relaciones Compuestas: Clave única compuesta (empresa_id, id) que permite a las entidades hijas (mae_agencias, mae_equipos_consignacion, mae_metas_promotores, mae_presupuestos_cliente, trx_visitas) heredar la restricción de tenant en sus foreign keys.
  • Trazabilidad y Auditoría: Auditoría completa y auditoría integral.

2. Definiciones de Implementación

Table fuerza_ventas.mae_promotores {
    id                          uuid          [pk, default: `gen_random_uuid()`, note: 'Identificador único UUID']
    empresa_id                  bigint        [not null, note: 'Identificador BIGINT de la empresa en core.identidad (RLS)']
    usuario_id                  uuid          [not null, note: 'Correlación con core.identidad.mae_usuarios (sin FK cross-DB)']
    persona_id                  uuid          [not null, note: 'Correlación con core.identidad.mae_personas (sin FK cross-DB)']
    codigo_promotor             varchar(30)   [not null, note: 'Código interno comercial']
    tipo_promotor_id            uuid          [not null, note: 'Tipo de promotor (FK cat_tipos_promotor)']
    modalidad_pago_comision_id  uuid          [note: 'Modalidad de pago de comisión (FK cat_modalidades_pago_comision)']
    is_coordinador              boolean       [not null, default: `false`, note: 'Indica si tiene rol de coordinación/supervisión']
    is_casa_matriz              boolean       [not null, default: `false`, note: 'Indica si opera desde sede principal']
    porcentaje_comision         numeric(5,2)  [not null, default: `0.00`, note: 'Porcentaje base de comisión']
    monto_cupo_maximo_credito   numeric(12,2) [not null, default: `0.00`, note: 'Cupo máximo acumulado otorgable a su cartera']
    dispositivo_imei             varchar(50)   [note: 'Identificador del dispositivo móvil autorizado']
    telefono_corporativo        varchar(50)   [note: 'Número móvil institucional']

    // Auditoría General
    is_activo                   boolean       [not null, default: `true`, note: 'Estado lógico del registro']
    created_at                  timestamptz   [not null, default: `now()`, note: 'Fecha de creación']
    updated_at                  timestamptz   [not null, default: `now()`, note: 'Fecha de última actualización']
    deleted_at                  timestamptz   [note: 'Fecha de eliminación lógica']
    created_by                  uuid          [note: 'Usuario creador']
    updated_by                  uuid          [note: 'Usuario modificador']

    Indexes {
        (empresa_id, id) [unique, name: 'uq_mae_promotores_empresa_id']
        (empresa_id, codigo_promotor) [unique, name: 'uq_mae_promotores_empresa_codigo']
        (empresa_id, usuario_id) [unique, name: 'uq_mae_promotores_empresa_usuario']
        (empresa_id, persona_id) [name: 'ix_mae_promotores_empresa_persona']
        (empresa_id, modalidad_pago_comision_id) [name: 'ix_mae_promotores_empresa_modalidad']
        (empresa_id, tipo_promotor_id) [name: 'ix_mae_promotores_empresa_tipo']
        (empresa_id, is_activo) [name: 'ix_mae_promotores_empresa_activo']
    }
}

Ref: fuerza_ventas.mae_promotores.(empresa_id, modalidad_pago_comision_id) > fuerza_ventas.cat_modalidades_pago_comision.(empresa_id, id) [delete: restrict]
Ref: fuerza_ventas.mae_promotores.(empresa_id, tipo_promotor_id) > fuerza_ventas.cat_tipos_promotor.(empresa_id, id) [delete: restrict]
CREATE TABLE IF NOT EXISTS fuerza_ventas.mae_promotores (
    id UUID NOT NULL DEFAULT gen_random_uuid(),
    empresa_id BIGINT NOT NULL,
    usuario_id UUID NOT NULL,
    persona_id UUID NOT NULL,
    codigo_promotor VARCHAR(30) NOT NULL,
    tipo_promotor_id UUID NOT NULL,
    modalidad_pago_comision_id UUID,
    is_coordinador BOOLEAN NOT NULL DEFAULT false,
    is_casa_matriz BOOLEAN NOT NULL DEFAULT false,
    porcentaje_comision NUMERIC(5,2) NOT NULL DEFAULT 0.00,
    monto_cupo_maximo_credito NUMERIC(12,2) NOT NULL DEFAULT 0.00,
    dispositivo_imei VARCHAR(50),
    telefono_corporativo VARCHAR(50),

    -- Auditoría General
    is_activo BOOLEAN NOT NULL DEFAULT true,
    created_at TIMESTAMPTZ NOT NULL DEFAULT now(),
    updated_at TIMESTAMPTZ NOT NULL DEFAULT now(),
    deleted_at TIMESTAMPTZ,
    created_by UUID,
    updated_by UUID,

    CONSTRAINT pk_mae_promotores PRIMARY KEY (id),
    CONSTRAINT uq_mae_promotores_empresa_id UNIQUE (empresa_id, id),
    CONSTRAINT uq_mae_promotores_empresa_codigo UNIQUE (empresa_id, codigo_promotor),
    CONSTRAINT uq_mae_promotores_empresa_usuario UNIQUE (empresa_id, usuario_id),
    CONSTRAINT fk_mae_promotores_modalidad_comision FOREIGN KEY (empresa_id, modalidad_pago_comision_id)
        REFERENCES fuerza_ventas.cat_modalidades_pago_comision (empresa_id, id)
        ON DELETE RESTRICT,
    CONSTRAINT fk_mae_promotores_tipo_promotor FOREIGN KEY (empresa_id, tipo_promotor_id)
        REFERENCES fuerza_ventas.cat_tipos_promotor (empresa_id, id)
        ON DELETE RESTRICT
);

-- Índices
CREATE INDEX IF NOT EXISTS ix_mae_promotores_empresa_persona
    ON fuerza_ventas.mae_promotores (empresa_id, persona_id);

CREATE INDEX IF NOT EXISTS ix_mae_promotores_empresa_modalidad
    ON fuerza_ventas.mae_promotores (empresa_id, modalidad_pago_comision_id);

CREATE INDEX IF NOT EXISTS ix_mae_promotores_empresa_tipo
    ON fuerza_ventas.mae_promotores (empresa_id, tipo_promotor_id);

CREATE INDEX IF NOT EXISTS ix_mae_promotores_empresa_activo
    ON fuerza_ventas.mae_promotores (empresa_id, is_activo);

-- Row-Level Security
ALTER TABLE fuerza_ventas.mae_promotores ENABLE ROW LEVEL SECURITY;

CREATE POLICY rls_mae_promotores_empresa
    ON fuerza_ventas.mae_promotores
    FOR ALL
    USING (
        empresa_id = current_setting('app.current_empresa_id', true)::BIGINT
    )
    WITH CHECK (
        empresa_id = current_setting('app.current_empresa_id', true)::BIGINT
    );

-- Comentarios
COMMENT ON TABLE fuerza_ventas.mae_promotores IS 'Maestro de Promotores y Asesores Comerciales';
COMMENT ON COLUMN fuerza_ventas.mae_promotores.modalidad_pago_comision_id IS 'Identificador de la modalidad de pago de comisión (FK cat_modalidades_pago_comision)';
COMMENT ON COLUMN fuerza_ventas.mae_promotores.usuario_id IS 'Correlación con core.identidad.mae_usuarios (sin FK cross-DB)';
COMMENT ON COLUMN fuerza_ventas.mae_promotores.persona_id IS 'Correlación con core.identidad.mae_personas (sin FK cross-DB)';
COMMENT ON COLUMN fuerza_ventas.mae_promotores.tipo_promotor_id IS 'Tipo o rol de promotor comercial (FK cat_tipos_promotor)';