Saltar a contenido

0003. Catálogos y tablas maestras generales

Estado: Superado por 0024; complementado por ADR 0029 Fecha: 2026-09-08 Autor: Duval Alcivar Módulo(s) afectado(s): svc-identidad (core_sigfa), todos los servicios que referencian los catálogos Complementado por: ADR 0029 - superficie de acceso de catálogos y validación de longitud

Contexto

svc-identidad es el dueño de la identidad digital en toda la plataforma. Además de usuarios, empresas, aplicaciones y permisos, centraliza los catálogos y maestros comunes que otros servicios referencian (cat_/mae_ sin negocio propio), para que no se dupliquen en cada base de datos.

La regla de negocio inicial: el mae_empresas referencia país y ciudad, las personas referencian un tipo de identificación. Hoy esas listas no tienen tabla; este ADR las define con margen para crecer.

Decisión

Crear un conjunto mínimo de catálogos globales (mayoría sin empresa_id, sin RLS: países, provincias, ciudades, monedas, bancos, tipos de documento) y maestros comunes bajo el esquema core.identidad, PK UUID y auditoría estándar. Una tabla nueva solo es un cat_<nombre> o mae_<nombre> nuevo bajo el mismo esquema: no se tocan los servicios.

1. Tablas iniciales

Tabla Contenido Quién la usa
cat_paises países (ISO 3166-1 alfa-3) mae_empresas.pais_id, mae_personas
cat_monedas monedas (ISO 4217) operaciones monetarias del núcleo
cat_ciudades ciudades (provincia_id) mae_empresas.ciudad_id
cat_provincias provincias o regiones (pais_id) geolocalización de sucursales/personas
cat_tipos_identificacion cédula, RUC, pasaporte mae_empresas.tipo_identificacion_id, mae_personas.tipo_identificacion_id
cat_tipos_documentos tipos de documento del núcleo con reglas de validación (longitud_minima, longitud_maxima, expresion_validacion) servicios que validan documentos
cat_generos masculino, femenino, otros mae_personas.genero_id
cat_tipos_usuario usuario, root, externo mae_usuarios.tipo_usuario_id (ADR 0007/0022)
cat_feriados feriados por empresa y país (empresa_id, pais_id, fecha) calendarios laborales, is_recuperable
cat_bancos bancos por empresa (empresa_id, codigo) operaciones contables, financieras y de recaudación

Nota (0024): cat_tipos_documentos fue fusionado en cat_tipos_identificacion — ver 0024.

Todas comparten la misma estructura base:

Campo Tipo Notas
id UUID PK gen_random_uuid()
codigo VARCHAR UNIQUE NOT NULL cuando aplica (ej. EC); no todas las tablas lo llevan
nombre VARCHAR NOT NULL, nombre legible
is_activo BOOLEAN NOT NULL, DEFAULT true
created_at / updated_at TIMESTAMPTZ NOT NULL, default now()
deleted_at TIMESTAMPTZ NULL, soft delete
created_by / updated_by UUID auditoría

La mayoría son catálogos globales (sin empresa_id, sin RLS) que todas las empresas comparten. Sin embargo, un catálogo global no obliga a ser global en todo su contenido: cuando el dato depende del contexto empresarial (por ejemplo cat_feriados: cada empresa define sus propios feriados nacionales/locales), la tabla incorpora empresa_id y aplica RLS aun formando parte del conjunto de catálogos de identidad. La regla se decide tabla a tabla en su especificación.

CREATE TABLE core.identidad.cat_paises (
    id         UUID PRIMARY KEY DEFAULT gen_random_uuid(),
    codigo     VARCHAR(3)  NOT NULL,
    nombre     VARCHAR(100) NOT NULL,
    is_activo  BOOLEAN NOT NULL DEFAULT true,
    created_at TIMESTAMPTZ NOT NULL DEFAULT now(),
    updated_at TIMESTAMPTZ NOT NULL DEFAULT now(),
    deleted_at TIMESTAMPTZ NULL,
    created_by UUID,
    updated_by UUID,
    CONSTRAINT uq_cat_paises_codigo UNIQUE (codigo)
);

