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 lascfg_menu_accionesactivas concedidas al usuario en esa empresa. ElJOINvive en el repository, que cruzarel_usuario_accionconcfg_menu_accionesdel dominio navegación —sólo lectura, comoexiste_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/permisosconcede una acción con body{"empresa_id": int, "usuario_id": uuid|null, "tipo_usuario_id": uuid|null, "accion_id": uuid}→201conRelUsuarioAccionRead. 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,PermisoNoEncontradoErroryConcesionDuplicadaError; se reutilizanUsuarioNoEncontradoError,TipoUsuarioNoEncontradoErroryEmpresaNoEncontradaError. RelUsuarioAccionCreatetipa el body yRelUsuarioAccionRead(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}/accionespara 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/usuariosy/api/v1/tipos-usuario, y concesión/revocación bajo/api/v1/permisos. UsuariosRepository,UsuariosServiceyusuarios_routersuman métodos;router.pyagregapermisos_routerymain.pylo monta;schemas.pyagregaRelUsuarioAccionCreate.- 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.