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 deDATABASE_SCHEMAS. - Nombres explícitos con la tabla completa para UNIQUE, FK e índices; los
CHECKsó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_CONVENTIONpara todo — los UNIQUE compuestos repetirían nombre (uq_<tabla>_empresa_iddos 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.pyy migración con su RLS. Los tests detests/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.