0050. Lista común de entidades (personas naturales y jurídicas)¶
Estado: Aceptado (enmendado por 0067) Fecha: 2026-10-22 Autor: Kevin Delgado Módulo(s) afectado(s): app/domains/usuarios/, docs/adr/
Nota (ADR 0067):
tipo_entidadhoy esPERSONAoPERSONA_COMERCIAL(antesPERSONA_NATURALoPERSONA_JURIDICA),/juridicases/comercialesylistar_personas_juridicaseslistar_personas_comerciales.EntidadResumenReadsumatipo_contribuyente. Este ADR conserva los nombres de su fecha.
Contexto¶
Las entidades siguen el patrón party (ADR 0025): la raíz mae_entidades y sus
dos hijas, mae_personas y mae_personas_juridicas, que repiten su id. Para
leerlas hay dos listas separadas, GET /entidades/personas y
GET /entidades/juridicas.
Otros servicios guardan sólo el id de la entidad. svc-fuerza-ventas pasó de
persona_id a entidad_id en sus promotores (su ADR 0047): un promotor puede
ser una persona natural o una jurídica. Para mostrar a cualquier entidad por su
id, o para elegirla en un formulario, el frontend tenía que hacer dos pedidos,
unirlos y repetir la regla del nombre visible.
Decisión¶
GET /api/v1/entidadesdevuelvelist[EntidadResumenRead]: las personas naturales y jurídicas activas en una sola lista.- Sólo las activas y no borradas (
is_activoydeleted_at IS NULL)./personasy/juridicassólo excluyen las borradas. - Sin paginación ni filtros, como
/personasy/juridicas. - Bajo el router de entidades, con la misma dependencia de sesión y el mismo esquema Bearer.
EntidadResumenReadtrae los campos de auditoría y, además:tipo_entidad:PERSONA_NATURALoPERSONA_JURIDICA.nombre_mostrar, con la regla de la plataforma que ya usaMaeUsuariosRead(ADR 0022 transversal):nombres apellidosen una persona natural, la razón social en una jurídica.nombre_comercial, sólo en una jurídica; en una natural viaja ennull.identificacionytipo_identificacion_id.
Para los demás datos (correo, teléfono, país…) siguen /personas/{id} y
/juridicas/{id}.
- Una sola consulta, con las capas del dominio:
- Repository: EntidadesRepository.listar_entidades, un UNION ALL de
las dos listas por tipo (las mismas tablas que listar_personas y
listar_personas_juridicas, con el filtro de borrado lógico y además el
de is_activo). Cada parte
arma los campos del contrato: el tipo sale de la tabla (patrón party) y
nombre_mostrar es nombres || ' ' || apellidos o nombre. La base
devuelve la lista ya ordenada por nombre_mostrar (y por id).
- Service: EntidadesService.listar_entidades sólo pasa cada fila a
EntidadResumenRead (model_validate). Devuelve el contrato y no la
fila para no importar SQLAlchemy fuera del repository.
- Router: delega en el service, como los demás endpoints de entidades.
- Por qué UNION ALL: es una sola ida a la base y cada parte lee sólo su
tabla, sin unir mae_entidades. Medido contra la base de desarrollo, con
los mismos datos: /entidades tarda unos 2,2 s; /personas + /juridicas
por separado, unos 4,9 s.
- Sólo se agrega código: un schema, un método del repository, uno del
service, una ruta y sus pruebas. No se modifica nada existente.
Alternativas descartadas¶
- Que el frontend pida
/personasy/juridicaspor separado — son dos pedidos en cada pantalla, y la regla del nombre visible repetida en cada cliente. - Juntar en el service las dos listas que ya da el repository — dos idas a la base en cada pedido.
- Una consulta con
LEFT JOINdesdemae_entidades— une tres tablas cuando cada tipo ya está en la suya, y necesitacoalescepara cada campo. - Una respuesta agrupada (
{personas, juridicas}) — obliga al cliente a unir los dos grupos para mostrar o elegir una entidad.
Consecuencias¶
- OpenAPI suma un endpoint de lectura y un schema. Las listas por tipo no cambian.
- Un servicio que guarda
entidad_id(promotores, usuarios) puede mostrar o elegir a cualquier entidad con un solo pedido. - Pruebas unitarias:
- Service (repository falso): pasa las filas al contrato.
- Router (service falso): responde 200 con el schema.
- Repository (sesión falsa): el SQL compilado filtra
is_activoydeleted_aten las dos partes delUNION ALL. - El SQL (tipo, nombre visible, filtro y orden) no tiene prueba de
integración (la carpeta
tests/integrationestá vacía). Se verificó contra la base de desarrollo: devuelve las 6 personas y la jurídica, los mismos registros que/personas+/juridicas, ordenados por nombre.
Qué no cubre¶
- Búsqueda (
?q=) y paginación: se agregan cuando haga falta, en las tres listas. - Las entidades inactivas o borradas: no aparecen en esta lista. Un
servicio que guarde el id de una entidad desactivada o borrada no la
encuentra aquí; para resolverla sigue
/personas/{id}o/juridicas/{id}. - Validar
entidad_iddesde otros servicios: sigue pendiente un endpoint de existencia o un adaptador (svc-fuerza-ventas, ADR 0047).