# 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

```gherkin
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

```gherkin
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

```gherkin
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

```gherkin
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

```gherkin
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

```gherkin
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

```typescript
// 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

```typescript
// 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 |