Saltar a contenido

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 .../sucursales lista las mae_sucursales activas asignadas, ordenadas por nombre. Usuario inexistente o inactivo → 404 «Usuario no encontrado». El JOIN vive en el repository, que cruza rel_usuario_sucursal con mae_sucursales del dominio sucursales (sólo lectura, como el slice de empresas).
  • POST .../sucursales asigna una sucursal con body {"sucursal_id": uuid} → 201 con 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 MaeSucursalesRead del dominio sucursales (no se duplica); la relación creada se proyecta con el RelUsuarioSucursalRead ya existente. RelUsuarioSucursalCreate tipa el body.
  • Nuevas excepciones del service siguiendo el patrón de nombres del dominio: SucursalNoEncontradaError, RelacionSucursalDuplicadaError y RelacionSucursalNoEncontradaError.

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 AuditMixin y 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 predicado deleted_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 con IntegrityError en la base. Es la misma limitación que arrastra rel_usuario_empresa (ADR 0028) y queda para un slice futuro: una migración que reemplace el constraint por un índice único parcial con deleted_at IS NULL, como ya hace rel_usuario_accion (ADR 0029).
  • OpenAPI del servicio suma 3 endpoints bajo /api/v1/usuarios.
  • UsuariosRepository, UsuariosService y usuarios_router suman métodos; schemas.py agrega RelUsuarioSucursalCreate y MaeSucursalesRead del dominio sucursales queda como contrato de lectura compartido.