Saltar a contenido

0028. CRUD de empresas del usuario (rel_usuario_empresa)

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 0010 transversal define que rel_usuario_empresa es el acceso: la lista de empresas que el usuario puede elegir al iniciar sesión. El usuario es global (no lleva empresa_id ni RLS, ADR 0012 transversal) y sus empresas se declaran en esta relación, que no lleva RLS porque el aislamiento se resuelve vía la relación misma. La tabla ya existe (ADR 0004) con usuario_id y empresa_id (BIGINT, FK a mae_empresas) y un UNIQUE(usuario_id, empresa_id); el login JWT necesita este slice para emitir el token con la empresa elegida.

Decisión

Se implementa el CRUD de las empresas del usuario bajo /api/v1/usuarios/{usuario_id}/empresas, con el patrón del servicio (router -> service -> repository, ADR 0001 transversal), reutilizando UsuariosRepository, UsuariosService y usuarios_router del slice de usuarios (ADR 0027):

  • GET .../empresas lista las mae_empresas activas asignadas, ordenadas por razón social (el "nombre" de una empresa en este servicio). Usuario inexistente o inactivo → 404 «Usuario no encontrado». El JOIN vive en el repository, que cruza rel_usuario_empresa con mae_empresas del dominio empresas (sólo lectura, como NavegacionRepository.existe_empresa).
  • POST .../empresas asigna una empresa con body {"empresa_id": int} → 201 con la relación creada. Validaciones en orden: usuario inexistente o inactivo → 404 «Usuario no encontrado»; empresa inexistente o inactiva → 404 «Empresa no encontrada»; relación activa ya existente → 409 «El usuario ya tiene asignada esa empresa».
  • DELETE .../empresas/{empresa_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 empresa».
  • El contrato de lectura de empresas reutiliza MaeEmpresasRead del dominio empresas (no se duplica); la relación creada se proyecta con el RelUsuarioEmpresaRead ya existente. RelUsuarioEmpresaCreate tipa el body.
  • Nuevas excepciones del service siguiendo el patrón de nombres del dominio: EmpresaNoEncontradaError, RelacionDuplicadaError y RelacionNoEncontradaError.

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.
  • Validar la empresa con el CRUD de mae_empresas — el repository del dominio usuarios lee mae_empresas directamente (patrón ya usado por navegación); el service no necesita otro service ni conocer su API.
  • 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

  • Desbloquea el login JWT con selección de empresa: el token llevará la empresa elegida por el usuario entre las devueltas por el GET.
  • OpenAPI del servicio suma 3 endpoints bajo /api/v1/usuarios.
  • UsuariosRepository, UsuariosService y usuarios_router suman métodos; schemas.py agrega RelUsuarioEmpresaCreate y MaeEmpresasRead del dominio empresas queda como contrato de lectura compartido.