CREATE TABLE core.identidad.cat_monedas (
    id         UUID PRIMARY KEY DEFAULT gen_random_uuid(),
    codigo     VARCHAR(10) NOT NULL,
    nombre     VARCHAR(100) NOT NULL,
    simbolo    VARCHAR(5),
    is_activo  BOOLEAN NOT NULL DEFAULT true,
    created_at TIMESTAMPTZ NOT NULL DEFAULT now(),
    updated_at TIMESTAMPTZ NOT NULL DEFAULT now(),
    deleted_at TIMESTAMPTZ NULL,
    created_by UUID,
    updated_by UUID,
    CONSTRAINT uq_cat_monedas_codigo UNIQUE (codigo)
);

CREATE TABLE core.identidad.cat_provincias (
    id         UUID PRIMARY KEY DEFAULT gen_random_uuid(),
    pais_id    UUID NOT NULL,
    nombre     VARCHAR(100) NOT NULL,
    is_activo  BOOLEAN NOT NULL DEFAULT true,
    created_at TIMESTAMPTZ NOT NULL DEFAULT now(),
    updated_at TIMESTAMPTZ NOT NULL DEFAULT now(),
    deleted_at TIMESTAMPTZ NULL,
    created_by UUID,
    updated_by UUID,
    CONSTRAINT fk_cat_provincias_pais
        FOREIGN KEY (pais_id) REFERENCES core.identidad.cat_paises(id)
);

CREATE INDEX ix_cat_provincias_pais_id ON core.identidad.cat_provincias (pais_id);

CREATE TABLE core.identidad.cat_ciudades (
    id           UUID PRIMARY KEY DEFAULT gen_random_uuid(),
    provincia_id UUID NOT NULL,
    nombre       VARCHAR(100) NOT NULL,
    is_activo    BOOLEAN NOT NULL DEFAULT true,
    created_at   TIMESTAMPTZ NOT NULL DEFAULT now(),
    updated_at   TIMESTAMPTZ NOT NULL DEFAULT now(),
    deleted_at   TIMESTAMPTZ NULL,
    created_by   UUID,
    updated_by   UUID,
    CONSTRAINT fk_cat_ciudades_provincia
        FOREIGN KEY (provincia_id) REFERENCES core.identidad.cat_provincias (id)
);

CREATE INDEX ix_cat_ciudades_provincia_id ON core.identidad.cat_ciudades (provincia_id);

CREATE TABLE core.identidad.cat_tipos_identificacion (
    id         UUID PRIMARY KEY DEFAULT gen_random_uuid(),
    nombre     VARCHAR(100) NOT NULL,
    is_activo  BOOLEAN NOT NULL DEFAULT true,
    created_at TIMESTAMPTZ NOT NULL DEFAULT now(),
    updated_at TIMESTAMPTZ NOT NULL DEFAULT now(),
    deleted_at TIMESTAMPTZ NULL,
    created_by UUID,
    updated_by UUID
);

CREATE TABLE core.identidad.cat_tipos_documentos (
    id                    UUID PRIMARY KEY DEFAULT gen_random_uuid(),
    codigo                VARCHAR(50) NOT NULL,
    nombre                VARCHAR(100) NOT NULL,
    descripcion           TEXT,
    longitud_minima       INTEGER NOT NULL DEFAULT 0,
    longitud_maxima       INTEGER NOT NULL DEFAULT 0,
    expresion_validacion  VARCHAR(255),
    is_activo             BOOLEAN NOT NULL DEFAULT true,
    created_at            TIMESTAMPTZ NOT NULL DEFAULT now(),
    updated_at            TIMESTAMPTZ NOT NULL DEFAULT now(),
    deleted_at            TIMESTAMPTZ NULL,
    created_by            UUID,
    updated_by            UUID,
    CONSTRAINT uq_cat_tipos_documentos_codigo UNIQUE (codigo)
);

CREATE TABLE core.identidad.cat_generos (
    id         UUID PRIMARY KEY DEFAULT gen_random_uuid(),
    nombre     VARCHAR(100) NOT NULL,
    is_activo  BOOLEAN NOT NULL DEFAULT true,
    created_at TIMESTAMPTZ NOT NULL DEFAULT now(),
    updated_at TIMESTAMPTZ NOT NULL DEFAULT now(),
    deleted_at TIMESTAMPTZ NULL,
    created_by UUID,
    updated_by UUID
);

