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-contactoscon filtros?cliente_id=y?contacto_id=; estrena el tagclientes-relaciones(sub-routerrelaciones, 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
POSTreactiva 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) ycontacto(nombre) con relacionesviewonly+joinedload. Como entre el vínculo ymae_clienteshay dos FK (la del vínculo y la circular), la relaciónclientedeclaraforeign_keys. - Contacto principal: se elige en el
PUTdel 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¶
clientesexpone 25 operaciones (20 maestras y 5 de relaciones).- Como el
PUTdel cliente reemplaza la ficha, si no se envíacontacto_principal_idel principal queda enNULL. - 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.