Saltar a contenido

0021. Dominio clientes — quinto slice: relación cliente–contactos

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

Contexto

rel_clientes_contactos vincula contactos (mae_contactos_cliente) con clientes; el cargo es propio de cada vínculo. El par cliente–contacto es único aun borrado: docs-sql pide reactivar la misma fila en lugar de crear otra. mae_clientes.contacto_principal_id tiene una FK circular compuesta hacia este vínculo (empresa_id, cliente_id, contacto_id): el principal debe estar vinculado a ese cliente. La FK no detecta si el vínculo está borrado.

Decisión

  • Rutas planas /api/v1/clientes-contactos con filtros ?cliente_id= y ?contacto_id=; estrena el tag clientes-relaciones (sub-router relaciones, ADR 0017).
  • Al vincular, cliente y contacto deben existir (404) y estar activos (409). Si el par ya está activo → 409; si estaba borrado, el mismo POST reactiva la misma fila con el cargo nuevo.
  • Sólo se edita cargo_en_cliente; cliente y contacto no cambian (422).
  • La respuesta trae cliente (razón social) y contacto (nombre) con relaciones viewonly + joinedload. Como entre el vínculo y mae_clientes hay dos FK (la del vínculo y la circular), la relación cliente declara foreign_keys.
  • Contacto principal: se elige en el PUT del cliente (contacto_principal_id); el service exige un vínculo existente (404) y activo (409). Al crear el cliente no se envía.
  • El vínculo del contacto principal no se borra (409: «quítalo primero»), y un contacto con vínculos activos tampoco (409, amplía el ADR 0018).

Alternativas descartadas

  • 409 al re-vincular un par borrado — obligaría a un endpoint de reactivación; docs-sql pide reutilizar la fila.
  • Endpoint propio PUT /clientes/{id}/contacto-principal — más explícito, pero suma una ruta especial; el principal es un campo más de la ficha.
  • Borrar el vínculo principal y dejar el principal en NULL — cambia el cliente en silencio desde otro recurso.

Consecuencias

  • clientes expone 25 operaciones (20 maestras y 5 de relaciones).
  • Como el PUT del cliente reemplaza la ficha, si no se envía contacto_principal_id el principal queda en NULL.
  • El nombre del contacto principal en la respuesta del cliente queda para un paso aparte.

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.