Saltar a contenido

0026. Validar por API el promotor contra crm-svc-fuerza-ventas

Estado: Propuesto Fecha: 2026-10-26 Autor: David Garcia Módulo(s) afectado(s): app/adaptadores/, app/domains/clientes/, app/core/config.py, app/main.py, tests/unit/adaptadores/, tests/unit/clientes/, tests/unit/core/

Contexto

promotor_id de rel_clientes_promotores y de mae_prospectos es un UUID de crm-svc-fuerza-ventas, sin FK (ADR transversal 0003), y se aceptaba sin validar (ADR 0023). El ADR 0025 dejó el molde para identidad y anotó este pendiente. Fuerza-ventas ya expone GET /api/v1/promotores/existe/{id} (true si existe en la empresa y no está borrado; nunca 404) sin pasar por su alcance: si no, un usuario de clientes que no es promotor recibiría 403.

Decisión

  • El mismo molde que identidad: puerto FuerzaVentas.existe_promotor en app/domains/clientes/puertos.py y adaptador app/adaptadores/fuerza_ventas/ (FuerzaVentasHttp, cliente compartido en app.state.http_fuerza_ventas, dependencia obtener_fuerza_ventas).
  • Lo común a los dos adaptadores pasa a app/adaptadores/http.py, como anticipó el ADR 0025: ClienteRest (_pedir, _leer), BOOLEANO y crear_http. Cada adaptador sólo declara su servicio, su variable y su mensaje 503.
  • Configuración: ADAPTADOR_FUERZA_VENTAS_URL, opcional, con el mismo validador que la de identidad (uno solo para las dos). Comparten SERVICIOS_TIMEOUT_SEC.
  • Falla cerrado, igual que identidad: false → 404 "No se encontró el registro … en promotores"; cualquier otro resultado → 503 "El servicio de fuerza de ventas no está disponible".
  • Dónde se valida, después de las validaciones locales:
Operación Cuándo consulta
Asignar promotor a un cliente Siempre (tras cliente activo y par no repetido)
Crear prospecto Solo si trae promotor_id
Editar prospecto Solo si trae promotor_id y cambia

Alternativas descartadas

  • Un helper genérico por función en vez de clase base — cada llamada repetiría el servicio, la variable y el mensaje.
  • Validar también al convertir el prospecto — la conversión no toca promotor_id.

Consecuencias

  • Ya no entran promotores que no existen o están borrados en fuerza-ventas.
  • Asignar y escribir prospectos con promotor dependen de fuerza-ventas (503 si cae). Editar sin cambiar el promotor, o quitarlo, sigue funcionando.
  • Fuerza-ventas exige el claim entidad_id: un token sin él recibe 401 allá y 503 aquí.
  • Despliegue: primero fuerza-ventas (endpoint existe), después svc-clientes, y declarar ADAPTADOR_FUERZA_VENTAS_URL en cada entorno.
  • Las asignaciones y prospectos ya guardados no se revisan.
  • Pendiente: el nombre del promotor en las respuestas (otro endpoint, de lectura).

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.