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,211 @@
+---
+name: perfex-migrations
+description: Migrações e upgrades de módulos Perfex CRM — gestão de versões, ficheiros de migração e actualizações de base de dados. Baseado apenas na documentação oficial.
+layer: wiki
+---
+
+# /perfex-migrations - Migrations Perfex CRM
+
+Sistema de migrações e upgrades de módulos. **Zero assumptions, zero hallucinations** - apenas documentação oficial.
+
+---
+
+## Documentação Base
+
+- [Preparing Module Upgrade](https://help.perfexcrm.com/preparing-module-upgrade/)
+- [Module Basics](https://help.perfexcrm.com/module-basics/)
+
+---
+
+## Como Funciona
+
+O Perfex CRM compara:
+- **Versão no init file** (header `Version:`)
+- **Versão na base de dados** (tabela `tblmodules`)
+
+Se forem diferentes → Sistema mostra "Database upgrade required".
+
+---
+
+## Estrutura de Migrations
+
+```
+modules/meu_modulo/
+├── meu_modulo.php          # Init file com Version: X.Y.Z
+└── migrations/
+    ├── 001_version_100.php  # v1.0.0 → v1.0.1
+    ├── 002_version_101.php  # v1.0.1 → v1.0.2
+    ├── 100_version_100.php  # v1.0.0 inicial (alternativa)
+    ├── 110_version_110.php  # v1.1.0
+    └── 200_version_200.php  # v2.0.0
+```
+
+---
+
+## Formato do Ficheiro
+
+### Nomenclatura (CRÍTICO)
+
+O Perfex usa **Sequential Migration** (não Timestamp).
+
+```
+NNN_version_NNN.php
+│   │       │
+│   │       └── Versão sem pontos (110 = 1.1.0)
+│   └── Literal "version"
+└── Número sequencial (3 dígitos, sem gaps)
+```
+
+**Exemplos:**
+
+| Versão | Ficheiro |
+|--------|----------|
+| 1.0.0 | `001_version_100.php` ou `100_version_100.php` |
+| 1.0.1 | `002_version_101.php` ou `101_version_101.php` |
+| 1.1.0 | `003_version_110.php` ou `110_version_110.php` |
+| 2.0.0 | `004_version_200.php` ou `200_version_200.php` |
+
+**Convenção recomendada:** Usar versão como prefixo (100, 110, 200...).
+
+---
+
+## Template Migration
+
+```php
+<?php
+
+defined('BASEPATH') or exit('No direct script access allowed');
+
+class Migration_Version_110 extends App_module_migration
+{
+    /**
+     * Executado durante upgrade
+     */
+    public function up()
+    {
+        // Alterações de base de dados aqui
+    }
+}
+```
+
+### Notas Importantes
+
+1. **Classe:** `Migration_Version_NNN` (NNN = versão sem pontos)
+2. **Extends:** `App_module_migration`
+3. **Método:** Apenas `up()` - não há `down()` (downgrades não suportados)
+4. **Pode ser vazio:** Se não houver alterações de BD, deixar `up()` vazio
+
+---
+
+## Exemplos de Migrations
+
+### Adicionar Coluna
+
+```php
+<?php
+
+defined('BASEPATH') or exit('No direct script access allowed');
+
+class Migration_Version_110 extends App_module_migration
+{
+    public function up()
+    {
+        $CI = &get_instance();
+
+        // Adicionar coluna se não existir
+        if (!$CI->db->field_exists('new_column', db_prefix() . 'meu_modulo')) {
+            $CI->db->query('ALTER TABLE `' . db_prefix() . 'meu_modulo`
+                ADD COLUMN `new_column` VARCHAR(255) DEFAULT NULL AFTER `name`');
+        }
+    }
+}
+```
+
+### Criar Nova Tabela
+
+```php
+<?php
+
+defined('BASEPATH') or exit('No direct script access allowed');
+
+class Migration_Version_120 extends App_module_migration
+{
+    public function up()
+    {
+        $CI = &get_instance();
+
+        if (!$CI->db->table_exists(db_prefix() . 'meu_modulo_items')) {
+            $CI->db->query('
+                CREATE TABLE `' . db_prefix() . 'meu_modulo_items` (
+                    `id` INT(11) UNSIGNED NOT NULL AUTO_INCREMENT,
+                    `parent_id` INT(11) UNSIGNED NOT NULL,
+                    `name` VARCHAR(255) NOT NULL,
+                    `quantity` INT(11) NOT NULL DEFAULT 1,
+                    PRIMARY KEY (`id`),
+                    KEY `parent_id` (`parent_id`)
+                ) ENGINE=InnoDB DEFAULT CHARSET=' . $CI->db->char_set . ';
+            ');
+        }
+    }
+}
+```
+
+### Modificar Coluna
+
+```php
+<?php
+
+defined('BASEPATH') or exit('No direct script access allowed');
+
+class Migration_Version_130 extends App_module_migration
+{
+    public function up()
+    {
+        $CI = &get_instance();
+
+        // Alterar tipo de coluna
+        $CI->db->query('ALTER TABLE `' . db_prefix() . 'meu_modulo`
+            MODIFY COLUMN `amount` DECIMAL(15,2) NOT NULL DEFAULT 0.00');
+    }
+}
+```
+
+### Adicionar Índice
+
+```php
+<?php
+
+defined('BASEPATH') or exit('No direct script access allowed');
+
+class Migration_Version_140 extends App_module_migration
+{
+    public function up()
+    {
+        $CI = &get_instance();
+
+        // Verificar se índice existe (evitar erro)
+        $indexes = $CI->db->query('SHOW INDEX FROM `' . db_prefix() . 'meu_modulo`
+            WHERE Key_name = "idx_status"')->result();
+
+        if (count($indexes) == 0) {
+            $CI->db->query('ALTER TABLE `' . db_prefix() . 'meu_modulo`
+                ADD INDEX `idx_status` (`status`)');
+        }
+    }
+}
+```
+
+### Migração de Dados
+
+```php
+<?php
+
+defined('BASEPATH') or exit('No direct script access allowed');
+
+class Migration_Version_150 extends App_module_migration
+{
+    public function up()
+    {
+        $CI = &get_instance();
+
+        // Migrar dados existentes