Saltar a contenido

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 en catalogos_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.AsyncClient por proceso en app.state, cerrado en el lifespan. ADAPTADOR_IDENTIDAD_URL es opcional (sin ella, solo lo que consulta identidad da 503) y SERVICIOS_TIMEOUT_SEC vale 5. httpx2 pasa 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>/ y adaptadores/<servicio>/ (primera versión, guardada en parche-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_URL obligatoria — 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: existe no 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_URL en 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 (endpoint existe en fuerza-ventas y adaptador app/adaptadores/fuerza_ventas/); con ese segundo adaptador, _pedir y _leer pasan a app/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.