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_promotorenapp/domains/clientes/puertos.pyy adaptadorapp/adaptadores/fuerza_ventas/(FuerzaVentasHttp, cliente compartido enapp.state.http_fuerza_ventas, dependenciaobtener_fuerza_ventas). - Lo común a los dos adaptadores pasa a
app/adaptadores/http.py, como anticipó el ADR 0025:ClienteRest(_pedir,_leer),BOOLEANOycrear_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). CompartenSERVICIOS_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 declararADAPTADOR_FUERZA_VENTAS_URLen 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.