Saltar a contenido

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_juridicas es hoy mae_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 el jti del pre-token de un solo uso (ADR 0018), nunca el token en claro.
  • mae_empresas.id es BIGINT con Identity: es la única tabla sin UUID, porque su id es el empresa_id que referencia toda la plataforma.
  • Las políticas RLS, las particiones y el ciclo de FK mae_documentos ↔ mae_empresas se 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ía cat_permisos y las tres rel_* que el ADR 0023 eliminó.
  • Migraciones escritas a mano con helpers (patrón _columnas_auditoria()) — abandona --autogenerate y 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_id en rel_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_001 a 20260928_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 check reporta un falso positivo de FK con esquema (limitación documentada en alembic/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-sql se actualizó para reflejar las 28 tablas y el modelo unificado (la fusión del ADR 0012 quedó pendiente de sincronizar allí).