Saltar a contenido

Especificación Técnica: trx_avisos_cobro

Esquema: fuerza_ventas
Base de Datos: crm
Tabla Legacy Origen: c213t_amortizacion_cliente / vi_aviso_cobro
Propósito: Programación y seguimiento de órdenes de cobranza asignadas a los promotores en campo para la gestión y recaudación de facturas de clientes.


1. Justificación y Mejoras de Arquitectura

  • Aislamiento Multi-Tenant (RLS): Integra empresa_id BIGINT NOT NULL con políticas RLS obligatorias para garantizar aislamiento riguroso por tenant en todas las operaciones.
  • Integridad Referencial Compuesta y Normalización de Catálogos: Clave única compuesta (empresa_id, id) y claves foráneas compuestas hacia fuerza_ventas.mae_promotores(empresa_id, promotor_id) y fuerza_ventas.cat_estados_cobro(empresa_id, estado_cobro_id), con correlación lógica por UUID hacia crm.clientes.mae_clientes(empresa_id, cliente_id) (sin FK física cross-service).
  • Control Estricto de Unicidad de Código: Restricción única (empresa_id, codigo_aviso) para evitar duplicidad de correlativos operativos dentro de la misma organización.
  • Eliminación de Deuda Técnica Legacy: Depuración de identificadores BIGINT, campos redundantes y tipado homogéneo en UUID y NUMERIC(12,2).
  • Trazabilidad y Auditoría: Auditoría integral (created_at, updated_at, deleted_at, created_by, updated_by) con auditoría integral.

2. Definiciones de Implementación

Table fuerza_ventas.trx_avisos_cobro {
    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)']
    promotor_id             uuid          [not null, note: 'Promotor asignado a la cobranza en campo']
    cliente_id              uuid          [not null, note: 'Cliente deudor (Correlación lógica con crm.clientes.mae_clientes)']
    codigo_aviso            varchar(30)   [not null, note: 'Código correlativo único del aviso de cobro']
    fecha_emision           date          [not null, note: 'Fecha de generación de la orden de cobro']
    fecha_limite_gestion    date          [not null, note: 'Fecha máxima estipulada para realizar la cobranza']
    monto_total_gestion     numeric(12,2) [not null, default: `0.00`, note: 'Monto total programado a cobrar']
    monto_cobrado_acumulado numeric(12,2) [not null, default: `0.00`, note: 'Monto total recaudado en campo']
    estado_cobro_id         uuid          [not null, note: 'Estado de la orden de cobro (fuerza_ventas.cat_estados_cobro)']
    observaciones           text          [note: 'Instrucciones y notas para la gestión de campo']

    // 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_trx_avisos_cobro_empresa_id']
        (empresa_id, codigo_aviso) [unique, name: 'uq_trx_avisos_cobro_empresa_codigo']
        (empresa_id, is_activo) [name: 'ix_trx_avisos_cobro_empresa_activo']
        (empresa_id, estado_cobro_id) [name: 'ix_trx_avisos_cobro_empresa_estado']
        (empresa_id, promotor_id, estado_cobro_id) [name: 'ix_trx_avisos_cobro_empresa_promotor_estado']
        (empresa_id, cliente_id) [name: 'ix_trx_avisos_cobro_empresa_cliente']
        (empresa_id, fecha_emision) [name: 'ix_trx_avisos_cobro_empresa_fecha']
    }
}

Ref: fuerza_ventas.trx_avisos_cobro.(empresa_id, promotor_id) > fuerza_ventas.mae_promotores.(empresa_id, id)
Ref: fuerza_ventas.trx_avisos_cobro.(empresa_id, estado_cobro_id) > fuerza_ventas.cat_estados_cobro.(empresa_id, id)
CREATE TABLE IF NOT EXISTS fuerza_ventas.trx_avisos_cobro (
    id UUID NOT NULL DEFAULT gen_random_uuid(),
    empresa_id BIGINT NOT NULL,
    promotor_id UUID NOT NULL,
    cliente_id UUID NOT NULL,
    codigo_aviso VARCHAR(30) NOT NULL,
    fecha_emision DATE NOT NULL,
    fecha_limite_gestion DATE NOT NULL,
    monto_total_gestion NUMERIC(12,2) NOT NULL DEFAULT 0.00,
    monto_cobrado_acumulado NUMERIC(12,2) NOT NULL DEFAULT 0.00,
    estado_cobro_id UUID NOT NULL,
    observaciones TEXT,

    -- 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_trx_avisos_cobro
        PRIMARY KEY (id),

    CONSTRAINT uq_trx_avisos_cobro_empresa_id
        UNIQUE (empresa_id, id),

    CONSTRAINT uq_trx_avisos_cobro_empresa_codigo
        UNIQUE (empresa_id, codigo_aviso),

    CONSTRAINT fk_trx_avisos_cobro_mae_promotores
        FOREIGN KEY (empresa_id, promotor_id)
        REFERENCES fuerza_ventas.mae_promotores (empresa_id, id),

    CONSTRAINT fk_trx_avisos_cobro_estado
        FOREIGN KEY (empresa_id, estado_cobro_id)
        REFERENCES fuerza_ventas.cat_estados_cobro (empresa_id, id)
);

