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_juridicases hoymae_personas_comercialesy la ruta/juridicases/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 deEntidadResumenReadmásnombres,apellidos,email,telefonoydireccion(de una persona natural) ypais_idyciudad_id(de una jurídica); los que no son de su tipo viajan ennull. Activa o inactiva (is_activolo 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):limitede 1 a 50 (10 por defecto),hay_maspidiendo 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_mostrareid.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_mostrareid.- Las tres van antes de
/{entidad_id}, para quebuscarypor-idsno se lean como un id. app/shared/busqueda.py(nuevo, copia del de svc-clientes): partir lo buscado en palabras, comparar sin tildes contranslate(lower())(sin la extensiónunaccent) y la página conhay_mas.nombre_mostrarsigue la regla de siempre (ADR 0022 transversal): "nombres apellidos" o la razón social, armado en la consulta como enlistar_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; eltotales para las tablas.POSTcon los ids en el cuerpo. Es una lectura; con hasta 100 ids la URL alcanza.- La extensión
unaccent. Pide permisos en la base;translatehace 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-idspara validar o nombrar varias entidades a la vez.