RF-ROLE-003: Asignacion de Roles a Usuarios
Identificacion
| Campo |
Valor |
| ID |
RF-ROLE-003 |
| Modulo |
MGN-003 Roles/RBAC |
| Prioridad |
P0 - Critica |
| Estado |
Ready |
| Fecha |
2025-12-05 |
Descripcion
El sistema debe permitir asignar uno o mas roles a cada usuario. Los permisos efectivos de un usuario son la union de todos los permisos de sus roles asignados. La asignacion puede realizarse desde la gestion de usuarios o desde la gestion de roles.
Actores
| Actor |
Descripcion |
| Super Admin |
Puede asignar cualquier rol a cualquier usuario |
| Admin |
Puede asignar roles (excepto super_admin) a usuarios del tenant |
Precondiciones
- Usuario autenticado con permiso
roles:assign
- Usuario destino existente y activo
- Rol existente y activo
Flujo Principal
Asignar Rol desde Usuario
1. Admin accede a Usuarios > Detalle de usuario
2. Click en "Gestionar Roles"
3. Sistema muestra:
- Roles actuales del usuario
- Roles disponibles para asignar
4. Admin selecciona roles a asignar
5. Admin deselecciona roles a quitar
6. Click en "Guardar Cambios"
7. Sistema actualiza asignaciones
8. Sistema recalcula permisos del usuario
9. Sistema muestra confirmacion
Asignar Usuarios desde Rol
1. Admin accede a Roles > Detalle de rol
2. Click en pestaña "Usuarios"
3. Sistema muestra usuarios con este rol
4. Click en "Agregar Usuarios"
5. Sistema muestra lista de usuarios sin este rol
6. Admin selecciona usuarios
7. Click en "Asignar"
8. Sistema asigna rol a usuarios seleccionados
Asignacion Masiva
1. Admin accede a Usuarios
2. Selecciona multiples usuarios (checkbox)
3. Click en "Acciones > Asignar Rol"
4. Sistema muestra selector de rol
5. Admin selecciona rol
6. Sistema asigna rol a todos los usuarios seleccionados
Flujos Alternativos
FA1: Usuario ya tiene el rol
1. Admin intenta asignar rol que usuario ya tiene
2. Sistema ignora la asignacion duplicada
3. Continua sin error
FA2: Quitar ultimo rol
1. Admin intenta quitar el unico rol del usuario
2. Sistema muestra advertencia
3. Admin confirma o cancela
4. Si confirma: usuario queda sin roles (acceso minimo)
FA3: Admin intenta asignar super_admin
1. Admin (no super_admin) intenta asignar rol super_admin
2. Sistema muestra error "Solo Super Admin puede asignar este rol"
3. Operacion cancelada
Reglas de Negocio
| ID |
Regla |
| RN-001 |
Usuario puede tener multiples roles |
| RN-002 |
Permisos efectivos = union de permisos de todos los roles |
| RN-003 |
Solo super_admin puede asignar rol super_admin |
| RN-004 |
No se puede quitar rol super_admin del ultimo super_admin |
| RN-005 |
Cambios de roles toman efecto inmediato |
| RN-006 |
Se registra en auditoria cada cambio de asignacion |
| RN-007 |
Usuario sin roles tiene acceso minimo (solo perfil propio) |
Criterios de Aceptacion
Escenario 1: Asignar rol a usuario
Given un usuario "juan@empresa.com" con rol "user"
And un rol "vendedor" disponible
When el admin asigna rol "vendedor" al usuario
Then el usuario tiene roles ["user", "vendedor"]
And el usuario tiene permisos de ambos roles combinados
And se registra en auditoria
Escenario 2: Quitar rol de usuario
Given un usuario con roles ["admin", "manager"]
When el admin quita el rol "manager"
Then el usuario solo tiene rol ["admin"]
And pierde los permisos exclusivos de "manager"
Escenario 3: Asignacion masiva
Given 10 usuarios seleccionados
And rol "vendedor" disponible
When el admin asigna "vendedor" a todos
Then los 10 usuarios tienen rol "vendedor" agregado
And responde con resumen: { success: 10, failed: 0 }
Escenario 4: Proteccion de super_admin
Given un admin autenticado (no super_admin)
When intenta asignar rol "super_admin" a un usuario
Then el sistema responde con status 403
And el mensaje es "Solo Super Admin puede asignar este rol"
Escenario 5: No quitar ultimo super_admin
Given solo 1 usuario con rol "super_admin"
When se intenta quitar el rol
Then el sistema responde con status 400
And el mensaje es "Debe existir al menos un Super Admin"
Mockup / Wireframe
Modal: Gestionar Roles de Usuario
┌──────────────────────────────────────────────────────────────────┐
│ ROLES DE: Juan Perez (juan@empresa.com) │
├──────────────────────────────────────────────────────────────────┤
│ │
│ Roles Asignados: │
│ ┌────────────────────────────────────────────────────────────┐ │
│ │ ☑ Admin Gestion completa del tenant [x] │ │
│ │ ☑ Manager Supervision operativa [x] │ │
│ │ ☐ User Acceso basico │ │
│ │ ☐ Vendedor Equipo de ventas │ │
│ │ ☐ Contador Area contable │ │
│ │ ☐ Almacenista Gestion de inventario │ │
│ └────────────────────────────────────────────────────────────┘ │
│ │
│ Permisos Efectivos: 45 permisos (de 2 roles) │
│ [Ver detalle de permisos] │
│ │
│ [ Cancelar ] [ Guardar Cambios ] │
└──────────────────────────────────────────────────────────────────┘
Vista: Usuarios de un Rol
┌──────────────────────────────────────────────────────────────────┐
│ ROL: Vendedor [+ Agregar Usuarios]│
├──────────────────────────────────────────────────────────────────┤
│ Usuarios con este rol (8): │
│ │
│ | Avatar | Nombre | Email | Desde | ⚙ |
│ |--------|----------------|--------------------|-----------|----|
│ | 👤 | Carlos Lopez | carlos@empresa.com | 01/12/2025 | 🗑|
│ | 👤 | Maria Garcia | maria@empresa.com | 15/11/2025 | 🗑|
│ | 👤 | Pedro Martinez | pedro@empresa.com | 10/11/2025 | 🗑|
│ | ... | ... | ... | ... | ...|
│ │
│ Mostrando 1-8 de 8 │
└──────────────────────────────────────────────────────────────────┘
Notas Tecnicas
API Endpoints
// Asignar roles a usuario
PUT /api/v1/users/:userId/roles
{
"roleIds": ["role-uuid-1", "role-uuid-2"]
}
// Response 200
{
"userId": "user-uuid",
"roles": [
{ "id": "role-uuid-1", "name": "Admin", "assignedAt": "..." },
{ "id": "role-uuid-2", "name": "Manager", "assignedAt": "..." }
],
"effectivePermissions": ["users:*", "reports:read", ...]
}
// Agregar rol a usuario (sin quitar existentes)
POST /api/v1/users/:userId/roles
{
"roleId": "role-uuid"
}
// Quitar rol de usuario
DELETE /api/v1/users/:userId/roles/:roleId
// Asignar rol a multiples usuarios
POST /api/v1/roles/:roleId/users
{
"userIds": ["user-1", "user-2", "user-3"]
}
// Response 200
{
"roleId": "role-uuid",
"results": {
"success": ["user-1", "user-2"],
"failed": [{ "userId": "user-3", "reason": "Ya tiene el rol" }]
}
}
// Listar usuarios de un rol
GET /api/v1/roles/:roleId/users?page=1&limit=20
// Obtener permisos efectivos de usuario
GET /api/v1/users/:userId/permissions
// Response 200
{
"roles": ["admin", "manager"],
"permissions": {
"direct": [...], // Permisos de roles asignados
"inherited": [...], // Via wildcards
"all": [...] // Union de todos
}
}
Calculo de Permisos Efectivos
function calculateEffectivePermissions(userId: string): string[] {
// 1. Obtener roles del usuario
const userRoles = await getUserRoles(userId);
// 2. Obtener permisos de cada rol
const allPermissions = new Set<string>();
for (const role of userRoles) {
const rolePermissions = await getRolePermissions(role.id);
rolePermissions.forEach(p => allPermissions.add(p));
}
// 3. Expandir wildcards
const expanded = expandWildcards(allPermissions);
return Array.from(expanded);
}
function expandWildcards(permissions: Set<string>): Set<string> {
const result = new Set(permissions);
for (const perm of permissions) {
if (perm.endsWith(':*')) {
// users:* -> agregar users:read, users:create, etc.
const module = perm.replace(':*', '');
const modulePerms = getModulePermissions(module);
modulePerms.forEach(p => result.add(p));
}
}
return result;
}
Dependencias
| ID |
Descripcion |
| RF-ROLE-001 |
Roles existentes para asignar |
| RF-ROLE-002 |
Permisos para calcular efectivos |
| RF-USER-001 |
Usuarios existentes |
Estimacion
| Tarea |
Puntos |
| Backend: Endpoints asignacion |
3 |
| Backend: Calculo permisos efectivos |
3 |
| Backend: Validaciones y reglas |
2 |
| Backend: Tests |
2 |
| Frontend: RoleAssignment modal |
3 |
| Frontend: BulkAssignment |
2 |
| Frontend: Tests |
2 |
| Total |
17 SP |
Historial
| Version |
Fecha |
Autor |
Cambios |
| 1.0 |
2025-12-05 |
System |
Creacion inicial |
