# 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 |