Saltar a contenido

0023. Dominio clientes — séptimo slice: relación cliente–promotores

Estado: Propuesto Fecha: 2026-10-01 Autor: Kevin Delgado Lopez Módulo(s) afectado(s): app/domains/clientes/, tests/unit/clientes/

Contexto

rel_clientes_promotores asigna promotores a un cliente; un cliente puede tener varios a la vez y no hay titular. Sólo tiene cliente_id y promotor_id, que es un UUID de svc-fuerza-ventas (aún no existe), sin FK. docs-sql no declara UNIQUE (cliente, promotor) y pide conservar las asignaciones (sin cascada). El control de qué clientes ve cada promotor es de la autorización, no de esta tabla.

Decisión

  • Rutas planas /api/v1/clientes-promotores (tag clientes-relaciones) con filtros ?cliente_id= y ?promotor_id=, ordenadas por fecha.
  • Sin PUT: la asignación no tiene nada editable. Son 4 endpoints: listar, obtener, asignar y quitar. Para cambiar de promotor se quita y se asigna otro.
  • Al asignar, el cliente debe existir (404) y estar activo (409); promotor_id se acepta sin validar hasta integrar fuerza de ventas (ADR 0017).
  • El mismo par con una asignación activa → 409. Si estaba quitada, el POST crea una fila nueva: queda el historial de asignaciones (a diferencia del ADR 0021, donde la base obliga a reutilizar la fila).
  • Respuesta con cliente (razón social); el nombre del promotor queda pendiente de fuerza de ventas.
  • Borrar un cliente conserva sus asignaciones.

Alternativas descartadas

  • Reactivar la misma fila — se perdería cuándo se quitó y se volvió a asignar; la base no lo exige.
  • PUT para cambiar el promotor — reescribiría la historia de la asignación.

Consecuencias

  • clientes expone 34 operaciones (20 maestras, 5 transaccionales, 9 de relaciones).
  • Al integrar fuerza de ventas: validar que el promotor exista y esté activo, mostrar su nombre y aplicar el acceso por promotor en la autorización.

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.