# RF-ROLE-001: CRUD de Roles

## Identificacion

| Campo | Valor |
|-------|-------|
| **ID** | RF-ROLE-001 |
| **Modulo** | MGN-003 Roles/RBAC |
| **Prioridad** | P0 - Critica |
| **Estado** | Ready |
| **Fecha** | 2025-12-05 |

---

## Descripcion

El sistema debe permitir a los administradores crear, listar, ver, actualizar y eliminar roles dentro de su tenant. Los roles son contenedores de permisos que se asignan a usuarios para controlar su acceso a funcionalidades del sistema.

---

## Actores

| Actor | Descripcion |
|-------|-------------|
| Super Admin | Puede gestionar roles del sistema (built-in) |
| Admin | Puede crear y gestionar roles personalizados del tenant |

---

## Precondiciones

1. Usuario autenticado con permiso `roles:create`, `roles:read`, `roles:update` o `roles:delete`
2. Tenant activo
3. Para modificar: rol existente en el tenant

---

## Flujo Principal

### Crear Rol

```
1. Admin accede a Configuracion > Roles
2. Click en "Nuevo Rol"
3. Sistema muestra formulario:
   - Nombre del rol (unico en tenant)
   - Descripcion
   - Seleccion de permisos
4. Admin completa datos y selecciona permisos
5. Click en "Crear Rol"
6. Sistema valida unicidad del nombre
7. Sistema crea el rol con los permisos seleccionados
8. Sistema muestra mensaje de exito
```

### Listar Roles

```
1. Admin accede a Configuracion > Roles
2. Sistema muestra tabla con:
   - Nombre del rol
   - Descripcion
   - Numero de permisos
   - Numero de usuarios asignados
   - Es rol del sistema (built-in)
   - Fecha de creacion
3. Admin puede filtrar por:
   - Nombre
   - Tipo (sistema/personalizado)
4. Admin puede ordenar por cualquier columna
```

### Ver Detalle de Rol

```
1. Admin click en un rol de la lista
2. Sistema muestra:
   - Informacion basica del rol
   - Lista de permisos asignados (agrupados por modulo)
   - Lista de usuarios con este rol
   - Historial de cambios
```

### Actualizar Rol

```
1. Admin click en "Editar" de un rol
2. Sistema muestra formulario con datos actuales
3. Admin modifica campos permitidos
4. Click en "Guardar Cambios"
5. Sistema valida cambios
6. Sistema actualiza el rol
7. Sistema registra en auditoria
```

### Eliminar Rol

```
1. Admin click en "Eliminar" de un rol
2. Sistema verifica si hay usuarios asignados
3. Si hay usuarios:
   - Muestra advertencia con conteo
   - Opcion de reasignar a otro rol
4. Admin confirma eliminacion
5. Sistema aplica soft delete
6. Sistema desasigna usuarios (si se confirmo)
```

---

## Flujos Alternativos

### FA1: Nombre duplicado

```
1. En paso 6 del flujo crear
2. Sistema detecta nombre ya existe en tenant
3. Sistema muestra error "Ya existe un rol con este nombre"
4. Admin corrige el nombre
5. Continua desde paso 5
```

### FA2: Intentar eliminar rol del sistema

```
1. Admin intenta eliminar rol built-in (admin, user, etc.)
2. Sistema muestra error "No se pueden eliminar roles del sistema"
3. Operacion cancelada
```

### FA3: Intentar modificar rol del sistema

```
1. Admin intenta modificar rol built-in
2. Sistema permite solo agregar permisos adicionales
3. No permite quitar permisos base ni cambiar nombre
```

---

## Reglas de Negocio

| ID | Regla |
|----|-------|
| RN-001 | Nombre de rol unico dentro del tenant |
| RN-002 | Roles built-in no pueden eliminarse |
| RN-003 | Roles built-in solo pueden extenderse (agregar permisos) |
| RN-004 | Soft delete en lugar de hard delete |
| RN-005 | Rol debe tener al menos un permiso |
| RN-006 | Nombre del rol: 3-50 caracteres, alfanumerico con guiones |
| RN-007 | Al eliminar rol, usuarios quedan sin ese rol |
| RN-008 | Un tenant puede tener maximo 50 roles personalizados |

---

## Roles del Sistema (Built-in)

| Codigo | Nombre | Descripcion | Permisos Base |
|--------|--------|-------------|---------------|
| super_admin | Super Administrador | Acceso total al sistema | Todos |
| admin | Administrador | Gestion del tenant | Gestion usuarios, roles, config |
| manager | Gerente | Supervision operativa | Lectura + reportes |
| user | Usuario | Acceso basico | Solo lectura propia |
| guest | Invitado | Acceso minimo | Solo dashboard |

---

## Criterios de Aceptacion

