Saltar a contenido

0029. CRUD de permisos por acción (rel_usuario_accion)

Estado: Aceptado Fecha: 2026-09-30 Autor: Duval Alcivar Módulo(s) afectado(s): app/domains/usuarios/, app/main.py, tests/unit/usuarios/, docs/adr/

Contexto

El ADR 0023 transversal unificó la autorización del servicio en una única tabla: rel_usuario_accion (la tabla ya existe, ADR 0004), reemplazando a rel_usuario_permiso, rel_usuario_menu y rel_usuario_menu_accion. La concesión es a nivel de acción —cfg_menu_acciones, la unidad de permiso del ADR 0023— y el sujeto es polimórfico y excluyente: cada fila lleva usuario_id o tipo_usuario_id, nunca ambos (lo impone el CHECK num_nonnulls(...) = 1). El login JWT necesita este slice para emitir el token con las acciones del usuario y de su rol.

Decisión

Se implementa el CRUD de permisos reutilizando UsuariosRepository y UsuariosService del slice de usuarios (ADR 0027), con el patrón del servicio (router -> service -> repository, ADR 0001 transversal), y un router nuevo permisos_router para la concesión y la revocación:

  • GET /api/v1/usuarios/{usuario_id}/acciones?empresa_id={int} lista las cfg_menu_acciones activas concedidas al usuario en esa empresa. El JOIN vive en el repository, que cruza rel_usuario_accion con cfg_menu_acciones del dominio navegación —sólo lectura, como existe_empresa—. Usuario inexistente o inactivo → 404 «Usuario no encontrado».
  • GET /api/v1/tipos-usuario/{tipo_usuario_id}/acciones?empresa_id={int} igual para un rol, bajo el prefijo existente del catálogo de roles. Rol inexistente o inactivo → 404 «Tipo de usuario no encontrado».
  • POST /api/v1/permisos concede una acción con body {"empresa_id": int, "usuario_id": uuid|null, "tipo_usuario_id": uuid|null, "accion_id": uuid} → 201 con RelUsuarioAccionRead. Validaciones en orden: sujeto excluyente (ninguno o ambos → 422 «Debe indicar usuario o rol» / «Debe indicar usuario o rol, no ambos»), referencias activas (usuario o rol → 404, empresa → 404, acción → 404) y concesión activa duplicada → 409 «El usuario ya tiene esa acción» / «El rol ya tiene esa acción» según el sujeto.
  • DELETE /api/v1/permisos/{permiso_id} revoca con borrado lógico (deleted_at + is_activo = False) → 204. Permiso inexistente o ya inactivo → 404 «Permiso no encontrado».
  • Nuevas excepciones del service siguiendo el patrón de nombres del dominio: SujetoInvalidoError, AccionNoEncontradaError, PermisoNoEncontradoError y ConcesionDuplicadaError; se reutilizan UsuarioNoEncontradoError, TipoUsuarioNoEncontradoError y EmpresaNoEncontradaError.
  • RelUsuarioAccionCreate tipa el body y RelUsuarioAccionRead (ya existente) proyecta la concesión creada. La exclusividad del sujeto la valida el service, no Pydantic, como el resto de las reglas del dominio.

Alternativas descartadas

  • Conceder por página (rel_usuario_menu_accion) — el ADR 0023 transversal unificó la autorización a nivel de acción; volver a la página reintroduce la tabla que este slice reemplaza.
  • Router, service y repository propios — el slice comparte validaciones y repository con el dominio usuarios, igual que el de empresas del usuario (ADR 0028); tres clases más por capa duplican la armada de dependencias.
  • GET /api/v1/roles/{tipo_usuario_id}/acciones para el listado del rol — el catálogo ya vive bajo /api/v1/tipos-usuario; un segundo prefijo fragmentaría el recurso en OpenAPI. Se conserva la semántica («las acciones del rol») bajo el prefijo existente.

Consecuencias

  • Desbloquea el login JWT: el token podrá llevar las acciones del usuario más las de su rol, la materia prima del permiso efectivo.
  • OpenAPI del servicio suma 4 endpoints: 2 listados bajo /api/v1/usuarios y /api/v1/tipos-usuario, y concesión/revocación bajo /api/v1/permisos.
  • UsuariosRepository, UsuariosService y usuarios_router suman métodos; router.py agrega permisos_router y main.py lo monta; schemas.py agrega RelUsuarioAccionCreate.
  • El borrado lógico deja volver a conceder una acción revocada: los índices únicos parciales (deleted_at IS NULL) no bloquean la re-concesión.