Saltar a contenido

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_id es 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), tampoco root (ADR 0027). Vale igual para el administrador y el supervisor. El cliente nace con su asignación en la misma transacción; el promotor_id del prospecto deja de ser opcional: en el PUT (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_ids opcional, 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. Un cliente_ids que 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 — existe está abierto a cualquier usuario autenticado: no hay nada que ocultar.
  • Replicar resolver_alcance en 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_SEC es 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.