feat(perfex-dev): adiciona plugin perfex-dev (agents, skills, knowledge e metadados do projeto)

2026-10-28 16:09:35 +00:00
parent b446fe25fe
commit 77c33e4d96
31 changed files with 2722 additions and 0 deletions
@@ -0,0 +1,208 @@
+---
+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'