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(tagclientes-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_idycodigono se editan: elPUTno 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_idse 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 acliente_id, con la relaciónLocalCliente.clienteyjoinedload, 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¶
clientesexpone 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_idy 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.