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

---
name: perfex-menus
description: Criação de menus para módulos Perfex CRM — sidebar, menus de cliente, add_sidebar_menu_item(), posições e ícones. Baseado apenas na documentação oficial.
layer: wiki
---

# /perfex-menus - Menus Perfex CRM

Criação de menus para módulos. **Zero assumptions, zero hallucinations** - apenas documentação oficial.

---

## Documentação Base

- [Create Menu Items](https://help.perfexcrm.com/create-menu-items/)

---

## Menu Admin (Sidebar)

### Adicionar Item Simples

```php
// No init file do módulo
hooks()->add_action('admin_init', 'meu_modulo_init_menu');

function meu_modulo_init_menu()
{
    $CI = &get_instance();

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

### Parâmetros

| Parâmetro | Tipo | Descrição |
|-----------|------|-----------|
| `name` | string | Texto do menu (usar _l() para tradução) |
| `href` | string | URL destino |
| `position` | int | Posição no menu (menor = mais acima) |
| `icon` | string | Classe Font Awesome |
| `collapse` | bool | Se tem sub-items (default: false) |
| `badge` | array | Badge com contagem |

---

## Menu com Sub-Items (Collapsible)

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

function meu_modulo_init_menu()
{
    $CI = &get_instance();

    // Menu pai (collapsible)
    $CI->app_menu->add_sidebar_menu_item('meu-modulo-menu', [
        'name'     => _l('meu_modulo_title'),
        'collapse' => true,
        'position' => 25,
        'icon'     => 'fa fa-cube',
    ]);

    // Sub-item 1
    $CI->app_menu->add_sidebar_children_item('meu-modulo-menu', [
        'slug'     => 'meu-modulo-lista',
        'name'     => _l('list'),
        'href'     => admin_url('meu_modulo'),
        'position' => 1,
        'icon'     => 'fa fa-list',
    ]);

    // Sub-item 2
    $CI->app_menu->add_sidebar_children_item('meu-modulo-menu', [
        'slug'     => 'meu-modulo-criar',
        'name'     => _l('create'),
        'href'     => admin_url('meu_modulo/create'),
        'position' => 2,
        'icon'     => 'fa fa-plus',
    ]);

    // Sub-item 3
    $CI->app_menu->add_sidebar_children_item('meu-modulo-menu', [
        'slug'     => 'meu-modulo-settings',
        'name'     => _l('settings'),
        'href'     => admin_url('meu_modulo/settings'),
        'position' => 3,
        'icon'     => 'fa fa-cog',
    ]);
}
```

---

## Posições Padrão Admin

| Posição | Menu Item |
|---------|-----------|
| 1 | Dashboard |
| 5 | Customers |
| 10 | Sales |
| 15 | Subscriptions |
| 20 | Expenses |
| 25 | Contracts |
| 30 | Projects |
| 35 | Tasks |
| 40 | Tickets |
| 45 | Leads |
| 50 | Knowledge Base |
| 55 | Utilities |
| 60 | Reports |

**Dica:** Usar posições intermédias (ex: 27, 32) para inserir entre items existentes.

---

## Badge (Contador)

```php
$CI->app_menu->add_sidebar_menu_item('meu-modulo-menu', [
    'name'     => _l('meu_modulo_title'),
    'href'     => admin_url('meu_modulo'),
    'position' => 25,
    'icon'     => 'fa fa-cube',
    'badge'    => [
        'value'      => meu_modulo_count_pending(),
        'type'       => 'danger',    // primary, success, warning, danger, info
        'show_on_sidebar' => true,
    ],
]);

// Função de contagem
function meu_modulo_count_pending()
{
    $CI = &get_instance();
    $CI->db->where('status', 'pending');
    return $CI->db->count_all_results(db_prefix() . 'meu_modulo');
}
```

---

## Menu Condicional (Permissões)

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

    $CI = &get_instance();

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

---

## Menu Cliente (Área Cliente)

### Adicionar Item

```php
hooks()->add_action('clients_init', 'meu_modulo_client_menu');

function meu_modulo_client_menu()
{
    // Só mostrar se cliente logado
    if (!is_client_logged_in()) {
        return;
    }

    add_theme_menu_item('meu-modulo', [
        'name'     => _l('meu_modulo_title'),
        'href'     => site_url('meu_modulo'),
        'position' => 35,
        'icon'     => 'fa fa-cube',
    ]);
}
```

### Posições Padrão Cliente

| Posição | Menu Item |
|---------|-----------|
| 5 | Knowledge Base |
| 10 | Projects |
| 15 | Invoices |
| 20 | Contracts |
| 25 | Estimates |
| 30 | Proposals |
| 40 | Subscriptions |
| 45 | Support |
| 99 | Registration |
| 100 | Login |

---

## Menu no Setup (Administração)

Para adicionar configurações ao menu Setup:

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

function meu_modulo_setup_menu()
{
    $CI = &get_instance();

    // Adicionar ao sub-menu de Setup