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

name, description, layer

name	description	layer
perfex-permissions	Sistema de permissões Perfex CRM — staff_can(), register_staff_capabilities(), controlo de acesso e roles. Baseado apenas na documentação oficial.	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
• 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

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

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

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

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

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

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