Saltar a contenido

0062. Una entidad por id, buscar entidades y varias por id

Estado: Propuesto Fecha: 2026-11-09 Autor: Kevin Delgado Módulo(s) afectado(s): app/shared/busqueda.py (nuevo), app/domains/usuarios/ (router, service, repository y schemas de entidades), tests/, docs/adr/ Complementa a: ADR 0025

Nota (ADR 0067): mae_personas_juridicas es hoy mae_personas_comerciales y la ruta /juridicas es /comerciales. Este ADR conserva los nombres de su fecha.

Contexto

Otros servicios guardan sólo el entidad_id (un promotor de fuerza de ventas, por ejemplo), y el frontend necesita su nombre. Hoy hay GET /entidades (todas las activas, sin buscar ni paginar) y una por tipo (/personas/{id} y /juridicas/{id}). Por eso el frontend:

  • para mostrar un nombre baja todas las entidades, o prueba como persona y, si da 404, como jurídica;
  • para elegir una persona (al crear un promotor) baja todas;
  • para los nombres de una tabla (agenda, pedidos, requerimientos) baja todas.

Con miles de personas cada pantalla descarga la lista entera.

Decisión

Tres lecturas nuevas en el router de entidades, con la misma autenticación (get_current_user: token normal o administrativo root). GET /entidades y las de cada tipo no cambian.

  • GET /entidades/{entidad_id} → EntidadDetalleRead: los campos de EntidadResumenRead más nombres, apellidos, email, telefono y direccion (de una persona natural) y pais_id y ciudad_id (de una jurídica); los que no son de su tipo viajan en null. Activa o inactiva (is_activo lo dice); 404 si no existe o está borrada.
  • GET /entidades/buscar?q=&limite=&offset= → {items: EntidadResumenRead[], hay_mas}, el contrato de los buscadores para elegir de svc-clientes (su ADR 0038): limite de 1 a 50 (10 por defecto), hay_mas pidiendo una fila de más, sin contar. Sólo las activas. q: cada palabra (hasta cinco) debe estar en los nombres, los apellidos, la razón social, el nombre comercial o la identificación, sin distinguir mayúsculas ni tildes. Orden: nombre_mostrar e id.
  • GET /entidades/por-ids?ids=…&ids=… (de 1 a 100) → list[EntidadResumenRead] en una sola consulta: los nombres de una tabla. Activas e inactivas; las que no existen o están borradas no vienen (no es error). Orden: nombre_mostrar e id.
  • Las tres van antes de /{entidad_id}, para que buscar y por-ids no se lean como un id.
  • app/shared/busqueda.py (nuevo, copia del de svc-clientes): partir lo buscado en palabras, comparar sin tildes con translate(lower()) (sin la extensión unaccent) y la página con hay_mas.
  • nombre_mostrar sigue la regla de siempre (ADR 0022 transversal): "nombres apellidos" o la razón social, armado en la consulta como en listar_entidades.
  • Sólo se agrega código: ninguna función existente cambia.

Alternativas descartadas

  • Paginar GET /entidades. Lo usan otras pantallas y servicios tal como está.
  • {items, total} en el buscador. Contar todas las entidades en cada letra que se escribe no le sirve a un campo para elegir; el total es para las tablas.
  • POST con los ids en el cuerpo. Es una lectura; con hasta 100 ids la URL alcanza.
  • La extensión unaccent. Pide permisos en la base; translate hace lo mismo y es IMMUTABLE (sirve a un índice de trigramas si después hace falta).

Consecuencias

  • El frontend deja de bajar todas las entidades: la ficha de un promotor pide la suya por id (con correo y teléfono), el campo "Persona o empresa" busca al escribir, y las tablas piden los nombres de sus filas en una llamada.
  • Buscar sin índice recorre las dos tablas (como listar_entidades); un índice de trigramas sobre las columnas normalizadas se agrega si hace falta, sin cambiar la consulta.
  • Los otros servicios pueden usar por-ids para validar o nombrar varias entidades a la vez.