Saltar a contenido

Especificación Técnica: trx_cobros_campo

Esquema: fuerza_ventas
Base de Datos: crm
Servicio: svc-fuerza-ventas
Tabla Legacy Origen: c213t_amortizacion_cliente
Propósito: Registro de cobros y recaudaciones comerciales efectuadas directamente en campo por promotores o cobradores móviles. Conecta los ingresos recibidos en ruta con el módulo de tesorería y contabilidad del ERP.


1. Justificación y Mejoras de Arquitectura

  • Integración Desacoplada Cross-Database: Enlaza de forma limpia mediante UUIDs de correlación lógica a los clientes (cliente_id) y bancos (banco_id en core.identidad.cat_bancos), sin generar acoplamiento físico inter-base.
  • Integración con Catálogos Contables: Relaciona formalmente mediante FKs compuestas hacia fuerza_ventas.cat_metodos_pago(empresa_id, id) y fuerza_ventas.cat_estados_cobro(empresa_id, id).
  • Integridad Referencial Intra-Esquema: Promotor recaudador (promotor_id) y visita de origen (visita_id) se relacionan con FKs compuestas hacia fuerza_ventas.mae_promotores(empresa_id, id) y fuerza_ventas.trx_visitas(empresa_id, id) (ON DELETE RESTRICT).
  • Aislamiento Multi-Tenant (RLS): Integra empresa_id BIGINT NOT NULL con políticas RLS obligatorias (USING y WITH CHECK) garantizando aislamiento total de las operaciones financieras por empresa.
  • Integridad Compuesta para Imputaciones: Incorpora la restricción UNIQUE (empresa_id, id) para permitir que trx_cobros_campo_imputaciones aplique claves foráneas compuestas con eliminación en cascada.
  • Unicidad de Recibo de Cobranza: Restricción UNIQUE (empresa_id, numero_recibo_campo) para blindar contra duplicidad de recibos emitidos desde dispositivos móviles.
  • Trazabilidad de Geolocalización y Conciliación: Almacena coordenadas GPS del cobro (latitud_cobro, longitud_cobro como DOUBLE PRECISION) y auditoría integral (created_at, updated_at, deleted_at, created_by, updated_by).

2. Definiciones de Implementación

Table fuerza_ventas.trx_cobros_campo {
    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)']
    cliente_id                    uuid             [not null, note: 'Correlación lógica con crm.clientes.mae_clientes (sin FK física)']
    promotor_id                   uuid             [not null, note: 'Referencia a fuerza_ventas.mae_promotores (FK compuesta por empresa_id)']
    visita_id                     uuid             [note: 'Referencia a fuerza_ventas.trx_visitas (FK compuesta por empresa_id)']
    metodo_pago_id                uuid             [not null, note: 'Método de pago (FK fuerza_ventas.cat_metodos_pago)']
    banco_id                      uuid             [note: 'Banco receptor/emisor (Correlación lógica con core.identidad.cat_bancos)']
    estado_cobro_id               uuid             [not null, note: 'Estado del cobro (FK fuerza_ventas.cat_estados_cobro)']
    numero_recibo_campo           varchar(30)      [not null, note: 'Número correlativo único del recibo móvil']
    fecha_cobro                   timestamptz      [not null, default: `now()`, note: 'Fecha y hora del cobro en campo']
    monto_total_recaudado         numeric(12,2)    [not null, note: 'Monto total monetario recaudado']
    numero_documento_pago         varchar(50)      [note: 'Número de cheque, comprobante de transferencia o depósito']
    comprobante_imagen_url        varchar(500)     [note: 'URL de almacenamiento de la foto o comprobante de pago']
    latitud_cobro                 double precision [note: 'Coordenada de latitud GPS del cobro']
    longitud_cobro                double precision [note: 'Coordenada de longitud GPS del cobro']
    observaciones                 text             [note: 'Comentarios u observaciones de cobranza']

    // 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_cobros_campo_empresa_id']
        (empresa_id, numero_recibo_campo) [unique, name: 'uq_trx_cobros_campo_empresa_recibo']
        (empresa_id, cliente_id) [name: 'ix_trx_cobros_campo_empresa_cliente']
        (empresa_id, promotor_id) [name: 'ix_trx_cobros_campo_empresa_promotor']
        (empresa_id, visita_id) [name: 'ix_trx_cobros_campo_empresa_visita']
        (empresa_id, metodo_pago_id) [name: 'ix_trx_cobros_campo_empresa_metodo']
        (empresa_id, banco_id) [name: 'ix_trx_cobros_campo_empresa_banco']
        (empresa_id, estado_cobro_id) [name: 'ix_trx_cobros_campo_empresa_estado']
        (empresa_id, fecha_cobro) [name: 'ix_trx_cobros_campo_empresa_fecha']
        (empresa_id, is_activo) [name: 'ix_trx_cobros_campo_empresa_activo']
    }
}

