0025. Validar por API las referencias a svc-identidad: tipo de identificación y ciudad¶
Estado: Propuesto Fecha: 2026-10-22 Autor: Kevin Delgado Lopez Módulo(s) afectado(s): app/adaptadores/, app/domains/clientes/, app/core/config.py, app/main.py, tests/unit/adaptadores/, tests/unit/clientes/
Contexto¶
svc-clientes guarda referencias a otros servicios solo como UUID, sin FK (ADR
transversal 0003): mae_clientes.tipo_identificacion_id y ciudad_id de
locales y prospectos (core-svc-identidad), y promotor_id
(crm-svc-fuerza-ventas). Nadie validaba esos UUID: POST /api/v1/clientes
guardaba cualquier UUID bien formado como tipo de identificación.
El ADR transversal 0003 manda comunicarse por API contractual o por eventos,
nunca por SQL cruzado. No hay bus todavía, así que para validar al escribir
se usa la API. crm-svc-fuerza-ventas ya resolvió lo mismo con svc-clientes: un
puerto por dominio, un adaptador por servicio y endpoints livianos existe.
Identidad no tenía endpoints así, solo la ficha completa.
Decisión¶
- En core-svc-identidad (rama
feat/catalogos-existe), dos rutas encatalogos_lectura_router(catálogos globales, sin RLS, token normal):
| Ruta | Responde |
|---|---|
GET /api/v1/catalogos/tipos-identificacion/existe/{tipo_id} |
true o false |
GET /api/v1/catalogos/ciudades/existe/{ciudad_id} |
true o false |
Una sola consulta SELECT EXISTS. Nunca 404: inexistente o borrado
(deleted_at) es false.
- En svc-clientes, el molde de fuerza-ventas:
app/domains/clientes/puertos.py Identidad (Protocol): existe_tipo_identificacion, existe_ciudad
app/adaptadores/identidad/
cliente_http.py IdentidadHttp: las rutas existe
dependencias.py cliente HTTP compartido y dependencia de FastAPI
El puerto es del dominio que lo usa: dice lo que clientes necesita, no copia
la API de identidad. El adaptador no importa de los dominios. El router
inyecta el adaptador en ClienteService, que no sabe de HTTP.
-
Conexión: se reenvía el token del usuario (no hay token de servicio). Un
httpx2.AsyncClientpor proceso enapp.state, cerrado en ellifespan.ADAPTADOR_IDENTIDAD_URLes opcional (sin ella, solo lo que consulta identidad da 503) ySERVICIOS_TIMEOUT_SECvale 5.httpx2pasa a dependencia de producción. -
Falla cerrado:
false→ 404 "No se encontró el registro … en tipos de identificación" (o "en ciudades"). Cualquier otra cosa (404 de la ruta, otro status, algo que no es un booleano, red caída, timeout, sin URL) → 503 "El servicio de identidad no está disponible". El detalle va solo al log, nunca el token. -
Dónde se valida, siempre después de las validaciones locales:
| Operación | Cuándo consulta |
|---|---|
| Crear cliente | Siempre |
| Editar cliente | Solo si cambia el tipo de identificación |
| Convertir prospecto con cliente nuevo | Siempre, antes de bloquear el prospecto (FOR UPDATE): ninguna llamada HTTP con una fila bloqueada |
| Convertir enlazando un cliente | Nunca |
| Crear local o prospecto | Solo si trae ciudad_id |
| Editar local o prospecto | Solo si trae ciudad_id y cambia |
Alternativas descartadas¶
- Usar la ficha que ya existía en identidad (
GET .../{id}) — trae la fila completa para responder sí o no. - Carpetas
app/integraciones/puertos/<servicio>/yadaptadores/<servicio>/(primera versión, guardada enparche-validar-tipo-identificacion.patch) — el puerto quedaba ordenado por proveedor y copiaba su API; más capas para un método, y dos estilos en la plataforma. - Leer la base de identidad o copiar el catálogo — prohibido por el ADR transversal 0003; se desincroniza.
- Fallar abierto — deja entrar datos sin validar justo cuando nadie lo nota.
ADAPTADOR_IDENTIDAD_URLobligatoria — el servicio no arrancaría aunque casi nada la use.
Consecuencias¶
- Ya no entran tipos de identificación ni ciudades que no existen en identidad.
- Un tipo borrado en identidad ahora da 404, no 409:
existeno distingue. - Esas escrituras dependen de identidad (503 si cae) y suman una llamada de hasta 5 s. Lecturas y demás operaciones no cambian. Editar sin cambiar la referencia sigue funcionando aunque identidad esté caído.
- El OpenAPI no cambia de campos; solo hay 404 y 503 nuevos.
- Despliegue: primero identidad, después svc-clientes; y declarar
ADAPTADOR_IDENTIDAD_URLen cada entorno. - Pruebas: 522 en verde (458 antes); ruff y mypy en verde. Contra las bases locales (solo lectura), los 3 clientes, 3 locales y 1 prospecto existentes tienen referencias válidas; repetir el cruce en el servidor.
- Pendiente:
promotor_id(endpointexisteen fuerza-ventas y adaptadorapp/adaptadores/fuerza_ventas/); con ese segundo adaptador,_pediry_leerpasan aapp/adaptadores/http.py.
Media página como máximo. Si el ADR crece más que eso, probablemente estás documentando el diseño completo del módulo, no una decisión puntual — separa.