Saltar a contenido

Especificación Técnica: trx_pedidos

Esquema: fuerza_ventas
Base de Datos: crm
Tabla Legacy Origen: c067t_pedido (42 col)
Propósito: Cabecera de órdenes de pedido generadas desde la aplicación móvil de promotores hacia el dominio de pedidos del ERP. Aplica integración desacoplada mediante UUIDs de correlación hacia CRM y Core sin dependencias foráneas físicas entre bases de datos.


1. Justificación y Mejoras de Arquitectura

  • Integración Desacoplada Cross-Database: Mantiene la autonomía del microservicio ERP utilizando identificadores UUID de correlación para vincular clientes (cliente_id), locales (local_entrega_id), canales (canal_id), términos de pago (termino_pago_id) y tipos de envío (tipo_envio_id) hacia crm, y sucursales (sucursal_id) hacia core.identidad, sin claves foráneas físicas inter-base.
  • Integridad Referencial Intra-Esquema: Promotor (promotor_id) y visita de origen (visita_id) viven en el mismo esquema fuerza_ventas, por lo que se relacionan con FKs compuestas (empresa_id, promotor_id) hacia fuerza_ventas.mae_promotores(empresa_id, id) y (empresa_id, visita_id) hacia 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 estricto por organización.
  • Integridad Referencial Compuesta para Detalle y Planificaciones: Define la restricción UNIQUE (empresa_id, id) en la cabecera para permitir que las tablas hijas (trx_pedidos_detalle y trx_pedidos_planificaciones) vinculen claves foráneas compuestas garantizando consistencia multi-tenant.
  • Control de Unicidad de Correlativo: Restricción UNIQUE (empresa_id, numero_pedido) para evitar colisiones de numeración de pedidos dentro del mismo tenant.
  • 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_pedidos {
    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)']
    local_entrega_id        uuid          [note: 'Correlación lógica con crm.clientes.mae_locales_cliente (sin FK física)']
    promotor_id             uuid          [not null, note: 'Referencia a fuerza_ventas.mae_promotores (FK compuesta por empresa_id)']
    sucursal_id             uuid          [not null, note: 'Correlación lógica con core.identidad.mae_sucursales (sin FK física)']
    visita_id               uuid          [note: 'Referencia a fuerza_ventas.trx_visitas (FK compuesta por empresa_id)']
    numero_pedido           varchar(30)   [not null, note: 'Número correlativo comercial del pedido']
    fecha_pedido            timestamptz   [not null, default: `now()`, note: 'Fecha y hora de emisión']
    fecha_entrega_estimada  date          [not null, note: 'Fecha comprometida de despacho']
    canal_id                uuid          [not null, note: 'Correlación lógica con crm.clientes.cat_canales_comerciales']
    termino_pago_id         uuid          [not null, note: 'Correlación lógica con crm.clientes.cat_terminos_pago']
    tipo_envio_id           uuid          [note: 'Correlación lógica con crm.clientes.cat_tipos_envio']
    monto_subtotal          numeric(12,2) [not null, default: `0.00`, note: 'Subtotal antes de descuentos e impuestos']
    monto_descuento         numeric(12,2) [not null, default: `0.00`, note: 'Descuento comercial global']
    monto_impuestos         numeric(12,2) [not null, default: `0.00`, note: 'Total de tributos (IVA)']
    monto_total             numeric(12,2) [not null, default: `0.00`, note: 'Monto neto final del pedido']
    estado_pedido           varchar(30)   [not null, default: `'BORRADOR'`, note: 'BORRADOR, ENVIADO, APROBADO_CREDITO, FACTURADO, DESPACHADO, ENTREGADO, CANCELADO']
    observaciones           text          [note: 'Instrucciones de entrega o notas comerciales']

    // 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_pedidos_empresa_id']
        (empresa_id, numero_pedido) [unique, name: 'uq_trx_pedidos_empresa_numero']
        (empresa_id, is_activo) [name: 'ix_trx_pedidos_empresa_activo']
        (empresa_id, cliente_id, fecha_pedido) [name: 'ix_trx_pedidos_empresa_cliente_fecha']
        (empresa_id, promotor_id, fecha_pedido) [name: 'ix_trx_pedidos_empresa_promotor_fecha']
        (empresa_id, estado_pedido) [name: 'ix_trx_pedidos_empresa_estado']
    }
}

