0063. Referencia de una sucursal para que otro servicio copie su nombre¶
Estado: Aceptado (2026-11-10) Fecha: 2026-11-10 Autor: David Garcia Módulo(s) afectado(s): app/domains/sucursales/ (router, schemas), tests/, docs/adr/ Complementa a: ADR 0051 (validar un id desde otro servicio), ADR 0046 (RLS)
Contexto¶
crm-svc-clientes va a guardar qué sucursales atienden a un cliente (rel_clientes_sucursal, su ADR 0044):
sólo el sucursal_id, sin FK entre bases. Al asignar necesita rechazar un id que no existe y copiar el
nombre de la sucursal a su historial, para que un cambio de nombre posterior no reescriba lo ya registrado.
El tenant sólo tiene GET /api/v1/sucursales, que devuelve la lista entera de la empresa: buscar un id en
ella cuesta más cuantas más sucursales haya. El detalle por id es del panel (root, ADR 0057). Un existe
(true/false) valida pero no da el nombre.
Decisión¶
GET /api/v1/sucursales/referencia/{sucursal_id}devuelveid,is_activo,codigoynombre. No es la ficha: sólo lo que se copia y lo que hace falta para validar.- 404 si la sucursal no existe, está borrada (
deleted_at) o es de otra empresa. - La desactivada sin borrar se devuelve con
is_activo: false: quien consulta decide si la usa. - La empresa sale del token y va explícita en el SQL, además de la RLS del pool del tenant: con un rol que salta la RLS (el de la base local es superusuario) se vería la de otra empresa.
- En el router del tenant, con JWT normal: el servicio que consulta reenvía el token del usuario. El token administrativo no vale (401), como en el listado.
- Reutiliza
SucursalService.obtener_sucursal: sólo se agregan la ruta, su schema y las pruebas.
Alternativas descartadas¶
GET /sucursales/existe/{id}(como ciudades y entidades) — no da el nombre: el consumidor tendría que pedir además la lista, o su frontend resolverlo al mostrar el historial.- Que el consumidor use
GET /sucursales— trae todas las sucursales para leer una. - Abrir la ficha
GET /sucursales/{id}al tenant — ata al consumidor a campos que no usa. - Devolver también las borradas — nadie debe asignar una sucursal borrada; el nombre ya copiado no la necesita.
Consecuencias¶
- OpenAPI suma un endpoint de lectura. Nada existente cambia.
- Cualquier usuario con token lee código y nombre de una sucursal de su empresa: lo mismo que ya da el listado.
- El nombre copiado por el consumidor es el de ese momento; si la sucursal cambia de nombre, la copia no.
- Hoy ninguna ruta desactiva una sucursal sin borrarla (borrar pone
is_activo = falseydeleted_at);is_activose devuelve para cuando exista y para datos cargados por fuera. - Pruebas unitarias (router con service falso): los cuatro campos,
is_activo: false, 404 para la inexistente, la borrada y la de otra empresa, 422, 401 sin token y con token administrativo, y que la ruta use el pool del tenant con la empresa del token. El SQL no tiene prueba de integración.