0032. CRUD de sucursales del usuario (rel_usuario_sucursal)¶
Estado: Aceptado Fecha: 2026-09-30 Autor: Duval Alcivar Módulo(s) afectado(s): app/domains/usuarios/, tests/unit/usuarios/, docs/adr/
Contexto¶
El ADR 0019 implementó el CRUD de mae_sucursales y dejó dicho que
desbloqueaba a rel_usuario_sucursal: la tabla que da a un usuario acceso a
las sucursales de sus empresas. Esa tabla ya existe, migrada desde el ADR 0004,
con usuario_id y sucursal_id (UUID, FK a mae_sucursales) y un
UNIQUE(usuario_id, sucursal_id); lo que falta es la API para administrar la
relación, exactamente el mismo hueco que cerró el ADR 0028 para las empresas.
Decisión¶
Se implementa el CRUD de las sucursales del usuario bajo
/api/v1/usuarios/{usuario_id}/sucursales, replicando el patrón del slice de
empresas del usuario (ADR 0028): router -> service -> repository (ADR 0001
transversal), reutilizando UsuariosRepository, UsuariosService y
usuarios_router del slice de usuarios (ADR 0027):
GET .../sucursaleslista lasmae_sucursalesactivas asignadas, ordenadas por nombre. Usuario inexistente o inactivo →404«Usuario no encontrado». ElJOINvive en el repository, que cruzarel_usuario_sucursalconmae_sucursalesdel dominio sucursales (sólo lectura, como el slice de empresas).POST .../sucursalesasigna una sucursal con body{"sucursal_id": uuid}→201con la relación creada. Validaciones en orden: usuario inexistente o inactivo →404«Usuario no encontrado»; sucursal inexistente o inactiva →404«Sucursal no encontrada»; relación activa ya existente →409«El usuario ya tiene asignada esa sucursal».DELETE .../sucursales/{sucursal_id}desasigna con borrado lógico (deleted_at+is_activo = False) →204. Usuario inexistente →404; relación inexistente o ya inactiva →404«El usuario no tiene asignada esa sucursal».- El contrato de lectura de sucursales reutiliza
MaeSucursalesReaddel dominio sucursales (no se duplica); la relación creada se proyecta con elRelUsuarioSucursalReadya existente.RelUsuarioSucursalCreatetipa el body. - Nuevas excepciones del service siguiendo el patrón de nombres del dominio:
SucursalNoEncontradaError,RelacionSucursalDuplicadaErroryRelacionSucursalNoEncontradaError.
El sujeto es el usuario, no la sucursal, por simetría con
rel_usuario_empresa (ADR 0028): la relación cuelga de /usuarios/{id} como
un sub-recurso y el usuario sigue siendo la identidad que atraviesa el servicio
(ADR 0027). Una ruta inversa (/sucursales/{id}/usuarios) rompería esa
simetría sin aportar casos de uso: el consumidor conoce al usuario y pide sus
sucursales.
Alternativas descartadas¶
- Router, service y repository propios para la relación — el slice es un sub-recurso del usuario y comparte validaciones y repository con el CRUD de usuarios; tres clases más por capa no aportan aislamiento y sí duplican la armada de dependencias (misma razón que en el ADR 0028).
- Colgar las rutas de
/sucursales— invertiría el sujeto: el CRUD de sucursales (ADR 0019) ya administra la tabla maestra y la relación es del usuario; además duplicaría las validaciones de usuario en otro router. - Desasignar borrando la fila — rompería el calendario de auditoría del
AuditMixiny el patrón de borrado lógico de todos los slices del servicio.
Consecuencias¶
- Limitación conocida:
UNIQUE(usuario_id, sucursal_id)es un constraint plano, sin predicadodeleted_at IS NULL. Tras desasignar una sucursal (borrado lógico), la fila inactiva sigue ocupando el par en el UNIQUE, así que reasignarla reventaría conIntegrityErroren la base. Es la misma limitación que arrastrarel_usuario_empresa(ADR 0028) y queda para un slice futuro: una migración que reemplace el constraint por un índice único parcial condeleted_at IS NULL, como ya hacerel_usuario_accion(ADR 0029). - OpenAPI del servicio suma 3 endpoints bajo
/api/v1/usuarios. UsuariosRepository,UsuariosServiceyusuarios_routersuman métodos;schemas.pyagregaRelUsuarioSucursalCreateyMaeSucursalesReaddel dominio sucursales queda como contrato de lectura compartido.