CREATE TABLE core.identidad.cat_feriados (
    id             UUID PRIMARY KEY DEFAULT gen_random_uuid(),
    empresa_id     BIGINT NOT NULL,
    pais_id        UUID NOT NULL,
    fecha          DATE NOT NULL,
    nombre         VARCHAR(150) NOT NULL,
    is_recuperable BOOLEAN NOT NULL DEFAULT false,
    is_activo      BOOLEAN NOT NULL DEFAULT true,
    created_at     TIMESTAMPTZ NOT NULL DEFAULT now(),
    updated_at     TIMESTAMPTZ NOT NULL DEFAULT now(),
    deleted_at     TIMESTAMPTZ NULL,
    created_by     UUID,
    updated_by     UUID,
    CONSTRAINT uq_cat_feriados_empresa_pais_fecha UNIQUE (empresa_id, pais_id, fecha),
    CONSTRAINT fk_cat_feriados_pais
        FOREIGN KEY (pais_id) REFERENCES core.identidad.cat_paises(id)
);

CREATE INDEX ix_cat_feriados_empresa_id ON core.identidad.cat_feriados (empresa_id);
CREATE INDEX ix_cat_feriados_pais_id ON core.identidad.cat_feriados (pais_id);

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

CREATE TABLE core.identidad.cat_bancos (
    id         UUID PRIMARY KEY DEFAULT gen_random_uuid(),
    empresa_id BIGINT NOT NULL,
    codigo     VARCHAR(20) NOT NULL,
    nombre     VARCHAR(100) NOT NULL,
    is_activo  BOOLEAN NOT NULL DEFAULT true,
    created_at TIMESTAMPTZ NOT NULL DEFAULT now(),
    updated_at TIMESTAMPTZ NOT NULL DEFAULT now(),
    deleted_at TIMESTAMPTZ NULL,
    created_by UUID,
    updated_by UUID,
    CONSTRAINT uq_cat_bancos_empresa_id UNIQUE (empresa_id, id),
    CONSTRAINT uq_cat_bancos_empresa_codigo UNIQUE (empresa_id, codigo)
);

CREATE INDEX ix_cat_bancos_empresa_activo ON core.identidad.cat_bancos (empresa_id, is_activo);

ALTER TABLE core.identidad.cat_bancos ENABLE ROW LEVEL SECURITY;
CREATE POLICY aislamiento_empresa ON core.identidad.cat_bancos
    FOR ALL
    USING (empresa_id = NULLIF(current_setting('app.current_empresa_id', true), '')::BIGINT);
# models.py — SQLAlchemy 2.0
class CatalogoBase:
    """Columnas comunes a todo catálogo. No es un mixin de herencia real,
    se copia por claridad en cada modelo."""
    pass

class CatPais(Base):
    __tablename__ = "cat_paises"
    __table_args__ = {"schema": "core.identidad"}
    id: Mapped[uuid.UUID] = mapped_column(primary_key=True, default=uuid.uuid4)
    codigo: Mapped[str] = mapped_column(String(3), unique=True, nullable=False)
    nombre: Mapped[str] = mapped_column(String(100), nullable=False)
    is_activo: Mapped[bool] = mapped_column(Boolean, default=True)
    created_at: Mapped[datetime] = mapped_column(DateTime(timezone=True), server_default=func.now())
    updated_at: Mapped[datetime] = mapped_column(DateTime(timezone=True), server_default=func.now(), onupdate=func.now())
    deleted_at: Mapped[datetime | None] = mapped_column(DateTime(timezone=True))
    created_by: Mapped[uuid.UUID | None] = mapped_column(as_uuid=True)
    updated_by: Mapped[uuid.UUID | None] = mapped_column(as_uuid=True)

2. Referencias desde otras tablas

  • mae_personas.tipo_identificacion_id es UUID y FK → cat_tipos_identificacion.id (ADR 0005). El valor identificacion ya es único por persona.
  • mae_empresas.tipo_identificacion_id es UUID y FK → cat_tipos_identificacion.id (ADR 0004).
  • mae_personas.genero_id es UUID y FK → cat_generos.id (ADR 0005).
  • mae_empresas.pais_id / mae_empresas.ciudad_id pasan a ser FK → cat_paises / cat_ciudades (ADR 0004).
  • cat_feriados.pais_id es UUID y FK → cat_paises.id.
  • cat_provincias.pais_id es UUID y FK → cat_paises.id.

