# US-MGN003-001: CRUD de Roles

## Identificacion

| Campo | Valor |
|-------|-------|
| **ID** | US-MGN003-001 |
| **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 crear, ver, editar y eliminar roles
**Para** gestionar los niveles de acceso de los usuarios a las funcionalidades del sistema

---

## Criterios de Aceptacion

### Escenario 1: Crear rol exitosamente

```gherkin
Given un admin autenticado con permiso "roles:create"
When crea un rol con:
  | name        | Vendedor           |
  | description | Equipo de ventas   |
  | permissions | [sales:*, users:read] |
Then el sistema crea el rol
  And el rol tiene slug "vendedor"
  And el rol tiene isBuiltIn = false
  And responde con status 201
```

### Escenario 2: Listar roles con paginacion

```gherkin
Given 12 roles en el tenant (5 built-in + 7 custom)
When el admin solicita GET /api/v1/roles?page=1&limit=10
Then el sistema retorna 10 roles
  And roles built-in aparecen primero
  And incluye usersCount y permissionsCount por rol
  And incluye meta con total=12
```

### Escenario 3: No crear rol con nombre duplicado

```gherkin
Given un rol existente con nombre "Vendedor"
When el admin intenta crear otro rol "Vendedor"
Then el sistema responde con status 409
  And el mensaje es "Ya existe un rol con este nombre"
```

### Escenario 4: No eliminar rol del sistema

```gherkin
Given el rol built-in "admin"
When el admin intenta eliminarlo
Then el sistema responde con status 400
  And el mensaje es "No se pueden eliminar roles del sistema"
```

### Escenario 5: Soft delete con reasignacion

```gherkin
Given rol "Vendedor" con 5 usuarios asignados
When admin elimina el rol con reassignTo="user"
Then el rol tiene deleted_at establecido
  And los 5 usuarios ahora tienen rol "user"
  And el rol no aparece en listados normales
```

---

## Mockup / Wireframe

```
+------------------------------------------------------------------+
|  [Logo]   Roles                           [+ Nuevo Rol]          |
+------------------------------------------------------------------+
| Buscar: [___________________] [Tipo: Todos ▼]                    |
+------------------------------------------------------------------+
| | Nombre          | Descripcion        | Permisos | Usuarios | ⚙ |
|---|-----------------|--------------------|-----------|---------|----|
| 🔒| Super Admin     | Acceso total       | 45       | 1       | 👁 |
| 🔒| Admin           | Gestion tenant     | 32       | 3       | 👁 |
| 🔒| Manager         | Supervision        | 18       | 5       | 👁 |
| 🔒| User            | Acceso basico      | 8        | 42      | 👁 |
|   | Vendedor        | Equipo de ventas   | 12       | 8       | ✏🗑|
|   | Contador        | Area contable      | 15       | 2       | ✏🗑|
+------------------------------------------------------------------+

🔒 = Rol del sistema (built-in), no editable/eliminable
```

---

## Notas Tecnicas

### API Endpoints

```typescript
POST /api/v1/roles
GET /api/v1/roles?page=1&limit=10&type=custom&search=vend
GET /api/v1/roles/:id
PATCH /api/v1/roles/:id
DELETE /api/v1/roles/:id?reassignTo=other-role-id
```

### Validaciones

| Campo | Regla |
|-------|-------|
| name | 3-50 chars, unico en tenant |
| description | Max 500 chars |
| permissionIds | Array min 1 |

---

## Definicion de Done

- [ ] Endpoint POST /api/v1/roles
- [ ] Endpoint GET /api/v1/roles con paginacion
- [ ] Endpoint GET /api/v1/roles/:id
- [ ] Endpoint PATCH /api/v1/roles/:id
- [ ] Endpoint DELETE /api/v1/roles/:id
- [ ] Validacion de roles built-in
- [ ] Frontend: RolesListPage
- [ ] Frontend: CreateRoleModal
- [ ] Frontend: EditRoleModal
- [ ] Tests unitarios
- [ ] Code review aprobado

---

## Estimacion

| Tarea | Horas |
|-------|-------|
| Backend: CRUD endpoints | 5h |
| Backend: Validaciones | 2h |
| Backend: Tests | 2h |
| Frontend: RolesListPage | 4h |
| Frontend: RoleForm | 4h |
| Frontend: Tests | 2h |
| **Total** | **19h** |

---

## Historial

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