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_documentosfue fusionado encat_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 ejemplocat_feriados: cada empresa define sus propios feriados nacionales/locales), la tabla incorporaempresa_idy 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_idesUUIDy FK →cat_tipos_identificacion.id(ADR 0005). El valoridentificacionya es único por persona.mae_empresas.tipo_identificacion_idesUUIDy FK →cat_tipos_identificacion.id(ADR 0004).mae_personas.genero_idesUUIDy FK →cat_generos.id(ADR 0005).mae_empresas.pais_id/mae_empresas.ciudad_idpasan a ser FK →cat_paises/cat_ciudades(ADR 0004).cat_feriados.pais_idesUUIDy FK →cat_paises.id.cat_provincias.pais_idesUUIDy 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_documentosNO pertenece al microserviciosvc-documentsde documentación interna del equipo: es un maestro de dominio del núcleo, encore.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);
4. Cómo crecer el catálogo¶
- 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-identidadcomo 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
ENUMen 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_empresasymae_personaspasan 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) incorporanempresa_idy 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.