Ref: fuerza_ventas.trx_cobros_campo.(empresa_id, metodo_pago_id) > fuerza_ventas.cat_metodos_pago.(empresa_id, id) [delete: restrict]
Ref: fuerza_ventas.trx_cobros_campo.(empresa_id, estado_cobro_id) > fuerza_ventas.cat_estados_cobro.(empresa_id, id) [delete: restrict]
Ref: fuerza_ventas.trx_cobros_campo.(empresa_id, promotor_id) > fuerza_ventas.mae_promotores.(empresa_id, id) [delete: restrict]
Ref: fuerza_ventas.trx_cobros_campo.(empresa_id, visita_id) > fuerza_ventas.trx_visitas.(empresa_id, id) [delete: restrict]
CREATE TABLE IF NOT EXISTS fuerza_ventas.trx_cobros_campo (
    id UUID NOT NULL DEFAULT gen_random_uuid(),
    empresa_id BIGINT NOT NULL,
    cliente_id UUID NOT NULL,
    promotor_id UUID NOT NULL,
    visita_id UUID,
    metodo_pago_id UUID NOT NULL,
    banco_id UUID,
    estado_cobro_id UUID NOT NULL,
    numero_recibo_campo VARCHAR(30) NOT NULL,
    fecha_cobro TIMESTAMPTZ NOT NULL DEFAULT now(),
    monto_total_recaudado NUMERIC(12,2) NOT NULL,
    numero_documento_pago VARCHAR(50),
    comprobante_imagen_url VARCHAR(500),
    latitud_cobro DOUBLE PRECISION,
    longitud_cobro DOUBLE PRECISION,
    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_cobros_campo PRIMARY KEY (id),
    CONSTRAINT uq_trx_cobros_campo_empresa_id UNIQUE (empresa_id, id),
    CONSTRAINT uq_trx_cobros_campo_empresa_recibo UNIQUE (empresa_id, numero_recibo_campo),
    CONSTRAINT fk_trx_cobros_campo_metodo FOREIGN KEY (empresa_id, metodo_pago_id)
        REFERENCES fuerza_ventas.cat_metodos_pago (empresa_id, id)
        ON DELETE RESTRICT,
    CONSTRAINT fk_trx_cobros_campo_estado FOREIGN KEY (empresa_id, estado_cobro_id)
        REFERENCES fuerza_ventas.cat_estados_cobro (empresa_id, id)
        ON DELETE RESTRICT,
    CONSTRAINT fk_trx_cobros_campo_promotor FOREIGN KEY (empresa_id, promotor_id)
        REFERENCES fuerza_ventas.mae_promotores (empresa_id, id)
        ON DELETE RESTRICT,
    CONSTRAINT fk_trx_cobros_campo_visita FOREIGN KEY (empresa_id, visita_id)
        REFERENCES fuerza_ventas.trx_visitas (empresa_id, id)
        ON DELETE RESTRICT
);

-- Índices
CREATE INDEX IF NOT EXISTS ix_trx_cobros_campo_empresa_cliente
    ON fuerza_ventas.trx_cobros_campo (empresa_id, cliente_id);

CREATE INDEX IF NOT EXISTS ix_trx_cobros_campo_empresa_promotor
    ON fuerza_ventas.trx_cobros_campo (empresa_id, promotor_id);

CREATE INDEX IF NOT EXISTS ix_trx_cobros_campo_empresa_visita
    ON fuerza_ventas.trx_cobros_campo (empresa_id, visita_id);

CREATE INDEX IF NOT EXISTS ix_trx_cobros_campo_empresa_metodo
    ON fuerza_ventas.trx_cobros_campo (empresa_id, metodo_pago_id);

CREATE INDEX IF NOT EXISTS ix_trx_cobros_campo_empresa_banco
    ON fuerza_ventas.trx_cobros_campo (empresa_id, banco_id);

CREATE INDEX IF NOT EXISTS ix_trx_cobros_campo_empresa_estado
    ON fuerza_ventas.trx_cobros_campo (empresa_id, estado_cobro_id);

CREATE INDEX IF NOT EXISTS ix_trx_cobros_campo_empresa_fecha
    ON fuerza_ventas.trx_cobros_campo (empresa_id, fecha_cobro);

CREATE INDEX IF NOT EXISTS ix_trx_cobros_campo_empresa_activo
    ON fuerza_ventas.trx_cobros_campo (empresa_id, is_activo);

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

CREATE POLICY rls_trx_cobros_campo_empresa
    ON fuerza_ventas.trx_cobros_campo
    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.trx_cobros_campo IS 'Cobros y amortizaciones recaudados en campo por promotores';
COMMENT ON COLUMN fuerza_ventas.trx_cobros_campo.cliente_id IS 'Correlación con crm.clientes.mae_clientes (sin FK cross-DB)';
COMMENT ON COLUMN fuerza_ventas.trx_cobros_campo.promotor_id IS 'Referencia a fuerza_ventas.mae_promotores (FK compuesta por empresa_id)';
COMMENT ON COLUMN fuerza_ventas.trx_cobros_campo.visita_id IS 'Referencia a fuerza_ventas.trx_visitas (FK compuesta por empresa_id)';
COMMENT ON COLUMN fuerza_ventas.trx_cobros_campo.metodo_pago_id IS 'Identificador del método de pago (FK cat_metodos_pago)';
COMMENT ON COLUMN fuerza_ventas.trx_cobros_campo.banco_id IS 'Identificador de la entidad bancaria (Correlación con core.identidad.cat_bancos)';
COMMENT ON COLUMN fuerza_ventas.trx_cobros_campo.estado_cobro_id IS 'Identificador del estado de cobro (FK cat_estados_cobro)';