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(tagclientes-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_idse acepta sin validar hasta integrar fuerza de ventas (ADR 0017). - El mismo par con una asignación activa → 409. Si estaba quitada, el
POSTcrea 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.
PUTpara cambiar el promotor — reescribiría la historia de la asignación.
Consecuencias¶
clientesexpone 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.