339 lines
8.2 KiB
Markdown
339 lines
8.2 KiB
Markdown
# RF-ROLE-002: Gestion de Permisos
|
|
|
|
## Identificacion
|
|
|
|
| Campo | Valor |
|
|
|-------|-------|
|
|
| **ID** | RF-ROLE-002 |
|
|
| **Modulo** | MGN-003 Roles/RBAC |
|
|
| **Prioridad** | P0 - Critica |
|
|
| **Estado** | Ready |
|
|
| **Fecha** | 2025-12-05 |
|
|
|
|
---
|
|
|
|
## Descripcion
|
|
|
|
El sistema debe mantener un catalogo de permisos que definen las acciones granulares que los usuarios pueden realizar. Los permisos se agrupan por modulo y se asignan a roles. El sistema soporta permisos jerarquicos donde un permiso padre implica todos sus hijos.
|
|
|
|
---
|
|
|
|
## Actores
|
|
|
|
| Actor | Descripcion |
|
|
|-------|-------------|
|
|
| Super Admin | Puede ver todos los permisos del sistema |
|
|
| Admin | Puede ver permisos disponibles para su tenant |
|
|
| Sistema | Registra nuevos permisos al instalar modulos |
|
|
|
|
---
|
|
|
|
## Precondiciones
|
|
|
|
1. Usuario autenticado con permiso `permissions:read`
|
|
2. Permisos base del sistema inicializados
|
|
|
|
---
|
|
|
|
## Catalogo de Permisos
|
|
|
|
### Estructura de Permisos
|
|
|
|
Los permisos siguen el patron `modulo:accion` o `modulo:recurso:accion`:
|
|
|
|
```
|
|
users:read - Leer usuarios
|
|
users:create - Crear usuarios
|
|
users:update - Actualizar usuarios
|
|
users:delete - Eliminar usuarios
|
|
users:* - Todos los permisos de usuarios (wildcard)
|
|
|
|
inventory:products:read - Leer productos
|
|
inventory:products:create - Crear productos
|
|
inventory:* - Todo el modulo inventario
|
|
```
|
|
|
|
### Permisos por Modulo
|
|
|
|
#### Modulo Auth (MGN-001)
|
|
|
|
| Permiso | Descripcion |
|
|
|---------|-------------|
|
|
| auth:sessions:read | Ver sesiones activas |
|
|
| auth:sessions:revoke | Revocar sesiones |
|
|
|
|
#### Modulo Users (MGN-002)
|
|
|
|
| Permiso | Descripcion |
|
|
|---------|-------------|
|
|
| users:read | Listar y ver usuarios |
|
|
| users:create | Crear usuarios |
|
|
| users:update | Actualizar usuarios |
|
|
| users:delete | Eliminar usuarios |
|
|
| users:activate | Activar/desactivar usuarios |
|
|
| users:export | Exportar lista de usuarios |
|
|
| users:import | Importar usuarios |
|
|
|
|
#### Modulo Roles (MGN-003)
|
|
|
|
| Permiso | Descripcion |
|
|
|---------|-------------|
|
|
| roles:read | Listar y ver roles |
|
|
| roles:create | Crear roles |
|
|
| roles:update | Actualizar roles |
|
|
| roles:delete | Eliminar roles |
|
|
| roles:assign | Asignar roles a usuarios |
|
|
| permissions:read | Ver permisos disponibles |
|
|
|
|
#### Modulo Tenants (MGN-004)
|
|
|
|
| Permiso | Descripcion |
|
|
|---------|-------------|
|
|
| tenants:read | Ver configuracion del tenant |
|
|
| tenants:update | Actualizar configuracion |
|
|
| tenants:billing | Gestionar facturacion |
|
|
|
|
#### Modulo Settings (MGN-006)
|
|
|
|
| Permiso | Descripcion |
|
|
|---------|-------------|
|
|
| settings:read | Ver configuracion |
|
|
| settings:update | Modificar configuracion |
|
|
|
|
#### Modulo Audit (MGN-007)
|
|
|
|
| Permiso | Descripcion |
|
|
|---------|-------------|
|
|
| audit:read | Ver logs de auditoria |
|
|
| audit:export | Exportar logs |
|
|
|
|
#### Modulo Reports (MGN-009)
|
|
|
|
| Permiso | Descripcion |
|
|
|---------|-------------|
|
|
| reports:read | Ver reportes |
|
|
| reports:create | Crear reportes personalizados |
|
|
| reports:export | Exportar reportes |
|
|
| reports:schedule | Programar reportes |
|
|
|
|
#### Modulo Financial (MGN-010)
|
|
|
|
| Permiso | Descripcion |
|
|
|---------|-------------|
|
|
| financial:accounts:read | Ver cuentas contables |
|
|
| financial:accounts:manage | Gestionar cuentas |
|
|
| financial:transactions:read | Ver transacciones |
|
|
| financial:transactions:create | Crear transacciones |
|
|
| financial:transactions:approve | Aprobar transacciones |
|
|
| financial:reports:read | Ver reportes financieros |
|
|
|
|
#### Modulo Inventory (MGN-011)
|
|
|
|
| Permiso | Descripcion |
|
|
|---------|-------------|
|
|
| inventory:products:read | Ver productos |
|
|
| inventory:products:create | Crear productos |
|
|
| inventory:products:update | Actualizar productos |
|
|
| inventory:products:delete | Eliminar productos |
|
|
| inventory:stock:read | Ver stock |
|
|
| inventory:stock:adjust | Ajustar stock |
|
|
| inventory:movements:read | Ver movimientos |
|
|
| inventory:movements:create | Crear movimientos |
|
|
|
|
---
|
|
|
|
## Flujo Principal
|
|
|
|
### Listar Permisos Disponibles
|
|
|
|
```
|
|
1. Admin accede a Configuracion > Roles > Nuevo/Editar
|
|
2. Sistema carga lista de permisos agrupados por modulo
|
|
3. Sistema muestra solo permisos habilitados para el tenant
|
|
4. Admin puede expandir/colapsar grupos
|
|
5. Admin puede buscar permisos por nombre
|
|
```
|
|
|
|
### Ver Permisos de un Rol
|
|
|
|
```
|
|
1. Admin accede a detalle de un rol
|
|
2. Sistema muestra permisos agrupados por modulo
|
|
3. Sistema indica cuales son heredados vs directos
|
|
4. Sistema muestra descripcion de cada permiso
|
|
```
|
|
|
|
---
|
|
|
|
## Reglas de Negocio
|
|
|
|
| ID | Regla |
|
|
|----|-------|
|
|
| RN-001 | Permisos son inmutables por usuarios |
|
|
| RN-002 | Permisos se registran por el sistema al instalar modulos |
|
|
| RN-003 | Permiso wildcard (*) incluye todas las acciones del modulo |
|
|
| RN-004 | Tenant solo ve permisos de modulos que tiene activos |
|
|
| RN-005 | Codigo de permiso unico globalmente |
|
|
| RN-006 | Permisos pueden estar activos o deprecados |
|
|
|
|
---
|
|
|
|
## Jerarquia de Permisos
|
|
|
|
```
|
|
users:* (Wildcard - todos los permisos de users)
|
|
├── users:read
|
|
├── users:create
|
|
├── users:update
|
|
├── users:delete
|
|
├── users:activate
|
|
├── users:export
|
|
└── users:import
|
|
|
|
inventory:* (Wildcard - todo inventario)
|
|
├── inventory:products:* (Wildcard - productos)
|
|
│ ├── inventory:products:read
|
|
│ ├── inventory:products:create
|
|
│ ├── inventory:products:update
|
|
│ └── inventory:products:delete
|
|
├── inventory:stock:*
|
|
│ ├── inventory:stock:read
|
|
│ └── inventory:stock:adjust
|
|
└── inventory:movements:*
|
|
├── inventory:movements:read
|
|
└── inventory:movements:create
|
|
```
|
|
|
|
---
|
|
|
|
## Criterios de Aceptacion
|
|
|
|
### Escenario 1: Listar permisos disponibles
|
|
|
|
```gherkin
|
|
Given un admin autenticado
|
|
When solicita GET /api/v1/permissions
|
|
Then el sistema retorna permisos agrupados por modulo
|
|
And cada permiso incluye code, name, description
|
|
And solo incluye permisos de modulos activos en el tenant
|
|
```
|
|
|
|
### Escenario 2: Buscar permisos
|
|
|
|
```gherkin
|
|
Given lista de 50 permisos
|
|
When el admin busca "users"
|
|
Then el sistema retorna solo permisos que contienen "users"
|
|
And mantiene agrupacion por modulo
|
|
```
|
|
|
|
### Escenario 3: Validar wildcard
|
|
|
|
```gherkin
|
|
Given un rol con permiso "users:*"
|
|
When se verifica si tiene "users:delete"
|
|
Then el sistema confirma que SI tiene el permiso
|
|
And el permiso es heredado (no directo)
|
|
```
|
|
|
|
### Escenario 4: Permisos por modulo deshabilitado
|
|
|
|
```gherkin
|
|
Given tenant sin modulo de inventario activo
|
|
When admin lista permisos disponibles
|
|
Then NO aparecen permisos de "inventory:*"
|
|
```
|
|
|
|
---
|
|
|
|
## Notas Tecnicas
|
|
|
|
### API Endpoints
|
|
|
|
```typescript
|
|
// Listar todos los permisos
|
|
GET /api/v1/permissions
|
|
// Query params: ?search=users&module=users
|
|
|
|
// Response 200
|
|
{
|
|
"data": [
|
|
{
|
|
"module": "users",
|
|
"moduleName": "Gestion de Usuarios",
|
|
"permissions": [
|
|
{
|
|
"id": "perm-uuid",
|
|
"code": "users:read",
|
|
"name": "Leer usuarios",
|
|
"description": "Permite ver listado y detalle de usuarios",
|
|
"isDeprecated": false
|
|
},
|
|
// ...
|
|
]
|
|
},
|
|
{
|
|
"module": "roles",
|
|
"moduleName": "Roles y Permisos",
|
|
"permissions": [...]
|
|
}
|
|
]
|
|
}
|
|
|
|
// Listar permisos de un rol
|
|
GET /api/v1/roles/:roleId/permissions
|
|
|
|
// Response 200
|
|
{
|
|
"direct": ["users:read", "users:create"],
|
|
"inherited": ["users:update"], // via wildcard
|
|
"all": ["users:read", "users:create", "users:update"]
|
|
}
|
|
```
|
|
|
|
### Modelo de Datos
|
|
|
|
```typescript
|
|
interface Permission {
|
|
id: string;
|
|
code: string; // users:read
|
|
name: string; // Leer usuarios
|
|
description: string;
|
|
module: string; // users
|
|
parentCode?: string; // users:* (para jerarquia)
|
|
isDeprecated: boolean;
|
|
createdAt: Date;
|
|
}
|
|
```
|
|
|
|
---
|
|
|
|
## Dependencias
|
|
|
|
| ID | Descripcion |
|
|
|----|-------------|
|
|
| RF-ROLE-001 | Roles que contienen permisos |
|
|
| MGN-004 | Tenants para filtrar por modulos activos |
|
|
|
|
---
|
|
|
|
## Estimacion
|
|
|
|
| Tarea | Puntos |
|
|
|-------|--------|
|
|
| Backend: Seed de permisos | 2 |
|
|
| Backend: Endpoint listar | 2 |
|
|
| Backend: Logica wildcard | 3 |
|
|
| Backend: Tests | 2 |
|
|
| Frontend: PermissionsList component | 2 |
|
|
| Frontend: Tests | 1 |
|
|
| **Total** | **12 SP** |
|
|
|
|
---
|
|
|
|
## Historial
|
|
|
|
| Version | Fecha | Autor | Cambios |
|
|
|---------|-------|-------|---------|
|
|
| 1.0 | 2025-12-05 | System | Creacion inicial |
|