Ref: fuerza_ventas.trx_pedidos.(empresa_id, promotor_id) > fuerza_ventas.mae_promotores.(empresa_id, id) [delete: restrict]
Ref: fuerza_ventas.trx_pedidos.(empresa_id, visita_id) > fuerza_ventas.trx_visitas.(empresa_id, id) [delete: restrict]
CREATE TABLE IF NOT EXISTS fuerza_ventas.trx_pedidos (
    id UUID NOT NULL DEFAULT gen_random_uuid(),
    empresa_id BIGINT NOT NULL,
    cliente_id UUID NOT NULL,
    local_entrega_id UUID,
    promotor_id UUID NOT NULL,
    sucursal_id UUID NOT NULL,
    visita_id UUID,
    numero_pedido VARCHAR(30) NOT NULL,
    fecha_pedido TIMESTAMPTZ NOT NULL DEFAULT now(),
    fecha_entrega_estimada DATE NOT NULL,
    canal_id UUID NOT NULL,
    termino_pago_id UUID NOT NULL,
    tipo_envio_id UUID,
    monto_subtotal NUMERIC(12,2) NOT NULL DEFAULT 0.00,
    monto_descuento NUMERIC(12,2) NOT NULL DEFAULT 0.00,
    monto_impuestos NUMERIC(12,2) NOT NULL DEFAULT 0.00,
    monto_total NUMERIC(12,2) NOT NULL DEFAULT 0.00,
    estado_pedido VARCHAR(30) NOT NULL DEFAULT 'BORRADOR',
    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_pedidos
        PRIMARY KEY (id),

    CONSTRAINT uq_trx_pedidos_empresa_id
        UNIQUE (empresa_id, id),

    CONSTRAINT uq_trx_pedidos_empresa_numero
        UNIQUE (empresa_id, numero_pedido),
    CONSTRAINT fk_trx_pedidos_promotor FOREIGN KEY (empresa_id, promotor_id)
        REFERENCES fuerza_ventas.mae_promotores (empresa_id, id)
        ON DELETE RESTRICT,
    CONSTRAINT fk_trx_pedidos_visita FOREIGN KEY (empresa_id, visita_id)
        REFERENCES fuerza_ventas.trx_visitas (empresa_id, id)
        ON DELETE RESTRICT
);

CREATE INDEX IF NOT EXISTS ix_trx_pedidos_empresa_activo
    ON fuerza_ventas.trx_pedidos (empresa_id, is_activo);

CREATE INDEX IF NOT EXISTS ix_trx_pedidos_empresa_cliente_fecha
    ON fuerza_ventas.trx_pedidos (empresa_id, cliente_id, fecha_pedido);

CREATE INDEX IF NOT EXISTS ix_trx_pedidos_empresa_promotor_fecha
    ON fuerza_ventas.trx_pedidos (empresa_id, promotor_id, fecha_pedido);

CREATE INDEX IF NOT EXISTS ix_trx_pedidos_empresa_estado
    ON fuerza_ventas.trx_pedidos (empresa_id, estado_pedido);

COMMENT ON TABLE fuerza_ventas.trx_pedidos IS
    'Órdenes de Pedido de Ventas (Cabecera ERP): Cabecera de pedidos generados desde la aplicación móvil de promotores hacia el dominio de pedidos del ERP. Aplica integración desacoplada mediante UUIDs de correlación hacia CRM y Core sin dependencias foráneas físicas entre bases.';

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

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

COMMENT ON COLUMN fuerza_ventas.trx_pedidos.cliente_id IS
    'Correlación lógica con crm.clientes.mae_clientes (sin FK física)';

COMMENT ON COLUMN fuerza_ventas.trx_pedidos.local_entrega_id IS
    'Correlación lógica con crm.clientes.mae_locales_cliente (sin FK física)';

COMMENT ON COLUMN fuerza_ventas.trx_pedidos.promotor_id IS
    'Referencia a fuerza_ventas.mae_promotores (FK compuesta por empresa_id)';

COMMENT ON COLUMN fuerza_ventas.trx_pedidos.sucursal_id IS
    'Correlación lógica con core.identidad.mae_sucursales (sin FK física)';

COMMENT ON COLUMN fuerza_ventas.trx_pedidos.visita_id IS
    'Referencia a fuerza_ventas.trx_visitas (FK compuesta por empresa_id)';

COMMENT ON COLUMN fuerza_ventas.trx_pedidos.numero_pedido IS
    'Número correlativo comercial del pedido';

COMMENT ON COLUMN fuerza_ventas.trx_pedidos.fecha_pedido IS
    'Fecha y hora de emisión';

COMMENT ON COLUMN fuerza_ventas.trx_pedidos.fecha_entrega_estimada IS
    'Fecha comprometida de despacho';

COMMENT ON COLUMN fuerza_ventas.trx_pedidos.canal_id IS
    'Correlación lógica con crm.clientes.cat_canales_comerciales';

COMMENT ON COLUMN fuerza_ventas.trx_pedidos.termino_pago_id IS
    'Correlación lógica con crm.clientes.cat_terminos_pago';

COMMENT ON COLUMN fuerza_ventas.trx_pedidos.tipo_envio_id IS
    'Correlación lógica con crm.clientes.cat_tipos_envio';

COMMENT ON COLUMN fuerza_ventas.trx_pedidos.monto_subtotal IS
    'Subtotal antes de descuentos e impuestos';

COMMENT ON COLUMN fuerza_ventas.trx_pedidos.monto_descuento IS
    'Descuento comercial global';

COMMENT ON COLUMN fuerza_ventas.trx_pedidos.monto_impuestos IS
    'Total de tributos (IVA)';

COMMENT ON COLUMN fuerza_ventas.trx_pedidos.monto_total IS
    'Monto neto final del pedido';

COMMENT ON COLUMN fuerza_ventas.trx_pedidos.estado_pedido IS
    'BORRADOR, ENVIADO, APROBADO_CREDITO, FACTURADO, DESPACHADO, ENTREGADO, CANCELADO';

COMMENT ON COLUMN fuerza_ventas.trx_pedidos.observaciones IS
    'Instrucciones de entrega o notas comerciales';

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

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

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

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

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

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

ALTER TABLE fuerza_ventas.trx_pedidos
    ENABLE ROW LEVEL SECURITY;

CREATE POLICY rls_trx_pedidos_empresa
    ON fuerza_ventas.trx_pedidos
    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
    );