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
- Usuario autenticado con permiso
roles:create, roles:read, roles:update o roles:delete
- Tenant activo
- 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
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
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
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
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
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
// 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 |
