claude-plugins/perfex-dev/skills/perfex-permissions/SKILL.md

---
name: perfex-permissions
description: Sistema de permissões Perfex CRM — staff_can(), register_staff_capabilities(), controlo de acesso e roles. Baseado apenas na documentação oficial.
layer: wiki
---

# /perfex-permissions - Permissões Perfex CRM

Sistema de permissões e controlo de acesso. **Zero assumptions, zero hallucinations** - apenas documentação oficial.

---

## Documentação Base

- [Staff Capabilities and Access](https://help.perfexcrm.com/staff-capabilities-and-access/)
- [Roles](https://help.perfexcrm.com/roles/)

---

## Conceitos Fundamentais

| Conceito | Descrição |
|----------|-----------|
| **Feature** | Área funcional (invoices, projects, meu_modulo) |
| **Capability** | Permissão específica (view, create, edit, delete) |
| **Role** | Conjunto de permissões pré-definido |

---

## Registar Permissões do Módulo

### No Init File

```php
hooks()->add_action('admin_init', 'meu_modulo_register_permissions');

function meu_modulo_register_permissions()
{
    $capabilities = [];

    $capabilities['capabilities'] = [
        'view'   => _l('permission_view'),    // Ver
        'create' => _l('permission_create'),  // Criar
        'edit'   => _l('permission_edit'),    // Editar
        'delete' => _l('permission_delete'),  // Apagar
    ];

    register_staff_capabilities(
        'meu_modulo',           // Feature ID (único)
        $capabilities,          // Array de capabilities
        _l('meu_modulo_title')  // Nome do módulo (mostrado em Settings)
    );
}
```

### Parâmetros register_staff_capabilities()

| Parâmetro | Tipo | Descrição |
|-----------|------|-----------|
| `$feature` | string | ID único da feature |
| `$capabilities` | array | Array com key 'capabilities' |
| `$name` | string | Nome mostrado na UI |

---

## Verificar Permissões: staff_can()

### Sintaxe

```php
staff_can($capability, $feature = null, $staff_id = '');
```

### Parâmetros

| Parâmetro | Tipo | Descrição |
|-----------|------|-----------|
| `$capability` | string | Nome da capability (view, create, etc.) |
| `$feature` | string | Feature ID (recomendado SEMPRE passar) |
| `$staff_id` | int | ID do staff (default: staff logado) |

### Retorno

- `true` - Staff tem permissão
- `false` - Staff não tem permissão

**NOTA:** Administradores SEMPRE retornam `true` (bypass total).

---

## Exemplos de Uso

### No Controller

```php
class Meu_modulo extends AdminController
{
    public function index()
    {
        // Verificar permissão de ver
        if (!staff_can('view', 'meu_modulo')) {
            access_denied('meu_modulo');
        }

        // ... código
    }

    public function create()
    {
        // Verificar permissão de criar
        if (!staff_can('create', 'meu_modulo')) {
            access_denied('meu_modulo');
        }

        // ... código
    }

    public function edit($id)
    {
        // Verificar permissão de editar
        if (!staff_can('edit', 'meu_modulo')) {
            access_denied('meu_modulo');
        }

        // ... código
    }

    public function delete($id)
    {
        // Verificar permissão de apagar
        if (!staff_can('delete', 'meu_modulo')) {
            access_denied('meu_modulo');
        }

        // ... código
    }
}
```

### Na View

```php
<!-- Mostrar botão apenas se tem permissão -->
<?php if (staff_can('create', 'meu_modulo')): ?>
    <a href="<?php echo admin_url('meu_modulo/create'); ?>" class="btn btn-primary">
        <i class="fa fa-plus"></i> <?php echo _l('create'); ?>
    </a>
<?php endif; ?>

<!-- Botões de acção condicionais -->
<td>
    <?php if (staff_can('edit', 'meu_modulo')): ?>
        <a href="<?php echo admin_url('meu_modulo/edit/' . $item->id); ?>"
           class="btn btn-default btn-icon">
            <i class="fa fa-pencil"></i>
        </a>
    <?php endif; ?>

    <?php if (staff_can('delete', 'meu_modulo')): ?>
        <a href="<?php echo admin_url('meu_modulo/delete/' . $item->id); ?>"
           class="btn btn-danger btn-icon _delete">
            <i class="fa fa-trash"></i>
        </a>
    <?php endif; ?>
</td>
```

### No Menu

```php
function meu_modulo_init_menu()
{
    // Só mostrar menu se tem permissão
    if (!staff_can('view', 'meu_modulo')) {
        return;
    }

    $CI = &get_instance();
    $CI->app_menu->add_sidebar_menu_item('meu-modulo', [
        'name'     => _l('meu_modulo'),
        'href'     => admin_url('meu_modulo'),
        'position' => 25,
        'icon'     => 'fa fa-cube',
    ]);
}
```

---

## Capabilities Padrão

### Recomendadas para CRUD

| Capability | Descrição | Uso |
|------------|-----------|-----|
| `view` | Ver registos | Listar, ver detalhes |
| `create` | Criar novos | Formulário de criação |
| `edit` | Editar existentes | Formulário de edição |
| `delete` | Apagar registos | Botão de eliminar |

### Adicionar Capabilities Custom

```php
$capabilities['capabilities'] = [
    // CRUD básico
    'view'   => _l('permission_view'),
    'create' => _l('permission_create'),
    'edit'