3. Tablas maestras generales (mae_documentos)

Además de los catálogos, svc-identidad centraliza maestros comunes sin dueño de negocio propio. mae_documentos es el registro de metadatos de los artefactos generados o recibidos por la plataforma (PDF, Excel, imágenes): el binario vive en Object Storage (S3 / MinIO) y aquí solo se guarda la referencia.

Campo Tipo Notas
id UUID PK gen_random_uuid()
empresa_id BIGINT NOT NULL FK → mae_empresas (RLS)
nombre VARCHAR(255) NOT NULL nombre del archivo
tipo_mime VARCHAR(100) NOT NULL MIME del documento
tamano_bytes BIGINT NOT NULL tamaño en bytes
hash_sha256 VARCHAR(64) NOT NULL integridad y deduplicación
url TEXT NOT NULL referencia en Object Storage
svc_origen VARCHAR(50) NOT NULL microservicio que registró el documento
is_activo BOOLEAN NOT NULL DEFAULT true estado lógico del registro
created_at / updated_at TIMESTAMPTZ NOT NULL default now()
deleted_at TIMESTAMPTZ NULL, soft delete
created_by / updated_by UUID auditoría

UNIQUE (empresa_id, hash_sha256). mae_documentos NO pertenece al microservicio svc-documents de documentación interna del equipo: es un maestro de dominio del núcleo, en core.identidad, referenciable desde cualquier servicio (facturas, reportes, actas, evidencias).

CREATE TABLE core.identidad.mae_documentos (
    id           UUID PRIMARY KEY DEFAULT gen_random_uuid(),
    empresa_id   BIGINT NOT NULL,
    nombre       VARCHAR(255) NOT NULL,
    tipo_mime    VARCHAR(100) NOT NULL,
    tamano_bytes BIGINT NOT NULL,
    hash_sha256  VARCHAR(64) NOT NULL,
    url          TEXT NOT NULL,
    svc_origen   VARCHAR(50) NOT NULL,
    is_activo    BOOLEAN NOT NULL DEFAULT true,
    created_at   TIMESTAMPTZ NOT NULL DEFAULT now(),
    updated_at   TIMESTAMPTZ NOT NULL DEFAULT now(),
    deleted_at   TIMESTAMPTZ NULL,
    created_by   UUID,
    updated_by   UUID,
    CONSTRAINT uq_mae_documentos_empresa_hash UNIQUE (empresa_id, hash_sha256)
);

CREATE INDEX ix_mae_documentos_empresa_origen ON core.identidad.mae_documentos (empresa_id, svc_origen);

ALTER TABLE core.identidad.mae_documentos ENABLE ROW LEVEL SECURITY;
CREATE POLICY aislamiento_empresa ON core.identidad.mae_documentos
    FOR ALL
    USING (empresa_id = NULLIF(current_setting('app.current_empresa_id', true), '')::BIGINT);
  • Nuevo catálogo = nueva tabla cat_<nombre> + seed en un script de migración. No se agregan catálogos dentro de tablas de negocio.
  • La carga inicial (seed) vive en el pipeline de svc-identidad como data migration; los catálogos globales no dependen de la empresa.
  • Los servicios consumen los catálogos que necesitan y los cachean; no los duplican en su base (regla de cero consultas entre bases, ADR transversal 0003).

Alternativas descartadas

  • Catálogos en cada servicio — duplica listas (un país diferente por base) y descuadra referencias comunes como país/ciudad.
  • Catálogo como ENUM en código — no es dato gestionable: cualquier país/cuidad nueva requiere despliegue; una tabla no.
  • Colchón de columnas sueltas en mae_empresas — acopla negocio y catálogo; el catálogo es global y reutilizable.

Consecuencias

  • Un solo lugar para países, provincias, ciudades, monedas, bancos, tipos de documento y documentos; los servicios los referencian por FK y los cachean.
  • mae_empresas y mae_personas pasan a tener FKs reales a los catálogos, sin valores sueltos.
  • La mayoría de los catálogos son globales (sin RLS): cualquier empresa los ve igual. Los que dependen del contexto empresarial (p. ej. cat_feriados) incorporan empresa_id y RLS.
  • Pendiente: definir si sucursal necesita catálogo de tipos o si se deja como texto libre; por ahora se usa el texto de mae_sucursales.