Saltar a contenido

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} devuelve id, is_activo, codigo y nombre. 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 = false y deleted_at); is_activo se 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.