Saltar a contenido

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_NATURAL y PERSONA_JURIDICA pasaron a PERSONA y PERSONA_COMERCIAL; mae_personas_juridicas es hoy mae_personas_comerciales y las rutas /juridicas son /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_entidades es la raíz polimórfica y la única tabla que asigna el id (UUID). Sus hijas mae_personas (naturales) y mae_personas_juridicas lo copian sin default, con clave foránea al padre: una entidad no puede ser persona natural y jurídica a la vez, y su id se 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 lleva tipo_entidad y 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 el id— y después la hija con ese mismo id.
  • Listado y detalle separados por tipo: GET /personas, GET /personas/{entidad_id}, GET /juridicas, GET /juridicas/{entidad_id}; los PUT también por tipo. DELETE /{entidad_id} borra lógicamente la raíz y la hija (ambas con deleted_at e is_activo = False).
  • Las reglas de negocio viven en el service (TipoEntidadInvalidoError, IdentificacionDuplicadaError, EntidadNoEncontradaError) y el router las traduce a 422/409/404: el schema compuesto EntidadCreate es un contenedor tipado, no duplica las reglas (ADR 0001 transversal: el service coordina reglas).

Alternativas descartadas

  • Un dominio entidades aparte — el ADR 0005 agrupa los cuatro bloques en usuarios; 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 desde mae_usuarios.entidad_id sin saber de qué tipo es. Sólo la raíz asigna el id.

Consecuencias

  • Desbloquea el CRUD de usuarios (mae_usuarios): su entidad_id ya puede apuntar a entidades reales.
  • OpenAPI del servicio suma 8 endpoints bajo /api/v1/entidades.
  • El repository.py, service.py y router.py del dominio usuarios quedan creados; el slice de credenciales les agregará métodos.
  • Los schemas MaeEntidadesRead, MaePersonasRead y MaePersonasJuridicasRead se reutilizan como respuesta; se agregan los Create/Update y el payload compuesto EntidadCreate.