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-usuariolista los activos ordenados pornombre;GET /tipos-usuario/{tipo_usuario_id}devuelve uno por UUID.POST /tipos-usuariocrea un rol concodigoúnico: si el código ya existe entre los activos responde409«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 responde404«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 a409/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
UniqueConstraintde 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): sutipo_usuario_idya 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
usuariossuman una clase por capa (TiposUsuarioRepository,TiposUsuarioService);TipoUsuarioNoEncontradoErrorqueda disponible para que el slice de usuarios la reutilice.