Saltar a contenido

0020. Dominio clientes — cuarto slice: locales del cliente

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

Contexto

mae_locales_cliente guarda los puntos de atención o entrega de un cliente (varios por cliente): código, nombre, dirección, ciudad y coordenadas. El código es único dentro del cliente. ciudad_id es un UUID de svc-identidad. Las coordenadas son numeric(9,6), en rango y las dos o ninguna (CHECK). El trigger trg_validar_cliente_de_local impide crear, reasignar o reactivar un local de un cliente inactivo o borrado.

Decisión

  • Rutas planas /api/v1/locales-cliente (tag clientes-maestras) con filtro ?cliente_id=, como los tipos de canal (ADR 0015).
  • Al crear, el service valida que el cliente exista (404) y esté activo (409) antes del trigger, que queda como red de seguridad; el código se valida contra los locales de ese cliente (409, aunque esté borrado).
  • cliente_id y codigo no se editan: el PUT no los acepta (422).
  • Coordenadas validadas en el contrato: rango, hasta 6 decimales y «las dos o ninguna», con un mensaje legible. Se reciben como Decimal (exactas) y salen como número.
  • ciudad_id se acepta sin validar hasta integrar svc-identidad (ADR 0017).
  • Borrar un cliente no toca sus locales: quedan como historial (docs-sql).
  • La respuesta trae cliente (razón social) junto a cliente_id, con la relación LocalCliente.cliente y joinedload, como las referencias del cliente (ADR 0019).

Alternativas descartadas

  • Rutas anidadas (/clientes/{id}/locales) — rompen la forma plana del dominio (ADR 0017).
  • Mover un local a otro cliente por PUT — las visitas (trx_visitas) dependerán del dueño del local; se crea un local nuevo.
  • Dejar que el trigger o el CHECK respondan — darían un 500 en lugar de un 404/409/422 claro.
  • Impedir borrar un cliente con locales activos — docs-sql los conserva como historial.

Consecuencias

  • clientes expone 20 operaciones.
  • Reactivar un local o un cliente no tiene endpoint todavía.
  • Pendiente: el nombre de la ciudad. Cuando exista identidad se decidirá cómo validar ciudad_id y mostrar su nombre: con una copia local de ciudades (sincronizada por eventos) sería una relación más en _REFERENCIAS_LOCAL; con una consulta a identidad, se resolvería fuera del JOIN.

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.