Saltar a contenido

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_entidad hoy es PERSONA o PERSONA_COMERCIAL (antes PERSONA_NATURAL o PERSONA_JURIDICA), /juridicas es /comerciales y listar_personas_juridicas es listar_personas_comerciales. EntidadResumenRead suma tipo_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/entidades devuelve list[EntidadResumenRead]: las personas naturales y jurídicas activas en una sola lista.
  • Sólo las activas y no borradas (is_activo y deleted_at IS NULL). /personas y /juridicas sólo excluyen las borradas.
  • Sin paginación ni filtros, como /personas y /juridicas.
  • Bajo el router de entidades, con la misma dependencia de sesión y el mismo esquema Bearer.
  • EntidadResumenRead trae los campos de auditoría y, además:
  • tipo_entidad: PERSONA_NATURAL o PERSONA_JURIDICA.
  • nombre_mostrar, con la regla de la plataforma que ya usa MaeUsuariosRead (ADR 0022 transversal): nombres apellidos en una persona natural, la razón social en una jurídica.
  • nombre_comercial, sólo en una jurídica; en una natural viaja en null.
  • identificacion y tipo_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 /personas y /juridicas por 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 JOIN desde mae_entidades — une tres tablas cuando cada tipo ya está en la suya, y necesita coalesce para 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_activo y deleted_at en las dos partes del UNION ALL.
  • El SQL (tipo, nombre visible, filtro y orden) no tiene prueba de integración (la carpeta tests/integration está 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_id desde otros servicios: sigue pendiente un endpoint de existencia o un adaptador (svc-fuerza-ventas, ADR 0047).