claude-plugins/perfex-dev/skills/perfex-module-basics/SKILL.md

---
name: perfex-module-basics
description: Fundamentos de desenvolvimento de módulos Perfex CRM — estrutura de pastas, ficheiro init, headers e integração CodeIgniter. Baseado apenas na documentação oficial.
layer: wiki
---

# /perfex-module-basics - Estrutura Base Módulos Perfex CRM

Fundamentos para desenvolvimento de módulos Perfex CRM. **Zero assumptions, zero hallucinations** - apenas documentação oficial.

---

## Documentação Base

- [Module Basics](https://help.perfexcrm.com/module-basics/)
- [Introduction to Modules](https://help.perfexcrm.com/introduction-to-perfex-crm-modules/)
- [Module File Headers](https://help.perfexcrm.com/module-file-headers/)

---

## Estrutura de Pastas (Obrigatória)

```
modules/
└── meu_modulo/
    ├── meu_modulo.php      # Init file (OBRIGATÓRIO - mesmo nome da pasta)
    ├── controllers/
    │   └── Meu_modulo.php
    ├── models/
    │   └── Meu_modulo_model.php
    ├── views/
    │   ├── index.php
    │   └── form.php
    ├── libraries/
    ├── helpers/
    ├── language/
    │   └── english/
    │       └── meu_modulo_lang.php
    ├── migrations/
    │   └── 001_version_100.php
    ├── config/
    └── index.html          # SEGURANÇA - prevenir directory listing
```

---

## Init File (Obrigatório)

O ficheiro init é o ponto de entrada do módulo. **DEVE ter o mesmo nome da pasta.**

### Template Mínimo

```php
<?php

defined('BASEPATH') or exit('No direct script access allowed');

/*
Module Name: Meu Módulo
Description: Descrição do módulo
Version: 1.0.0
Requires at least: 2.3.*
Author: Descomplicar
Author URI: https://descomplicar.pt
*/

// Registar hooks de activação/desactivação
register_activation_hook('meu_modulo', 'meu_modulo_activation_hook');
register_deactivation_hook('meu_modulo', 'meu_modulo_deactivation_hook');
register_uninstall_hook('meu_modulo', 'meu_modulo_uninstall_hook');

/**
 * Executado quando o módulo é activado
 */
function meu_modulo_activation_hook()
{
    $CI = &get_instance();

    // Criar tabelas
    if (!$CI->db->table_exists(db_prefix() . 'meu_modulo')) {
        $CI->db->query('CREATE TABLE `' . db_prefix() . 'meu_modulo` (
            `id` INT(11) NOT NULL AUTO_INCREMENT,
            `name` VARCHAR(255) NOT NULL,
            `created_at` DATETIME NOT NULL,
            PRIMARY KEY (`id`)
        ) ENGINE=InnoDB DEFAULT CHARSET=' . $CI->db->char_set . ';');
    }

    // Adicionar opções
    add_option('meu_modulo_version', '1.0.0');
}

/**
 * Executado quando o módulo é desactivado
 */
function meu_modulo_deactivation_hook()
{
    // Limpeza temporária (não apagar dados)
}

/**
 * Executado quando o módulo é removido
 */
function meu_modulo_uninstall_hook()
{
    $CI = &get_instance();

    // Remover tabelas
    $CI->db->query('DROP TABLE IF EXISTS `' . db_prefix() . 'meu_modulo`');

    // Remover opções
    delete_option('meu_modulo_version');
}
```

---

## File Headers (Meta-Informação)

### Headers Obrigatórios

| Header | Descrição |
|--------|-----------|
| `Module Name` | **ÚNICO OBRIGATÓRIO** - Nome do módulo |

### Headers Opcionais (Recomendados)

| Header | Descrição | Exemplo |
|--------|-----------|---------|
| `Description` | Descrição funcional | `CRM integration module` |
| `Version` | Versão semântica | `1.0.0` |
| `Requires at least` | Versão mínima Perfex | `2.3.*` |
| `Author` | Nome do autor | `Descomplicar` |
| `Author URI` | Website do autor | `https://descomplicar.pt` |
| `Module URI` | Página do módulo | `https://...` |

### Exemplo Completo

```php
/*
Module Name: Customer Portal
Description: Extended customer self-service portal
Version: 2.1.0
Requires at least: 2.3.*
Author: Descomplicar
Author URI: https://descomplicar.pt
Module URI: https://descomplicar.pt/modules/customer-portal
*/
```

---

## Aceder ao CodeIgniter

Fora de controllers/models, usar `get_instance()`:

```php
$CI = &get_instance();

// Carregar helper
$CI->load->helper('meu_modulo/meu_helper');

// Carregar library
$CI->load->library('meu_modulo/minha_library');

// Carregar model
$CI->load->model('meu_modulo/meu_modulo_model');

// Aceder à BD
$CI->db->get(db_prefix() . 'meu_modulo');
```

---

## Funções de Módulo Essenciais

### Paths e URLs

```php
// URL do módulo
$url = module_dir_url('meu_modulo');
// Resultado: https://crm.exemplo.pt/modules/meu_modulo/

// Path absoluto
$path = module_dir_path('meu_modulo');
// Resultado: /var/www/html/modules/meu_modulo/

// Path das libraries
$libs_path = module_libs_path('meu_modulo');
// Resultado: /var/www/html/modules/meu_modulo/libraries/
```

### Opções (Persistência)

```php
// Criar opção (não sobrescreve se existir)
add_option('meu_modulo_setting', 'valor', 0);

// Ler opção
$valor = get_option('meu_modulo_setting');

// Actualizar opção (cria se não existir - v2.3.3+)
update_option('meu_modulo_setting', 'novo_valor');

// Apagar opção
delete_option('meu_modulo_setting');
```

### Database Prefix

**SEMPRE usar `db_prefix()` em queries:**

```php
// CORRECTO
$CI->db->get(db_prefix() . 'meu_modulo