0067. Persona comercial y tipo de contribuyente¶
Estado: Aceptado Fecha: 2026-11-16 Autor: Duval Alcivar Módulo(s) afectado(s): app/domains/usuarios/, app/domains/navegacion/plantilla.py, alembic/versions/, tests/, docs/adr/
Contexto¶
El patrón party (ADR 0025) clasificaba a las entidades en PERSONA_NATURAL y
PERSONA_JURIDICA. Ese eje mezcla dos cosas distintas: la naturaleza de la
entidad (un humano o un sujeto comercial) y el régimen tributario (persona
natural o sociedad). Un profesional con RUC es una persona natural en lo
tributario, pero no cabía en ninguna de las dos tablas sin forzar el modelo.
Además, la cédula o el pasaporte y el RUC son identificaciones de sujetos legales distintos: la primera identifica a la persona; el RUC, a quien factura.
Decisión¶
mae_entidades.tipo_entidadpasa aPERSONAyPERSONA_COMERCIAL.mae_personas_juridicaspasa amae_personas_comerciales(modeloMaePersonasComerciales). La cédula y el pasaporte siguen enmae_personas; el RUC vive enmae_personas_comerciales.- Se agrega
mae_personas_comerciales.tipo_contribuyente(String(20),NOT NULL,CHECKenPERSONA_NATURALoPERSONA_JURIDICA). Es obligatorio al crear, editable por el administrador y se expone en las lecturas, el perfil y la lista común de entidades (nullen las personas). - Un mismo humano puede existir como dos entidades independientes: una
PERSONAy unaPERSONA_COMERCIAL. No hay vínculo ni clave foránea entre ambas. - Las rutas
/juridicasy/admin/juridicaspasan a/comercialesy/admin/comerciales, sin alias: es un renombrado duro. En la plantilla de navegación,persona_juridicapasa apersona_comercial(ruta/config/entidades/personas-comerciales) ypersona_naturalpasa apersona(nombre "Personas", ruta/config/entidades/personas). - La migración
20261116_001convierte los datos: las filas existentes quedan contipo_contribuyente = 'PERSONA_JURIDICA'y el menú de todas las empresas se renombra. Eldowngraderevierte todo menostipo_contribuyente, que se pierde con la columna. - No se valida el formato del RUC según
tipo_contribuyente: queda fuera de alcance. - Nombres de constraints e índices legibles, nunca recortados. PostgreSQL
admite 63 caracteres; si la
naming_conventionlos supera, SQLAlchemy recorta el nombre y le agrega un sufijo de hash que nadie recuerda ni puede buscar. En ese caso se declara unname=explícito y legible: la FK detipo_identificacion_idse llamafk_mae_personas_comerciales_tipo_identificacion_id. La migración no escribe el nombre recortado que existía: ubica esa FK por su columna enpg_constrainty la renombra. La regla vale para todo el servicio y la garantiza un test sobre todas las tablas.
Alternativas descartadas¶
- Vincular la persona con su comercial por clave foránea — YAGNI. Hoy nada
consume el vínculo y rellenarlo después es barato: el RUC de una persona
natural es su cédula más
001, salvo con pasaporte, donde hay que resolverlo a mano. - Mantener
PERSONA_JURIDICAy agregar un tercer valor para el profesional con RUC — deja el eje mezclado y duplica el criterio tributario. - Conservar las rutas viejas como alias — el único consumidor es el frontend, que se actualiza junto con este cambio.
Consecuencias¶
- Los clientes que enviaban
PERSONA_NATURALoPERSONA_JURIDICAcomotipo_entidad, ojuridicaen el alta, reciben422. Hay que desplegar el frontend junto con el servicio. - Un alta de persona comercial sin
tipo_contribuyenteresponde422. - Las entradas de menú copiadas por empresa se actualizan en la migración; los
roles y permisos apuntan a las acciones por
id, no por código. - Una persona comercial con
PERSONA_NATURALvuelve comoPERSONA_JURIDICAal hacerdowngrade.
Verificación¶
- Pruebas unitarias del service, los schemas, el router, los modelos y la
plantilla: tipo de contribuyente obligatorio y validado, rechazo de los
valores viejos de
tipo_entidad, perfilPERSONA_COMERCIALcontipo_contribuyentey rutas viejas inexistentes. alembic headsdevuelve un solo head yalembic upgrade/downgrade --sqlgenera el SQL de ida y de vuelta.test_ningun_nombre_de_constraint_ni_indice_se_recorta_en_postgresqlrecorre todas las tablas y falla si algún nombre no cabe en 63 caracteres.- Ensayo real sobre una base PostgreSQL 18:
upgrade,downgradeyupgradede nuevo, partiendo del nombre recortado original de la FK; datos, menú y constraints verificados en cada paso.