Saltar a contenido

0034. Historial del cliente que salió de la cartera

Estado: Aceptado Fecha: 2026-10-29 Autor: David Garcia Módulo(s) afectado(s): app/domains/clientes/, app/shared/auditoria/, tests/unit/

Contexto

El historial de cliente se filtra por la cartera de hoy (ADR 0029 y 0030). Si un supervisor transfiere un cliente de RCHIQUITO a otro promotor, el cliente sale de la cartera de RCHIQUITO y con él todo su historial: no ve la transferencia ni lo que él mismo hizo mientras el cliente fue suyo. En la trazabilidad de la pantalla, los eventos desaparecen. Por id, la respuesta es 404. Negocio quiere que quien tuvo un cliente conserve lo que pasó mientras lo tuvo, incluida su salida. No debe ver lo de antes ni lo de después: si a GRIVAS le asignan un cliente por error y se lo quitan enseguida, no debe quedarse con toda la historia del cliente.

Decisión

  • Periodo en cartera: va de que se asignó el cliente a un promotor que hoy está en el alcance del usuario hasta que se le quitó. Hay uno por asignación quitada; si al promotor se le asignó el cliente dos veces, hay dos periodos.
  • desde es el created_at de la asignación y hasta, el del evento borrado que la quitó (entidad_tipo = 'cliente_promotor'). Los dos son el now() de su transacción, con el reloj de la base. Así entra todo lo que hicieron esas dos transacciones: en una transferencia, de quién vino el cliente y a quién pasó.
  • No se usa deleted_at: lo pone la aplicación con su reloj, y con un desfase el evento de la quita podría quedar fuera.
  • Un evento de cliente se ve si se cumple una de estas condiciones:
  • el cliente está hoy en la cartera del usuario (todo su historial, como hasta ahora);
  • el evento cae dentro de alguno de sus periodos, extremos incluidos.
  • Vale para las dos lecturas:
  • GET /api/v1/auditoria sin referencia_id: entran los clientes de la cartera y los que salieron, cada uno con sus periodos;
  • con referencia_id: ya no responde 404 si hay algún periodo, y devuelve los eventos de esos periodos;
  • /actores (ADR 0032) aplica el mismo filtro.
  • La ficha no cambia: GET /clientes/{id} sigue siendo 404 para quien ya no tiene el cliente. Sólo se conserva el historial de su periodo.
  • El contrato de Visibilidad cambia. El dominio ya no devuelve sólo ids visibles. Devuelve también una consulta de periodos (referencia_id, desde, hasta), y consulta_de_eventos y consulta_de_actores suman OR EXISTS (periodo de ese referencia_id con created_at BETWEEN desde AND hasta). El router de shared sigue sin conocer el dominio (ADR 0002).
  • Quien perdió el cliente sabe cuál fue. Hoy el frontend nombra cada evento con la lista de clientes visibles. Si a un promotor le quitan varios clientes, vería varios grupos de eventos rotulados "Cliente no disponible", sin saber de quién son. Por eso, EventoResponse suma dos campos:
  • referencia_descripcion: codigo · razón social del cliente, el actual. El dominio lo llena en todos los eventos de cliente (una lectura de mae_clientes por los ids de la página), así el nombre no depende de qué clientes tenga cargados el frontend;
  • en_cartera: false cuando el evento se ve sólo por un periodo. Con en_cartera = false, el frontend muestra el nombre sin enlace a la ficha (que sería 404) y lo marca como "Salió de su cartera".
  • Fuera de alcance:
  • prospecto, que pierde su historial igual cuando cambia promotor_id;
  • contacto, que se ve por sus vínculos con clientes. Si hace falta, cada uno tendrá su ADR.

Alternativas descartadas

  • Todo el historial hasta la salida: una asignación por error, aunque dure segundos, le deja ver toda la historia anterior del cliente.
  • Nada al salir (lo de ADR 0030): el promotor no ve ni la transferencia ni lo que él mismo hizo.
  • Periodos también para el dueño actual: dejaría de ver la historia anterior a su asignación, que necesita para atender al cliente.
  • Copiar el historial al promotor al transferir: duplica eventos que sólo se insertan, y no resuelve las quitas hechas antes.

Consecuencias

  • La consulta del historial suma un EXISTS sobre rel_clientes_promotores unido a aud_eventos para los periodos. Se apoya en el índice (empresa_id, referencia_tipo, referencia_id, id) de ADR 0030. Si pesa, se puede sumar un índice parcial para los borrado de cliente_promotor.
  • Las quitas anteriores al despliegue de la auditoría no tienen evento y no dan periodo. Tampoco hay eventos de ese periodo que mostrar.
  • No se pierde historial: los eventos nunca se borran. El dueño actual, su supervisor y el administrador siguen viendo el historial completo. Si el promotor se va de la empresa, sus clientes se le transfieren a otro promotor, que hereda el historial completo.
  • Un supervisor que tiene en su alcance al promotor que perdió el cliente ve los mismos periodos.
  • Quien perdió el cliente ve de quién lo recibió y a quién pasó. Ese promotor se nombra por su entidad, como en ADR 0030.
  • Quien perdió el cliente sigue viendo su código y razón social actuales, aunque los cambien después de la salida. El resto de la ficha no lo ve.
  • Frontend: TrazabilidadClientes toma el nombre de referencia_descripcion en lugar de la lista de clientes. Usa la lista sólo para decidir si enlaza la ficha (en_cartera).
  • El contrato suma dos campos a la respuesta: los clientes actuales no cambian.

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.