Saltar a contenido

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_entidad pasa a PERSONA y PERSONA_COMERCIAL.
  • mae_personas_juridicas pasa a mae_personas_comerciales (modelo MaePersonasComerciales). La cédula y el pasaporte siguen en mae_personas; el RUC vive en mae_personas_comerciales.
  • Se agrega mae_personas_comerciales.tipo_contribuyente (String(20), NOT NULL, CHECK en PERSONA_NATURAL o PERSONA_JURIDICA). Es obligatorio al crear, editable por el administrador y se expone en las lecturas, el perfil y la lista común de entidades (null en las personas).
  • Un mismo humano puede existir como dos entidades independientes: una PERSONA y una PERSONA_COMERCIAL. No hay vínculo ni clave foránea entre ambas.
  • Las rutas /juridicas y /admin/juridicas pasan a /comerciales y /admin/comerciales, sin alias: es un renombrado duro. En la plantilla de navegación, persona_juridica pasa a persona_comercial (ruta /config/entidades/personas-comerciales) y persona_natural pasa a persona (nombre "Personas", ruta /config/entidades/personas).
  • La migración 20261116_001 convierte los datos: las filas existentes quedan con tipo_contribuyente = 'PERSONA_JURIDICA' y el menú de todas las empresas se renombra. El downgrade revierte todo menos tipo_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_convention los supera, SQLAlchemy recorta el nombre y le agrega un sufijo de hash que nadie recuerda ni puede buscar. En ese caso se declara un name= explícito y legible: la FK de tipo_identificacion_id se llama fk_mae_personas_comerciales_tipo_identificacion_id. La migración no escribe el nombre recortado que existía: ubica esa FK por su columna en pg_constraint y 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_JURIDICA y 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_NATURAL o PERSONA_JURIDICA como tipo_entidad, o juridica en el alta, reciben 422. Hay que desplegar el frontend junto con el servicio.
  • Un alta de persona comercial sin tipo_contribuyente responde 422.
  • 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_NATURAL vuelve como PERSONA_JURIDICA al hacer downgrade.

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, perfil PERSONA_COMERCIAL con tipo_contribuyente y rutas viejas inexistentes.
  • alembic heads devuelve un solo head y alembic upgrade/downgrade --sql genera el SQL de ida y de vuelta.
  • test_ningun_nombre_de_constraint_ni_indice_se_recorta_en_postgresql recorre todas las tablas y falla si algún nombre no cabe en 63 caracteres.
  • Ensayo real sobre una base PostgreSQL 18: upgrade, downgrade y upgrade de nuevo, partiendo del nombre recortado original de la FK; datos, menú y constraints verificados en cada paso.