Saltar a contenido

0026. CRUD de catálogo de tipos de usuario

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

Contexto

cat_tipos_usuario es el catálogo global de roles de la plataforma (usuario, root, externo), vigente como catálogo de roles desde el ADR 0023: los roles crecen agregando filas, no tablas. Es global: no lleva empresa_id ni RLS (ADR 0012 transversal). La tabla ya existe (ADR 0004) y el dominio usuarios ya tiene sus archivos creados por el slice de entidades (ADR 0025); este ADR entrega el CRUD del catálogo de roles.

Decisión

Se implementa el CRUD de cat_tipos_usuario bajo /api/v1/tipos-usuario, con el patrón del servicio (router -> service -> repository, ADR 0001 transversal):

  • GET /tipos-usuario lista los activos ordenados por nombre; GET /tipos-usuario/{tipo_usuario_id} devuelve uno por UUID.
  • POST /tipos-usuario crea un rol con codigo único: si el código ya existe entre los activos responde 409 «Ya existe un tipo de usuario con ese código».
  • PUT /tipos-usuario/{tipo_usuario_id} actualiza parcialmente, con la misma validación de código duplicado; el rol inexistente o inactivo responde 404 «Tipo de usuario no encontrado».
  • DELETE /tipos-usuario/{tipo_usuario_id} es borrado lógico (deleted_at + is_activo = False), 204.
  • Las reglas viven en el service (CodigoDuplicadoError, TipoUsuarioNoEncontradoError) y el router las traduce a 409/404.

Alternativas descartadas

  • Un CRUD por rol o una tabla por rol — el ADR 0023 unificó la autorización en acciones: los roles se mantienen como filas de cat_tipos_usuario, nunca como tablas nuevas.
  • Validar el código duplicado con el UniqueConstraint de la base — el constraint no distingue borrados lógicos: un rol eliminado seguiría bloqueando su código. La unicidad se valida en el service sobre los activos (deleted_at IS NULL), como en los demás catálogos del servicio.

Consecuencias

  • Desbloquea el CRUD de usuarios (mae_usuarios): su tipo_usuario_id ya puede apuntar a roles reales (ADR 0027).
  • OpenAPI del servicio suma 5 endpoints bajo /api/v1/tipos-usuario.
  • El repository y el service del dominio usuarios suman una clase por capa (TiposUsuarioRepository, TiposUsuarioService); TipoUsuarioNoEncontradoError queda disponible para que el slice de usuarios la reutilice.