erp-core/docs/01-fase-foundation/MGN-003-roles/historias-usuario/US-MGN003-003.md

US-MGN003-003: Asignacion de Roles a Usuarios

Identificacion

Campo	Valor
ID	US-MGN003-003
Modulo	MGN-003 Roles/RBAC
Sprint	Sprint 2
Prioridad	P0 - Critica
Story Points	8
Estado	Ready
Autor	System
Fecha	2025-12-05

---

Historia de Usuario

Como administrador del sistema Quiero poder asignar y quitar roles a los usuarios Para controlar que acciones puede realizar cada usuario en el sistema

---

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 quien hizo la asignacion

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"
  And los cambios son inmediatos

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"

Escenario 6: Ver permisos efectivos

Given usuario con roles ["admin", "vendedor"]
When consulta GET /api/v1/users/:id/permissions
Then retorna union de permisos de ambos roles
  And indica cuales son directos y cuales heredados

---

Mockup / Wireframe

Modal: Gestionar Roles de Usuario
┌──────────────────────────────────────────────────────────────────┐
│  ROLES DE: Juan Perez (juan@empresa.com)                         │
├──────────────────────────────────────────────────────────────────┤
│                                                                   │
│  Selecciona los roles para este usuario:                         │
│                                                                   │
│  ┌────────────────────────────────────────────────────────────┐ │
│  │ 🔒 Super Admin   Acceso total al sistema           [ ]      │ │
│  │ 🔒 Admin         Gestion completa del tenant       [✓]      │ │
│  │ 🔒 Manager       Supervision operativa             [ ]      │ │
│  │ 🔒 User          Acceso basico                     [✓]      │ │
│  │    Vendedor      Equipo de ventas                  [✓]      │ │
│  │    Contador      Area contable                     [ ]      │ │
│  │    Almacenista   Gestion de inventario             [ ]      │ │
│  └────────────────────────────────────────────────────────────┘ │
│                                                                   │
│  Roles seleccionados: 3 (Admin, User, Vendedor)                  │
│  Permisos efectivos: 45 permisos                                 │
│                                                                   │
│  [Ver detalle de permisos]                                       │
│                                                                   │
│  [  Cancelar  ]                        [ Guardar Cambios ]       │
└──────────────────────────────────────────────────────────────────┘

Vista: Usuarios de un Rol (desde detalle de 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 | 🗑|
│                                                                   │
└──────────────────────────────────────────────────────────────────┘

---

Notas Tecnicas

API Endpoints

// Desde usuario - asignar roles
PUT /api/v1/users/:userId/roles
{ "roleIds": ["role-1", "role-2"] }

// Desde rol - asignar usuarios
POST /api/v1/roles/:roleId/users
{ "userIds": ["user-1", "user-2"] }

// Ver usuarios de un rol
GET /api/v1/roles/:roleId/users

// Ver permisos efectivos
GET /api/v1/users/:userId/permissions

Respuestas

// Asignacion exitosa
{
  "userId": "user-uuid",
  "roles": ["admin", "vendedor"],
  "effectivePermissions": ["users:*", "sales:*", ...]
}

// Asignacion masiva
{
  "results": {
    "success": ["user-1", "user-2"],
    "failed": [
      { "userId": "user-3", "reason": "Usuario no encontrado" }
    ]
  }
}

---

Definicion de Done

• Endpoint PUT /api/v1/users/:id/roles
• Endpoint POST /api/v1/roles/:id/users
• Endpoint GET /api/v1/roles/:id/users
• Endpoint GET /api/v1/users/:id/permissions
• Proteccion de rol super_admin
• Validacion de ultimo super_admin
• Calculo de permisos efectivos
• Frontend: RoleAssignmentModal
• Frontend: UsersOfRole view
• Tests unitarios
• Code review aprobado

---

Estimacion

Tarea	Horas
Backend: Endpoints	4h
Backend: Validaciones	2h
Backend: Permisos efectivos	2h
Backend: Tests	2h
Frontend: RoleAssignmentModal	4h
Frontend: BulkAssignment	2h
Frontend: Tests	2h
Total	18h

---

Historial

Version	Fecha	Autor	Cambios
1.0	2025-12-05	System	Creacion inicial