CREATE INDEX IF NOT EXISTS ix_trx_avisos_cobro_empresa_activo
    ON fuerza_ventas.trx_avisos_cobro (empresa_id, is_activo);

CREATE INDEX IF NOT EXISTS ix_trx_avisos_cobro_empresa_estado
    ON fuerza_ventas.trx_avisos_cobro (empresa_id, estado_cobro_id);

CREATE INDEX IF NOT EXISTS ix_trx_avisos_cobro_empresa_promotor_estado
    ON fuerza_ventas.trx_avisos_cobro (empresa_id, promotor_id, estado_cobro_id);

CREATE INDEX IF NOT EXISTS ix_trx_avisos_cobro_empresa_cliente
    ON fuerza_ventas.trx_avisos_cobro (empresa_id, cliente_id);

CREATE INDEX IF NOT EXISTS ix_trx_avisos_cobro_empresa_fecha
    ON fuerza_ventas.trx_avisos_cobro (empresa_id, fecha_emision);

COMMENT ON TABLE fuerza_ventas.trx_avisos_cobro IS
    'Avisos de Cobro y Órdenes de Cobranza (Cabecera): Programación de cobros asignados a los promotores en campo para recaudación de facturas pendientes.';

COMMENT ON COLUMN fuerza_ventas.trx_avisos_cobro.id IS
    'Identificador único UUID';

COMMENT ON COLUMN fuerza_ventas.trx_avisos_cobro.empresa_id IS
    'Identificador BIGINT de la empresa en core.identidad (RLS)';

COMMENT ON COLUMN fuerza_ventas.trx_avisos_cobro.promotor_id IS
    'Promotor asignado a la cobranza en campo';

COMMENT ON COLUMN fuerza_ventas.trx_avisos_cobro.cliente_id IS
    'Cliente deudor';

COMMENT ON COLUMN fuerza_ventas.trx_avisos_cobro.codigo_aviso IS
    'Código correlativo único del aviso de cobro';

COMMENT ON COLUMN fuerza_ventas.trx_avisos_cobro.fecha_emision IS
    'Fecha de generación de la orden de cobro';

COMMENT ON COLUMN fuerza_ventas.trx_avisos_cobro.fecha_limite_gestion IS
    'Fecha máxima estipulada para realizar la cobranza';

COMMENT ON COLUMN fuerza_ventas.trx_avisos_cobro.monto_total_gestion IS
    'Monto total programado a cobrar';

COMMENT ON COLUMN fuerza_ventas.trx_avisos_cobro.monto_cobrado_acumulado IS
    'Monto total recaudado en campo';

COMMENT ON COLUMN fuerza_ventas.trx_avisos_cobro.estado_cobro_id IS
    'Estado de la orden de cobro (fuerza_ventas.cat_estados_cobro)';

COMMENT ON COLUMN fuerza_ventas.trx_avisos_cobro.observaciones IS
    'Instrucciones y notas para la gestión de campo';

COMMENT ON COLUMN fuerza_ventas.trx_avisos_cobro.is_activo IS
    'Estado lógico del registro';

COMMENT ON COLUMN fuerza_ventas.trx_avisos_cobro.created_at IS
    'Fecha de creación';

COMMENT ON COLUMN fuerza_ventas.trx_avisos_cobro.updated_at IS
    'Fecha de última actualización';

COMMENT ON COLUMN fuerza_ventas.trx_avisos_cobro.deleted_at IS
    'Fecha de eliminación lógica';

COMMENT ON COLUMN fuerza_ventas.trx_avisos_cobro.created_by IS
    'Usuario creador';

COMMENT ON COLUMN fuerza_ventas.trx_avisos_cobro.updated_by IS
    'Usuario modificador';

ALTER TABLE fuerza_ventas.trx_avisos_cobro
    ENABLE ROW LEVEL SECURITY;

CREATE POLICY rls_trx_avisos_cobro_empresa
    ON fuerza_ventas.trx_avisos_cobro
    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
    );