Saltar a contenido

0004. Modelos ORM del servicio de clientes

Estado: Propuesto Fecha: 2026-09-28 Autor: Kevin Delgado Lopez Módulo(s) afectado(s): app/core/models.py, app/shared/esquema.py, app/domains/catalogos/, app/domains/clientes/, app/registry.py, alembic/versions/

Contexto

El esquema clientes tiene 16 tablas definidas en docs-sql: 8 catálogos (cat_*), 5 maestras (mae_*), 1 transaccional (trx_*) y 2 relacionales (rel_*). Todas son multiempresa (empresa_id + RLS) y comparten las columnas estándar del ADR 0004 transversal. Hay que fijar cómo se escriben sus modelos SQLAlchemy para que coincidan con docs-sql, se generen bien con --autogenerate y se apliquen en orden en cualquier base.

Decisión

docs-sql es la fuente de verdad de columnas, tipos, restricciones e índices; los modelos lo replican tal cual, y los nombres de clase también salen de ahí (Cliente, LocalCliente…).

Columnas estándar: mixins (app/core/models.py)

Mixin Columna Tipo Descripción
EmpresaMixin id UUID PK, la genera la base con gen_random_uuid()
empresa_id BIGINT NOT NULL Empresa dueña de la fila; la aporta el token y la valida la RLS. Sin default
AuditMixin is_activo BOOLEAN NOT NULL Estado lógico, true por defecto
created_at TIMESTAMPTZ NOT NULL Fecha de creación, now()
updated_at TIMESTAMPTZ NOT NULL Última modificación, now(); el ORM la renueva en cada UPDATE (onupdate)
deleted_at TIMESTAMPTZ Borrado lógico
created_by / updated_by UUID sub del usuario del token que creó / modificó

id y empresa_id van siempre primero y la auditoría al final del CREATE TABLE, igual que en docs-sql.

Forma de cada modelo

Cada tabla es una clase explícita, sin bases abstractas: los mixins aportan las columnas estándar y el modelo declara todas sus columnas de negocio y restricciones.

class TerminoPago(Base, EmpresaMixin, AuditMixin):
    __tablename__ = "cat_terminos_pago"
    __table_args__ = (
        UniqueConstraint("empresa_id", "id", name="uq_cat_terminos_pago_empresa_id"),
        UniqueConstraint(
            "empresa_id", "codigo", name="uq_cat_terminos_pago_empresa_codigo"
        ),
        CheckConstraint("dias_plazo >= 0", name="dias_no_negativos"),
        {"schema": ESQUEMA_CLIENTES},
    )

    codigo: Mapped[str] = mapped_column(String(30), nullable=False)
    nombre: Mapped[str] = mapped_column(String(100), nullable=False)
    dias_plazo: Mapped[int] = mapped_column(SmallInteger, nullable=False)
    descripcion: Mapped[str | None] = mapped_column(Text)
  • Esquema: ESQUEMA_CLIENTES = "clientes" (app/shared/esquema.py), constante; no se lee de DATABASE_SCHEMAS.
  • Nombres explícitos con la tabla completa para UNIQUE, FK e índices; los CHECK sólo llevan el sufijo y la convención los completa:
UniqueConstraint(..., name="uq_cat_terminos_pago_empresa_codigo")  ->  uq_cat_terminos_pago_empresa_codigo
CheckConstraint(..., name="dias_no_negativos")                     ->  ck_cat_terminos_pago_dias_no_negativos
PrimaryKey (automático)                                            ->  pk_cat_terminos_pago

FK compuestas por empresa

Toda FK incluye empresa_id, y toda tabla tiene UNIQUE (empresa_id, id) como destino: una fila nunca apunta a datos de otra empresa.

ForeignKeyConstraint(
    ["empresa_id", "cliente_id"],
    ["clientes.mae_clientes.empresa_id", "clientes.mae_clientes.id"],
    name="fk_mae_locales_cliente_cliente",
)

Las referencias a otros servicios son UUID sin FK: tipo_identificacion_id y ciudad_id (core), promotor_id (svc-fuerza-ventas).

Dominios

app/domains/
├── catalogos/models.py   # cat_*  (8 tablas)
└── clientes/models.py    # mae_*, trx_*, rel_*  (8 tablas)

clientes apunta a los catálogos por nombre de tabla ("clientes.cat_…"), sin importar el dominio catalogos.

Migraciones en orden de dependencias

Los modelos de cada grupo se escriben recién en su etapa, porque --autogenerate compara todos los modelos registrados en app/registry.py:

20260925_001  catálogos        cat_*
      ▼
20260927_001  maestras         mae_*   (+ función y trigger de locales)
      ▼
20260927_002  transaccionales  trx_*
      ▼
20260927_003  relacionales     rel_*   (+ FK circular)

FK circular: mae_clientes.contacto_principal_id apunta a rel_clientes_contactos, que a su vez apunta a mae_clientes. Se declara con use_alter=True y se crea con ALTER TABLE al final de la migración de relacionales, cuando ya existen las dos tablas:

ForeignKeyConstraint(
    ["empresa_id", "id", "contacto_principal_id"],
    [
        "clientes.rel_clientes_contactos.empresa_id",
        "clientes.rel_clientes_contactos.cliente_id",
        "clientes.rel_clientes_contactos.contacto_id",
    ],
    name="fk_mae_clientes_contacto_principal",
    use_alter=True,
)

Lo que el modelo no expresa (RLS, función y trigger de locales) va escrito a mano en la migración (ADR 0003).

Tablas del modelo

Tabla Clase Dominio
cat_canales_comerciales CanalComercial catalogos
cat_clases_cliente ClaseCliente catalogos
cat_estados_prospecto EstadoProspecto catalogos
cat_modelos_comerciales ModeloComercial catalogos
cat_terminos_pago TerminoPago catalogos
cat_unidades_comerciales UnidadComercial catalogos
cat_tipos_canal_comercial TipoCanalComercial catalogos
cat_tipos_clientes TipoCliente catalogos
mae_grupos_economicos GrupoEconomico clientes
mae_contactos_cliente ContactoCliente clientes
mae_clientes Cliente clientes
mae_locales_cliente LocalCliente clientes
mae_prospectos Prospecto clientes
trx_perfil_financiero_cliente PerfilFinancieroCliente clientes
rel_clientes_contactos ClienteContacto clientes
rel_clientes_promotores ClientePromotor clientes

Detalle de columnas: docs-sql y app/domains/*/models.py.

Alternativas descartadas

  • Usar la NAMING_CONVENTION para todo — los UNIQUE compuestos repetirían nombre (uq_<tabla>_empresa_id dos veces) y PostgreSQL los rechaza.
  • Todas las tablas en un solo dominio o una sola migración — la FK circular y el trigger no pueden ir en el CREATE TABLE, y un archivo único es difícil de revisar y revertir por partes.

Consecuencias

  • Una tabla nueva sigue el mismo molde: mixins, columnas explícitas, FK compuesta, nombres completos, import en app/registry.py y migración con su RLS. Los tests de tests/unit/<dominio>/ comparan cada modelo contra docs-sql sin base de datos.
  • Las mejoras de índices o tipos se proponen en docs-sql primero; aquí no se aplican por cuenta propia.

Media página como máximo. Si el ADR crece más que eso, probablemente estás documentando el diseño completo del módulo, no una decisión puntual — separa.