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 /clientessin filtro, cruzado conGET /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/listadoyGET /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.