Saltar a contenido

Especificación Técnica: rel_usuario_accion

Esquema: core.identidad
Base de Datos: core
Servicio: svc-identidad
Propósito: Concede una acción a un usuario o a un tipo de usuario (rol), con alcance por empresa y un único sujeto por fila. Reemplaza a rel_usuario_permiso, rel_usuario_menu y rel_usuario_menu_accion.


1. Justificación y Mejoras de Arquitectura

  • Unifica los permisos en una sola tabla: cada fila otorga UNA acción (accion_id) a UN sujeto, ya sea un usuario (usuario_id) o un tipo de usuario / rol (tipo_usuario_id). La restricción ck_rel_usuario_accion_sujeto (num_nonnulls(...) = 1) exige exactamente uno.
  • Modelo de concesión en dos niveles: tipo_usuario_id define los permisos base del rol y usuario_id registra excepciones individuales. El permiso efectivo de un usuario es la unión de las acciones concedidas a su tipo de usuario más las concedidas directamente a su usuario.
  • cat_tipos_usuario actúa como catálogo de roles; la lista de roles crece agregando filas (p. ej. supervisor, supervisor_junior, cajero) sin cambios de esquema.
  • La jerarquía de menús, módulos y aplicaciones es DERIVADA, no almacenada: accion_id -> cfg_menu_acciones.menu_id -> cfg_menu.padre_id (recursivo) -> cfg_modulos -> cat_aplicaciones. Esto evita duplicar la estructura de navegación en cada concesión.
  • Los índices únicos parciales (uq_rel_usuario_accion_usuario y uq_rel_usuario_accion_tipo) impiden concesiones duplicadas por sujeto, ignorando el sujeto nulo y los registros eliminados (deleted_at).
  • RLS por empresa actual al ser una configuración por empresa.

2. Definiciones de Implementación

Table core.identidad.rel_usuario_accion {
    id                         uuid          [pk, default: `gen_random_uuid()`]
    empresa_id                 bigint        [not null]
    usuario_id                 uuid          [ref: > mae_usuarios.id]
    tipo_usuario_id            uuid          [ref: > cat_tipos_usuario.id]
    accion_id                  uuid          [not null, ref: > cfg_menu_acciones.id]

    // 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 [name: 'ix_rel_usuario_accion_empresa_id']
        usuario_id [name: 'ix_rel_usuario_accion_usuario_id']
        tipo_usuario_id [name: 'ix_rel_usuario_accion_tipo_usuario_id']
        accion_id [name: 'ix_rel_usuario_accion_accion_id']
        // Únicos parciales: WHERE sujeto IS NOT NULL AND deleted_at IS NULL
        (usuario_id, accion_id, empresa_id) [unique, name: 'uq_rel_usuario_accion_usuario']
        (tipo_usuario_id, accion_id, empresa_id) [unique, name: 'uq_rel_usuario_accion_tipo']
    }

    // RLS por empresa actual; un único sujeto por fila (usuario XOR tipo_usuario)
}
CREATE TABLE IF NOT EXISTS core.identidad.rel_usuario_accion (
    id UUID NOT NULL DEFAULT gen_random_uuid() PRIMARY KEY,
    empresa_id BIGINT NOT NULL,
    usuario_id UUID,
    tipo_usuario_id UUID,
    accion_id UUID NOT NULL,

    -- 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 ck_rel_usuario_accion_sujeto CHECK (num_nonnulls(usuario_id, tipo_usuario_id) = 1),
    CONSTRAINT fk_rel_usuario_accion_usuario FOREIGN KEY (usuario_id) REFERENCES core.identidad.mae_usuarios (id),
    CONSTRAINT fk_rel_usuario_accion_tipo_usuario FOREIGN KEY (tipo_usuario_id) REFERENCES core.identidad.cat_tipos_usuario (id),
    CONSTRAINT fk_rel_usuario_accion_accion FOREIGN KEY (accion_id) REFERENCES core.identidad.cfg_menu_acciones (id)
);
CREATE INDEX IF NOT EXISTS ix_rel_usuario_accion_empresa_id ON core.identidad.rel_usuario_accion (empresa_id);
CREATE INDEX IF NOT EXISTS ix_rel_usuario_accion_usuario_id ON core.identidad.rel_usuario_accion (usuario_id);
CREATE INDEX IF NOT EXISTS ix_rel_usuario_accion_tipo_usuario_id ON core.identidad.rel_usuario_accion (tipo_usuario_id);
CREATE INDEX IF NOT EXISTS ix_rel_usuario_accion_accion_id ON core.identidad.rel_usuario_accion (accion_id);
CREATE UNIQUE INDEX IF NOT EXISTS uq_rel_usuario_accion_usuario
    ON core.identidad.rel_usuario_accion (usuario_id, accion_id, empresa_id)
    WHERE usuario_id IS NOT NULL AND deleted_at IS NULL;
CREATE UNIQUE INDEX IF NOT EXISTS uq_rel_usuario_accion_tipo
    ON core.identidad.rel_usuario_accion (tipo_usuario_id, accion_id, empresa_id)
    WHERE tipo_usuario_id IS NOT NULL AND deleted_at IS NULL;

-- Row-Level Security
ALTER TABLE core.identidad.rel_usuario_accion ENABLE ROW LEVEL SECURITY;
CREATE POLICY aislamiento_empresa ON core.identidad.rel_usuario_accion
    FOR ALL
    USING (empresa_id = NULLIF(current_setting('app.current_empresa_id', true), '')::BIGINT);

-- Comentarios
COMMENT ON COLUMN core.identidad.rel_usuario_accion.empresa_id IS 'Empresa';
COMMENT ON COLUMN core.identidad.rel_usuario_accion.usuario_id IS 'Usuario (o NULL si el permiso es por tipo)';
COMMENT ON COLUMN core.identidad.rel_usuario_accion.tipo_usuario_id IS 'Tipo de usuario / rol (o NULL si es por usuario)';
COMMENT ON COLUMN core.identidad.rel_usuario_accion.accion_id IS 'Acción habilitada';