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.
desdees elcreated_atde la asignación yhasta, el del eventoborradoque la quitó (entidad_tipo = 'cliente_promotor'). Los dos son elnow()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
clientese 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/auditoriasinreferencia_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
Visibilidadcambia. El dominio ya no devuelve sólo ids visibles. Devuelve también una consulta de periodos(referencia_id, desde, hasta), yconsulta_de_eventosyconsulta_de_actoressumanOR EXISTS (periodo de ese referencia_id con created_at BETWEEN desde AND hasta). El router desharedsigue 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,
EventoResponsesuma dos campos: referencia_descripcion:codigo · razón socialdel cliente, el actual. El dominio lo llena en todos los eventos decliente(una lectura demae_clientespor los ids de la página), así el nombre no depende de qué clientes tenga cargados el frontend;en_cartera:falsecuando el evento se ve sólo por un periodo. Conen_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 cambiapromotor_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
EXISTSsobrerel_clientes_promotoresunido aaud_eventospara 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 losborradodecliente_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:
TrazabilidadClientestoma el nombre dereferencia_descripcionen 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.