365 lines
11 KiB
Markdown
365 lines
11 KiB
Markdown
# 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 |
|