0004. Tablas iniciales del servicio de identidad¶
Estado: Aceptado Fecha: 2026-09-28 Autor: Duval Alcivar Módulo(s) afectado(s): app/domains/, alembic/, tests/, docs/
Nota (ADR 0067):
mae_personas_juridicases hoymae_personas_comerciales. Este ADR conserva los nombres de su fecha.
Contexto¶
El servicio arranca sin modelo de datos: hay que crear el esquema inicial a
partir de los ADR de docs-site (0003-0023) y de las specs de docs-sql. El
plan original de docs-sql traía 32 tablas con el modelo de permisos anterior
(cat_permisos y tres relaciones paralelas), pero el ADR 0023 de docs-site
(Aceptado) unificó la autorización en una sola tabla: rel_usuario_accion.
Decisión¶
Esquema y dominios¶
28 tablas en el esquema identidad, en 5 dominios, generadas con
alembic revision --autogenerate desde los modelos (el ADR 0012 fusionó
cat_tipos_documentos dentro de cat_tipos_identificacion, de ahí el conteo
actual):
usuarios/ -> mae_entidades, mae_personas, mae_personas_juridicas,
cat_tipos_usuario, mae_usuarios, rel_usuario_empresa,
rel_usuario_sucursal, rel_usuario_accion,
trx_refresh_tokens, trx_pre_tokens, log_sesiones
empresas/ -> mae_empresas, mae_documentos, rel_empresa_aplicacion
sucursales/ -> mae_sucursales
navegacion/ -> cat_aplicaciones, cfg_modulos, cfg_menu,
cfg_menu_acciones, cfg_variables_sistemas
catalogos/ -> cat_paises, cat_tipos_identificacion, cat_generos,
cat_monedas, cat_provincias,
cat_ciudades, cat_feriados, cat_bancos
Base común: mixins¶
Toda tabla hereda de Base y combina los mixins de app/core/models.py:
IdMixin -> id UUID (tablas sin empresa)
EmpresaMixin -> id + empresa_id sin FK (18 tablas por empresa)
EmpresaConFkMixin -> id + empresa_id con FK a mae_empresas (3 tablas)
AuditMixin -> is_activo, created_at, updated_at, deleted_at,
created_by, updated_by
El esquema se declara literal (constante ESQUEMA_IDENTIDAD), no desde la
configuración: es un dato estructural por tabla.
Autorización unificada (ADR 0023)¶
Se eliminan cat_permisos, rel_usuario_permiso, rel_usuario_menu y
rel_usuario_menu_accion. La concesión es por acción en
rel_usuario_accion, con sujeto polimórfico (usuario XOR rol) y dos índices
únicos parciales que impiden concesiones duplicadas:
CREATE UNIQUE INDEX uq_rel_usuario_accion_usuario
ON identidad.rel_usuario_accion (usuario_id, accion_id, empresa_id)
WHERE usuario_id IS NOT NULL AND deleted_at IS NULL;
CREATE UNIQUE INDEX uq_rel_usuario_accion_tipo
ON identidad.rel_usuario_accion (tipo_usuario_id, accion_id, empresa_id)
WHERE tipo_usuario_id IS NOT NULL AND deleted_at IS NULL;
Aislamiento por empresa (RLS)¶
RLS en 13 tablas (ADR 0012 transversal). La política estándar filtra por
empresa_id; rel_usuario_sucursal no tiene empresa_id y lo resuelve por
subconsulta a través de mae_sucursales:
-- Política estándar (12 tablas)
CREATE POLICY aislamiento_empresa ON identidad.<tabla>
FOR ALL USING (
empresa_id = NULLIF(current_setting('app.current_empresa_id', true), '')::BIGINT
);
-- rel_usuario_sucursal (sin empresa_id propio)
CREATE POLICY aislamiento_empresa ON identidad.rel_usuario_sucursal
FOR ALL USING (
sucursal_id IN (
SELECT s.id FROM identidad.mae_sucursales s
WHERE s.empresa_id =
NULLIF(current_setting('app.current_empresa_id', true), '')::BIGINT
)
);
Particionado de log_sesiones¶
Crece con cada login, así que va particionada por mes sobre created_at. La PK
es compuesta (id, created_at) — PostgreSQL exige que la columna de partición
esté en la PK — y hay una partición DEFAULT como red de seguridad:
CREATE TABLE identidad.log_sesiones (
id UUID NOT NULL DEFAULT uuidv7(),
created_at TIMESTAMPTZ NOT NULL DEFAULT now(),
PRIMARY KEY (id, created_at)
) PARTITION BY RANGE (created_at);
CREATE TABLE identidad.log_sesiones_default
PARTITION OF identidad.log_sesiones DEFAULT;
Las particiones mensuales (log_sesiones_YYYYMM) las crea y retira el job del
ADR 0021.
Otras decisiones¶
trx_pre_tokens: registra solo eljtidel pre-token de un solo uso (ADR 0018), nunca el token en claro.mae_empresas.idesBIGINTconIdentity: es la única tabla sin UUID, porque su id es elempresa_idque referencia toda la plataforma.- Las políticas RLS, las particiones y el ciclo de FK
mae_documentos ↔ mae_empresasse agregan con SQL en la migración, porque la metadata de SQLAlchemy no puede expresarlos.
Alternativas descartadas¶
- El plan de 32 tablas de
docs-sql— quedó desactualizado: incluíacat_permisosy las tresrel_*que el ADR 0023 eliminó. - Migraciones escritas a mano con helpers (patrón
_columnas_auditoria()) — abandona--autogeneratey arriesga un desvío silencioso contra la metadata. El DRY vive en los mixins de los modelos; las migraciones quedan generadas y explícitas. - RLS desnormalizando
empresa_idenrel_usuario_sucursal— duplica un dato que puede desincronizarse; se eligió la subconsulta. - Un dominio
permisos/— quedó sin tablas tras el ADR 0023; se eliminó.
Consecuencias¶
- Base reproducible con 4 migraciones (
20260925_001a20260928_004); una tabla nueva es modelo +--autogenerate+ aplicar el patrón de RLS/partición si aplica. - El RLS y el particionado viven en SQL de migración, no en la metadata: cada migración nueva que cree una tabla con RLS debe repetir el patrón a mano.
alembic checkreporta un falso positivo de FK con esquema (limitación documentada enalembic/env.py); la base está verificada correcta.- Queda pendiente el seed inicial de catálogos (países, tipos de identificación, etc.) para el primer despliegue.
docs-sqlse actualizó para reflejar las 28 tablas y el modelo unificado (la fusión del ADR 0012 quedó pendiente de sincronizar allí).