Saltar a contenido

0018. Dominio clientes — segundo slice: contactos del cliente

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

Contexto

Sigue el molde del ADR 0017. mae_contactos_cliente guarda la ficha de una persona de contacto (nombre, correo, telefono, whatsapp) que después se vincula a uno o varios clientes en rel_clientes_contactos, donde va su cargo. A diferencia de las tablas anteriores no tiene codigo, y docs-sql prohíbe imponer unicidad por nombre, correo o teléfono: ninguno identifica de forma fiable a una persona.

Decisión

  • Endpoints bajo /api/v1/contactos-cliente (tag clientes-maestras), con los códigos del ADR 0008 salvo el 409: no hay conflicto posible, dos contactos pueden tener los mismos datos.
  • Todos los campos se editan por PUT (menos is_activo). El PUT reemplaza la ficha: un campo opcional que no se envía queda en NULL.
  • correo se valida con una forma mínima (algo@dominio.ext, hasta 254 caracteres) sin agregar dependencias, con un field_validator para que el 422 diga «El correo no tiene un formato válido (ejemplo: nombre@dominio.com)» en lugar de mostrar la expresión regular. telefono y whatsapp son texto libre de hasta 50.
  • El listado se ordena por nombre.

Alternativas descartadas

  • Unicidad por correo o teléfono — docs-sql la descarta: fusionaría personas distintas por coincidencia textual.
  • EmailStr de Pydantic — exige la dependencia email-validator, que no está en el stack de la plantilla (ADR 0001).
  • cargo en el contacto — varía por cliente; va en rel_clientes_contactos.

Consecuencias

  • clientes expone 10 operaciones.
  • Un contacto con vínculos activos a clientes no se borra (409); se aplicó al agregar rel_clientes_contactos (ADR 0021).

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.