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,180 @@
+---
+name: perfex-hooks
+description: Sistema de hooks Perfex CRM — actions, filters, add_action, add_filter, do_action, apply_filters com lista completa por categoria. Baseado apenas na documentação oficial.
+layer: wiki
+---
+
+# /perfex-hooks - Sistema de Hooks Perfex CRM
+
+Sistema de extensibilidade via actions e filters. **Zero assumptions, zero hallucinations** - apenas documentação oficial.
+
+---
+
+## Documentação Base
+
+- [Action Hooks](https://help.perfexcrm.com/action-hooks/)
+- [GitHub Hook List](https://gist.github.com/JamesSimpson/4eae4ba2d6d7072eca9f0fae58b8887c)
+
+---
+
+## Conceitos Fundamentais
+
+| Tipo | Função | Retorno | Uso |
+|------|--------|---------|-----|
+| **Action** | Executa lógica após eventos | void | Side effects (logs, emails, etc.) |
+| **Filter** | Modifica dados antes de processamento | Dados modificados | Alterar valores |
+
+---
+
+## Sintaxe (v2.3.0+)
+
+### Registar Action
+
+```php
+hooks()->add_action($tag, $callback, $priority = 10, $accepted_args = 1);
+```
+
+**Parâmetros:**
+- `$tag` (string): Nome do hook
+- `$callback` (callable): Função a executar
+- `$priority` (int): Ordem de execução (menor = primeiro). Default: 10
+- `$accepted_args` (int): Número de argumentos. Default: 1
+
+**Exemplo:**
+
+```php
+// No init file do módulo
+hooks()->add_action('after_client_added', 'meu_modulo_after_client_added');
+
+function meu_modulo_after_client_added($clientId)
+{
+    // Lógica após cliente criado
+    log_activity('Novo cliente criado: ' . $clientId);
+
+    // Enviar notificação
+    $CI = &get_instance();
+    $CI->load->model('clients_model');
+    $client = $CI->clients_model->get($clientId);
+
+    // Integração externa, etc.
+}
+```
+
+### Registar Filter
+
+```php
+hooks()->add_filter($tag, $callback, $priority = 10, $accepted_args = 1);
+```
+
+**Exemplo:**
+
+```php
+hooks()->add_filter('before_client_added', 'meu_modulo_before_client_added');
+
+function meu_modulo_before_client_added($data)
+{
+    // Modificar dados antes de guardar
+    if (empty($data['country'])) {
+        $data['country'] = 177; // Portugal
+    }
+
+    // OBRIGATÓRIO: retornar dados modificados
+    return $data;
+}
+```
+
+### Executar Action (criar hooks próprios)
+
+```php
+hooks()->do_action($tag, $arg = '');
+```
+
+**Exemplo:**
+
+```php
+// No teu módulo, permitir que outros módulos executem código
+hooks()->do_action('meu_modulo_after_process', $resultId);
+```
+
+### Aplicar Filter (criar filters próprios)
+
+```php
+hooks()->apply_filters($tag, $value, $additionalParams = []);
+```
+
+**Exemplo:**
+
+```php
+// Permitir que outros módulos modifiquem dados
+$data = hooks()->apply_filters('meu_modulo_data', $data);
+```
+
+---
+
+## Onde Colocar Hooks
+
+### Opção 1: Init File do Módulo (Recomendado)
+
+```php
+// modules/meu_modulo/meu_modulo.php
+hooks()->add_action('after_client_added', 'meu_modulo_client_handler');
+```
+
+### Opção 2: my_functions_helper.php (Customizações Simples)
+
+```php
+// application/helpers/my_functions_helper.php
+hooks()->add_action('after_client_added', 'custom_client_handler');
+```
+
+---
+
+## Lista Completa de Hooks por Categoria
+
+### Autenticação
+
+| Hook | Trigger | Argumentos |
+|------|---------|------------|
+| `admin_auth_init` | Início auth admin | - |
+| `after_staff_login` | Após login staff | $staff_id |
+| `after_user_logout` | Após logout | - |
+| `after_contact_login` | Após login contacto | $contact_id |
+| `after_client_register` | Após registo cliente | $client_id |
+| `after_client_logout` | Após logout cliente | - |
+
+### Clientes
+
+| Hook | Trigger | Argumentos |
+|------|---------|------------|
+| `before_client_added` | **FILTER** - Antes de criar | $data |
+| `after_client_added` | Após criar cliente | $client_id |
+| `before_client_updated` | **FILTER** - Antes de actualizar | $data, $client_id |
+| `after_client_updated` | Após actualizar | $client_id |
+| `before_client_deleted` | Antes de apagar | $client_id |
+| `after_client_deleted` | Após apagar | $client_id |
+| `contact_created` | Contacto criado | $contact_id |
+| `contact_updated` | Contacto actualizado | $contact_id |
+| `before_delete_contact` | Antes apagar contacto | $contact_id |
+| `contact_deleted` | Contacto apagado | $contact_id |
+
+### Facturas
+
+| Hook | Trigger | Argumentos |
+|------|---------|------------|
+| `before_invoice_added` | **FILTER** - Antes de criar | $data |
+| `after_invoice_added` | Após criar | $invoice_id |
+| `before_invoice_updated` | **FILTER** - Antes de actualizar | $data, $invoice_id |
+| `after_invoice_updated` | Após actualizar | $invoice_id |
+| `invoice_sent` | Factura enviada | $invoice_id |
+| `invoice_status_changed` | Status alterado | $invoice_id, $status |
+| `before_invoice_deleted` | Antes de apagar | $invoice_id |
+| `invoice_marked_as_cancelled` | Factura cancelada | $invoice_id |
+
+### Orçamentos (Estimates)
+
+| Hook | Trigger | Argumentos |
+|------|---------|------------|
+| `before_estimate_added` | **FILTER** - Antes de criar | $data |
+| `after_estimate_added` | Após criar | $estimate_id |
+| `after_estimate_updated` | Após actualizar | $estimate_id |
+| `estimate_