Saltar a contenido

Especificación Técnica: cfg_secuencia_pedido

Esquema: fuerza_ventas
Base de Datos: crm
Servicio: svc-fuerza-ventas
Tabla Legacy Origen: Secuencias anuales centralizadas de pedidos
Propósito: Control y generación atómica de correlativos numéricos secuenciales de pedidos de preventa/autoventa por tenant y año fiscal.


1. Justificación y Mejoras de Arquitectura

  • Secuenciación Atómica y Anualizada: Administra la numeración de pedidos comerciales garantizando la unicidad compuesta UNIQUE (empresa_id, anio) para evitar huecos, bloqueos masivos o colisiones entre distintos períodos fiscales.
  • Aislamiento Multi-Tenant (RLS): Integra empresa_id BIGINT NOT NULL indexado, asegurado con políticas PostgreSQL Row-Level Security (USING y WITH CHECK) vía app.current_empresa_id.
  • Integridad y Restricciones CHECK: Asegura que el año de facturación/pedido pertenezca a un rango válido (CHECK (anio >= 2000 AND anio <= 2100)) y que el contador sea no negativo (CHECK (ultimo_numero >= 0)).
  • Trazabilidad y Auditoría: Registro de creación y modificación con created_at, created_by, updated_at y updated_by.

2. Definiciones de Implementación

Table fuerza_ventas.cfg_secuencia_pedido {
    id                          bigint      [pk, increment, note: 'Identificador interno autogenerado']
    empresa_id                  bigint        [not null, note: 'Identificador BIGINT de la empresa en core.identidad (RLS)']
    anio                        smallint      [not null, note: 'Año fiscal de la secuencia del pedido']
    ultimo_numero               bigint        [not null, default: 0, note: 'Último número de secuencia generado para el año']

    // Auditoría General
    created_at                  timestamptz   [not null, default: `now()`, note: 'Fecha y hora de creación de la fila']
    created_by                  uuid          [note: 'Usuario que creó la fila en core.identidad']
    updated_at                  timestamptz   [not null, default: `now()`, note: 'Fecha y hora de última modificación']
    updated_by                  uuid          [note: 'Usuario que realizó la última modificación']

    Indexes {
        (empresa_id, id) [unique, name: 'uq_cfg_secuencia_pedido_empresa_id']
        (empresa_id, anio) [unique, name: 'uq_cfg_secuencia_pedido_empresa_anio']
        empresa_id [name: 'ix_cfg_secuencia_pedido_empresa_id']
    }
}
CREATE TABLE IF NOT EXISTS fuerza_ventas.cfg_secuencia_pedido (
    id BIGINT GENERATED ALWAYS AS IDENTITY,
    empresa_id BIGINT NOT NULL,
    anio SMALLINT NOT NULL,
    ultimo_numero BIGINT NOT NULL DEFAULT 0,

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

    CONSTRAINT pk_cfg_secuencia_pedido
        PRIMARY KEY (id),

    CONSTRAINT uq_cfg_secuencia_pedido_empresa_id
        UNIQUE (empresa_id, id),

    CONSTRAINT uq_cfg_secuencia_pedido_empresa_anio
        UNIQUE (empresa_id, anio),

    CONSTRAINT ck_cfg_secuencia_pedido_anio_valido
        CHECK (anio >= 2000 AND anio <= 2100),

    CONSTRAINT ck_cfg_secuencia_pedido_ultimo_numero_positivo
        CHECK (ultimo_numero >= 0)
);

-- Índices
CREATE INDEX IF NOT EXISTS ix_cfg_secuencia_pedido_empresa_id
    ON fuerza_ventas.cfg_secuencia_pedido (empresa_id);

CREATE INDEX IF NOT EXISTS ix_cfg_secuencia_pedido_empresa_anio
    ON fuerza_ventas.cfg_secuencia_pedido (empresa_id, anio);

-- Comentarios de Documentación
COMMENT ON TABLE fuerza_ventas.cfg_secuencia_pedido IS
    'Configuración y control de secuencias y correlativos numéricos de pedidos de venta por año y empresa.';

COMMENT ON COLUMN fuerza_ventas.cfg_secuencia_pedido.id IS
    'Identificador interno autogenerado.';

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

COMMENT ON COLUMN fuerza_ventas.cfg_secuencia_pedido.anio IS
    'Año fiscal de la secuencia del pedido.';

COMMENT ON COLUMN fuerza_ventas.cfg_secuencia_pedido.ultimo_numero IS
    'Último número de secuencia generado para el año.';

COMMENT ON COLUMN fuerza_ventas.cfg_secuencia_pedido.created_at IS
    'Fecha y hora de creación de la fila.';

COMMENT ON COLUMN fuerza_ventas.cfg_secuencia_pedido.created_by IS
    'Usuario que creó la fila en core.identidad.';

COMMENT ON COLUMN fuerza_ventas.cfg_secuencia_pedido.updated_at IS
    'Fecha y hora de última modificación.';

COMMENT ON COLUMN fuerza_ventas.cfg_secuencia_pedido.updated_by IS
    'Usuario que realizó la última modificación.';

-- Row Level Security (RLS)
ALTER TABLE fuerza_ventas.cfg_secuencia_pedido
    ENABLE ROW LEVEL SECURITY;

CREATE POLICY rls_cfg_secuencia_pedido_empresa
    ON fuerza_ventas.cfg_secuencia_pedido
    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
    );