Roles

Descripción

Los roles son entidades por organización que agrupan permisos y se asignan a los usuarios. Cada usuario tiene exactamente un rol; cada rol puede tener cero o más permisos. Ver 02-permisos.md para el catálogo de permisos y 07-usuarios.md para la relación usuario-rol.

Reglas fundamentales:

Los roles pertenecen a una organización; no se comparten entre organizaciones.
Dos roles en la misma organización no pueden tener el mismo nombre.
Dos organizaciones distintas pueden tener roles con el mismo nombre sin conflicto.
Un rol puede tener cero o más permisos; la relación roles-permisos es muchos a muchos.

Rol administrador (sistema)

Al crearse una organización, el sistema genera automáticamente un rol llamado "Administrador" con todos los permisos disponibles para ese tipo de organización. Este rol es especial:

Está marcado como rol de sistema (is_system = true).
No puede ser eliminado. Sí puede editarse (nombre y/o permisos): la condición de rol de sistema sólo bloquea el borrado, no la actualización.
El primer usuario de la organización (contacto principal) recibe este rol al registrarse.

ABM de roles

Un usuario con permiso ROLE:WRITE puede crear, actualizar y eliminar roles en su propia organización.

Creación

Se debe indicar el nombre del rol. Los permisos son opcionales en la creación (un rol puede crearse sin permisos asignados).

El sistema asigna automáticamente la organización del usuario que crea (desde el token).
Si ya existe un rol con ese nombre en la misma organización, se devuelve error.

Actualización

Se puede actualizar el nombre y/o el conjunto de permisos del rol.

Solo se envían los campos que se desean cambiar.
Si se envía una lista de permisos, reemplaza los permisos existentes del rol. Si se envía una lista vacía, el rol queda sin permisos.
Si no se envía el campo de permisos, los permisos actuales se mantienen.
Si el nuevo nombre ya existe en la organización (en otro rol), se devuelve error.
Los roles de sistema (is_system = true) también pueden actualizarse (nombre y/o permisos); la restricción de sistema sólo impide su eliminación.

Eliminación

La eliminación es definitiva (hard delete): el rol se borra de la base de datos.

No se puede eliminar un rol de sistema (is_system = true); el sistema devuelve error.
No se puede eliminar un rol que tenga usuarios asignados; el sistema devuelve error.

Consulta de roles

Un usuario con permiso ROLE:READ puede listar y consultar roles. Los resultados siempre están limitados a la organización del usuario autenticado (no hay acceso cross-org).

Listar: devuelve todos los roles de la organización con sus permisos, paginados.
Consultar por id: devuelve el rol con sus permisos y usuarios asociados. Si el rol no pertenece a la organización del usuario, se devuelve error 404.

Catálogo de permisos

Los permisos son una lista cerrada definida en migraciones: no se crean ni editan en runtime. Cada permiso combina un recurso y una acción (ej. USER:READ, ROLE:WRITE). Ver 02-permisos.md.

Cuando se añade un nuevo permiso al catálogo, el sistema lo asigna automáticamente al rol administrador de cada organización (respetando la restricción de ORGANIZATION, que solo aplica a organizaciones SUPER_ADMIN).

Condiciones de negocio (resumen)

Los roles son por organización; nombre único por organización.
Un rol puede tener cero o más permisos (la relación es muchos a muchos con el catálogo de permisos).
El rol administrador se crea automáticamente al crear una organización; es de sistema: no puede eliminarse, pero sí puede editarse (nombre y/o permisos).
Un rol con usuarios asignados no puede eliminarse.
La creación, actualización y eliminación requieren permiso ROLE:WRITE. La consulta requiere ROLE:READ.
Los resultados de consulta siempre están limitados a la organización del usuario autenticado.