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_idencore.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)yfuerza_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 haciafuerza_ventas.mae_promotores(empresa_id, id)yfuerza_ventas.trx_visitas(empresa_id, id)(ON DELETE RESTRICT). - Aislamiento Multi-Tenant (RLS): Integra
empresa_id BIGINT NOT NULLcon políticas RLS obligatorias (USINGyWITH CHECK) garantizando aislamiento total de las operaciones financieras por empresa. - Integridad Compuesta para Imputaciones: Incorpora la restricción
UNIQUE (empresa_id, id)para permitir quetrx_cobros_campo_imputacionesaplique 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_cobrocomoDOUBLE 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)';