Saltar a contenido

0012. Cartera propia de sólo lectura, buscada en el teléfono

Estado: Propuesto Fecha: 2026-11-03 Autor: David Garcia Módulo(s) afectado(s): modules/cartera/

Contexto

La pestaña Clientes (ADR 0010) es la cartera del promotor y el punto de partida de un pedido fuera de una visita (ADR 0013). En crm-svc-clientes la cartera son las asignaciones activas de rel_clientes_promotores (ADR 0028 de clientes), y cada listado ya viene filtrado por el alcance del usuario: un promotor ve su cartera y un supervisor la de su equipo (ADR 0029 de clientes). GET /clientes no pagina y devuelve también los inactivos y los borrados; ?promotor_id= lo acota a la cartera de un promotor (ADR 0040 de clientes). Un cliente desactivado o borrado tiene is_activo = false; deleted_at distingue el borrado (ADR 0036 de clientes). Locales y vínculos con contactos se piden por ?cliente_id=. Cada operación exige su permiso clientes.clientes.* (ADR 0027 de clientes).

Decisión

  • La cartera es la del promotor de la sesión, como la agenda (ADR 0011): GET /clientes?promotor_id=<propio>, y de ahí sólo los activos. Un supervisor no ve la de su equipo, y un cliente desactivado o borrado no aparece.
  • La búsqueda es en el teléfono, sobre la lista ya cargada: nombre comercial, razón social, código y número de documento, sin distinguir mayúsculas ni tildes. Se ordena por nombre.
  • El cliente se nombra como en la visita (ADR 0011): nombre comercial o, sin él, razón social.
  • Ficha por id (/clientes/:id, ADR 0010): datos comerciales, locales activos con su dirección y contactos activos con cargo, teléfono y WhatsApp. Un 404 dice que el cliente ya no está en la cartera (lo transfirieron o lo borraron en la web).
  • Sólo lectura: crear y editar clientes, locales y contactos es de la web.
  • Un 403 se muestra tal cual: al rol le falta el permiso en identidad.

Alternativas descartadas

  • GET /clientes sin filtro, cruzado con GET /clientes-promotores — dos peticiones, y para un supervisor descarga la cartera de todo su equipo para descartarla en el teléfono.
  • Un GET /clientes/{id} por asignación — una petición por cliente, y cada una consulta el alcance en fuerza de ventas.
  • Búsqueda y paginación en el servidor (GET /clientes/listado y GET /clientes/buscar, ADR 0041 y 0038 de clientes) — piden red en cada búsqueda, cuando la app se prepara para trabajar sin conexión (ADR 0004); vuelve si la cartera crece hasta que la lista completa pese.

Consecuencias

  • Abrir la pestaña trae toda la cartera del promotor; con cientos de clientes es aceptable, con miles habrá que pasar a GET /clientes/listado.
  • La ficha pide un contacto a la vez (GET /contactos-cliente/{id}) para tener sus teléfonos: los vínculos sólo traen el nombre.
  • Llamar o abrir WhatsApp desde la ficha queda para cuando se decida la dependencia; por ahora el número se puede copiar.
  • Si clientes o fuerza de ventas no responden, no hay cartera (503, ADR 0029 de clientes).

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.