0028. Cartera del promotor: alta con promotor y transferencia dentro del alcance¶
Estado: Aceptado Fecha: 2026-10-26 Autor: David Garcia Módulo(s) afectado(s): app/domains/clientes/, app/adaptadores/fuerza_ventas/, tests/unit/
Contexto¶
Dar de alta un cliente no lo asigna a nadie, y cualquier usuario asigna o quita
cualquier promotor (ADR 0023): no hay cartera ni forma de moverla. La cartera
de un promotor son sus clientes con asignación activa en
rel_clientes_promotores y sus prospectos (promotor_id). Fuerza-ventas
expone el alcance del usuario (GET /api/v1/alcance, su ADR 0055):
promotor_id (el suyo o null) y promotor_ids (los que ve; null = todos,
[] = no es promotor). Se consulta por el puerto FuerzaVentas, con el token
del usuario y antes de abrir la transacción.
Decisión¶
- Nada nace sin promotor. Al dar de alta un cliente o un prospecto,
promotor_ides opcional en el body y por defecto es el propio; tiene que estar en el alcance de quien da de alta (403). Quien no es promotor vigente no da de alta (403), tampocoroot(ADR 0027). Vale igual para el administrador y el supervisor. El cliente nace con su asignación en la misma transacción; elpromotor_iddel prospecto deja de ser opcional: en elPUT(que reemplaza la ficha) es obligatorio (422 si falta) y, si cambia, el nuevo tiene que estar en el alcance (403). - Convertir creando un cliente nuevo lo asigna al promotor del prospecto; enlazar uno existente no cambia sus asignaciones.
- Asignar y quitar (
POST/DELETE /clientes-promotores): el promotor de la asignación, en el alcance de quien la hace (403). Un cliente activo no se queda sin promotor: quitar el último es 409. - Transferir (
POST /api/v1/clientes-promotores/transferir:origen_promotor_id,destino_promotor_id,cliente_idsopcional, sin él todos): origen y destino en el alcance (403), distintos (400), el destino vigente (existe, 404). En una sola transacción, por cada asignación activa del origen: se quita y se asigna el destino, salvo que ya estuviera. Uncliente_idsque no es del origen: 409 con todos los casos. Responde los movidos y los que ya tenían al destino. Un supervisor transfiere dentro de su equipo (él incluido); el administrador, entre cualquiera. - Un cliente puede tener varios promotores, sin titular.
- Orden: permiso (ADR 0027) → alcance → validaciones locales → identidad y
existe→ escritura.
Alternativas descartadas¶
- Transferir sólo el administrador — el supervisor ya gestiona su equipo en fuerza-ventas (metas, responsables).
- Ocultar el promotor ajeno como inexistente —
existeestá abierto a cualquier usuario autenticado: no hay nada que ocultar. - Replicar
resolver_alcanceen clientes — sus datos (promotores y supervisión) y sus reglas son de fuerza-ventas; leerlos sería SQL cruzado y copiarlos exige un bus que no existe. - Promotor titular — cambia el modelo; no se necesita para transferir.
Consecuencias¶
- Estas escrituras suman una llamada a fuerza-ventas (del orden de cien
milisegundos;
SERVICIOS_TIMEOUT_SECes el peor caso) y dan 503 si no responde. - Sólo el administrador mueve la cartera de un promotor borrado: los borrados no están en el alcance de un supervisor.
- Clientes sin asignación y prospectos sin promotor existentes hay que asignarlos antes de desplegar (ver ADR 0029).
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.