### Escenario 1: Crear rol exitosamente

```gherkin
Given un admin autenticado con permiso "roles:create"
When crea un rol con nombre "Vendedor" y 5 permisos
Then el sistema crea el rol
  And el rol aparece en la lista
  And el rol tiene isBuiltIn = false
  And responde con status 201
```

### Escenario 2: Listar roles con paginacion

```gherkin
Given 25 roles en el tenant (5 built-in + 20 custom)
When el admin solicita GET /api/v1/roles?page=1&limit=10
Then el sistema retorna 10 roles
  And incluye meta con total=25, pages=3
  And roles built-in aparecen primero
```

### 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 de rol personalizado

```gherkin
Given un rol personalizado "Vendedor" con 3 usuarios
When el admin lo elimina con reasignacion a "user"
Then el rol tiene deleted_at establecido
  And los 3 usuarios ahora tienen rol "user"
  And el rol no aparece en listados
```

---

## 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       | ✏🗑|
|   | Almacenista     | Gestion inventario | 10       | 4       | ✏🗑|
+------------------------------------------------------------------+
| Mostrando 1-7 de 7                        [< Anterior] [Siguiente >]|
+------------------------------------------------------------------+

🔒 = Rol del sistema (built-in)

Modal: Crear/Editar Rol
┌──────────────────────────────────────────────────────────────────┐
│                        NUEVO ROL                                  │
├──────────────────────────────────────────────────────────────────┤
│  Nombre*          [_______________________________]              │
│  Descripcion      [_______________________________]              │
│                   [_______________________________]              │
│                                                                   │
│  PERMISOS                                        [Seleccionar todos]│
│  ┌────────────────────────────────────────────────────────────┐ │
│  │ ▼ Usuarios (4 permisos)                                     │ │
│  │   ☑ users:read    ☐ users:create                           │ │
│  │   ☐ users:update  ☐ users:delete                           │ │
│  │                                                              │ │
│  │ ▼ Roles (4 permisos)                                        │ │
│  │   ☑ roles:read    ☐ roles:create                           │ │
│  │   ☐ roles:update  ☐ roles:delete                           │ │
│  │                                                              │ │
│  │ ▼ Inventario (6 permisos)                                   │ │
│  │   ☑ inventory:read    ☑ inventory:create                   │ │
│  │   ☑ inventory:update  ☐ inventory:delete                   │ │
│  │   ☑ inventory:export  ☐ inventory:import                   │ │
│  └────────────────────────────────────────────────────────────┘ │
│                                                                   │
│  Permisos seleccionados: 7                                       │
│                                                                   │
│  [  Cancelar  ]                        [ Crear Rol ]             │
└──────────────────────────────────────────────────────────────────┘
```

---

## Notas Tecnicas

### API Endpoints

```typescript
// Crear rol
POST /api/v1/roles
{
  "name": "Vendedor",
  "description": "Equipo de ventas",
  "permissionIds": ["perm-uuid-1", "perm-uuid-2"]
}

// Response 201
{
  "id": "role-uuid",
  "name": "Vendedor",
  "slug": "vendedor",
  "description": "Equipo de ventas",
  "isBuiltIn": false,
  "permissions": [...],
  "usersCount": 0,
  "createdAt": "2025-12-05T10:00:00Z"
}

// Listar roles
GET /api/v1/roles?page=1&limit=10&search=vend&type=custom

// Response 200
{
  "data": [...],
  "meta": { "total": 25, "page": 1, "limit": 10 }
}

// Ver detalle
GET /api/v1/roles/:id

// Actualizar rol
PATCH /api/v1/roles/:id
{
  "name": "Vendedor Senior",
  "permissionIds": ["perm-1", "perm-2", "perm-3"]
}

// Eliminar rol
DELETE /api/v1/roles/:id?reassignTo=other-role-id
```

### Validaciones

| Campo | Validacion |
|-------|------------|
| name | Required, 3-50 chars, unique en tenant |
| slug | Auto-generado desde name |
| description | Optional, max 500 chars |
| permissionIds | Array min 1 elemento |

---

## Dependencias

| ID | Descripcion |
|----|-------------|
| RF-AUTH-001 | Login para autenticacion |
| RF-ROLE-002 | Permisos para asignar a roles |
| MGN-004 | Tenants para aislamiento |

---

## Estimacion

| Tarea | Puntos |
|-------|--------|
| Backend: CRUD endpoints | 5 |
| Backend: Validaciones y reglas | 3 |
| Backend: Tests | 2 |
| Frontend: RolesListPage | 3 |
| Frontend: RoleForm modal | 3 |
| Frontend: PermissionSelector | 2 |
| Frontend: Tests | 2 |
| **Total** | **20 SP** |

---

## Historial

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