0025. CRUD de entidades — patrón party¶
Estado: Aceptado (enmendado por 0067) Fecha: 2026-09-29 Autor: Duval Alcivar Módulo(s) afectado(s): app/domains/usuarios/, tests/unit/usuarios/
Nota (ADR 0067):
PERSONA_NATURALyPERSONA_JURIDICApasaron aPERSONAyPERSONA_COMERCIAL;mae_personas_juridicases hoymae_personas_comercialesy las rutas/juridicasson/comerciales. Este ADR conserva los nombres de su fecha.
Contexto¶
El dominio usuarios agrupa cuatro bloques que el ADR 0005 trata juntos:
entidades (patrón party), credenciales (mae_usuarios), roles y autorización,
y sesiones. Este ADR entrega el primer slice: el CRUD de entidades. Las
tablas mae_entidades, mae_personas y mae_personas_juridicas ya existen
(ADR 0004) y son globales: no llevan empresa_id porque las personas son de la
plataforma, no de una empresa.
Decisión¶
Se implementa el CRUD de entidades bajo /api/v1/entidades, con el patrón
party:
mae_entidadeses la raíz polimórfica y la única tabla que asigna elid(UUID). Sus hijasmae_personas(naturales) ymae_personas_juridicaslo copian sin default, con clave foránea al padre: una entidad no puede ser persona natural y jurídica a la vez, y suidse puede referenciar desde otras tablas sin saber de qué tipo es (mae_usuarios.entidad_id).- El alta es compuesta (
POST /api/v1/entidades): el payload llevatipo_entidady la hija correspondiente. El service valida el tipo y la hija (422«Tipo de entidad inválido») y la unicidad de la identificación por tipo de entidad (409«Ya existe una entidad con esa identificación»). Persiste primero la raíz —que genera elid— y después la hija con ese mismoid. - Listado y detalle separados por tipo:
GET /personas,GET /personas/{entidad_id},GET /juridicas,GET /juridicas/{entidad_id}; losPUTtambién por tipo.DELETE /{entidad_id}borra lógicamente la raíz y la hija (ambas condeleted_ateis_activo = False). - Las reglas de negocio viven en el service (
TipoEntidadInvalidoError,IdentificacionDuplicadaError,EntidadNoEncontradaError) y el router las traduce a422/409/404: el schema compuestoEntidadCreatees un contenedor tipado, no duplica las reglas (ADR 0001 transversal: el service coordina reglas).
Alternativas descartadas¶
- Un dominio
entidadesaparte — el ADR 0005 agrupa los cuatro bloques enusuarios; separar el CRUD de entidades rompería esa agrupación y obligaría a otro repository. - Alta en dos llamadas (raíz y luego hija) — dejaría estados intermedios (raíz sin hija) visibles desde la API y haría el contrato más frágil; el alta compuesta valida tipo e hija en una sola operación.
- Que la hija genere su propio
id— rompería el patrón party: una entidad debe poder referenciarse desdemae_usuarios.entidad_idsin saber de qué tipo es. Sólo la raíz asigna elid.
Consecuencias¶
- Desbloquea el CRUD de usuarios (
mae_usuarios): suentidad_idya puede apuntar a entidades reales. - OpenAPI del servicio suma 8 endpoints bajo
/api/v1/entidades. - El
repository.py,service.pyyrouter.pydel dominiousuariosquedan creados; el slice de credenciales les agregará métodos. - Los schemas
MaeEntidadesRead,MaePersonasReadyMaePersonasJuridicasReadse reutilizan como respuesta; se agregan losCreate/Updatey el payload compuestoEntidadCreate.