Saltar a contenido

0035. Referencias para que otro servicio copie el nombre al registrar

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

Contexto

Fuerza-ventas guarda sólo el id del cliente, del local o del prospecto en sus visitas, requerimientos y pedidos, y el frontend los nombra con la lista de clientes visibles. Esa lista se filtra por la cartera de hoy (ADR 0029). Si un supervisor transfiere un cliente de RCHIQUITO a otro promotor, RCHIQUITO sigue viendo sus visitas y pedidos, pero el cliente aparece como "fuera de tu cartera". Negocio decidió que esos registros muestren el nombre que tenía el cliente cuando se hicieron. Fuerza-ventas lo copiará al registrar, y para eso necesita leer el nombre. Hoy sólo puede preguntar si existe (existe, un booleano), y la ficha pide permisos de clientes y se filtra por la cartera.

Decisión

  • Tres lecturas nuevas, con el mismo acceso que los existe: sólo piden token (SIN_PERMISO) y no se filtran por la cartera.
  • GET /api/v1/clientes/referencia/{cliente_id}: id, is_activo, codigo, razon_social y nombre_comercial.
  • GET /api/v1/locales-cliente/referencia/{cliente_id}/{local_id}: id, is_activo, cliente_id, codigo y nombre.
  • GET /api/v1/prospectos/referencia/{prospecto_id}: id, is_activo, nombre y cliente_id (el cliente en que se convirtió).
  • También de un borrado: is_activo dice si se puede usar, y quien consulta decide qué hacer. 404 sólo si no existe, es de otra empresa (RLS) o el local es de otro cliente. La actividad del cliente de un local la dice la referencia del cliente.
  • Sin los campos de auditoría: no es la ficha. Sólo lo que se copia y lo que hace falta para validar.
  • Los existe se mantienen. Fuerza-ventas los reemplaza por las referencias en su propio cambio.

Alternativas descartadas

  • Una lista de nombres por ids para el frontend, sin cartera: cualquiera con token leería el nombre de cualquier cliente. Contradice el ADR 0029.
  • Que fuerza-ventas pida los nombres al listar: cada agenda y cada lista de pedidos dependería de clientes. Si clientes cae, fuerza-ventas no puede mostrar sus propios registros.
  • Ampliar los existe con el nombre: cambia un contrato que responde true/false y que hoy usan otros.
  • Leer la ficha (GET /clientes/{id}): pide permisos de clientes que el promotor puede no tener, y se filtra por la cartera.

Consecuencias

  • Quien tiene token y el id de un cliente puede leer su código y su nombre, aunque no sea de su cartera. Es el mismo riesgo que ya aceptan los existe (los ids son UUID v7, no se adivinan). Se cierra cuando exista una credencial de servicio.
  • El nombre copiado es el de ese momento. Si la razón social cambia después, la copia de fuerza-ventas no se actualiza. El código no se puede editar.
  • Fuerza-ventas pasa a leer el nombre del prospecto de aquí, y no de su ficha.

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.