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

---
name: perfex-controllers
description: Controllers para módulos Perfex CRM — AdminController, ClientsController, routing e trait ValidatesContact. Baseado apenas na documentação oficial.
layer: wiki
---

# /perfex-controllers - Controllers Perfex CRM

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

---

## Documentação Base

- [Module Controllers](https://help.perfexcrm.com/module-controllers/)
- [CodeIgniter Controllers](https://codeigniter.com/userguide3/general/controllers.html)

---

## Estrutura de Pastas

```
modules/meu_modulo/
└── controllers/
    ├── Meu_modulo.php          # Controller principal
    ├── Admin_controller.php     # Controller admin adicional
    └── Client_controller.php    # Controller cliente
```

---

## Classes Base Disponíveis

| Classe | Uso | Validação Automática |
|--------|-----|----------------------|
| `AdminController` | Área admin/staff | Login staff obrigatório |
| `ClientsController` | Área cliente | Tema cliente aplicado |
| `App_Controller` | Base genérica | Nenhuma |

---

## AdminController (Área Admin)

Para funcionalidades exclusivas de staff/administradores.

### Template

```php
<?php

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

class Meu_modulo extends AdminController
{
    public function __construct()
    {
        parent::__construct();
        // Carregar models, helpers, etc.
        $this->load->model('meu_modulo/meu_modulo_model');
    }

    /**
     * Página principal do módulo
     * URL: /admin/meu_modulo ou /admin/meu_modulo/index
     */
    public function index()
    {
        // Verificar permissão
        if (!staff_can('view', 'meu_modulo')) {
            access_denied('meu_modulo');
        }

        // Preparar dados
        $data['items'] = $this->meu_modulo_model->get_all();
        $data['title'] = _l('meu_modulo_title');

        // Carregar view
        $this->load->view('meu_modulo/index', $data);
    }

    /**
     * Formulário de criação
     * URL: /admin/meu_modulo/create
     */
    public function create()
    {
        if (!staff_can('create', 'meu_modulo')) {
            access_denied('meu_modulo');
        }

        if ($this->input->post()) {
            // Processar formulário
            $data = $this->input->post();
            $id = $this->meu_modulo_model->add($data);

            if ($id) {
                set_alert('success', _l('added_successfully', _l('meu_modulo_item')));
                redirect(admin_url('meu_modulo'));
            }
        }

        $this->load->view('meu_modulo/form');
    }

    /**
     * Editar item
     * URL: /admin/meu_modulo/edit/123
     */
    public function edit($id)
    {
        if (!staff_can('edit', 'meu_modulo')) {
            access_denied('meu_modulo');
        }

        $data['item'] = $this->meu_modulo_model->get($id);

        if (!$data['item']) {
            show_404();
        }

        if ($this->input->post()) {
            $success = $this->meu_modulo_model->update($id, $this->input->post());

            if ($success) {
                set_alert('success', _l('updated_successfully', _l('meu_modulo_item')));
                redirect(admin_url('meu_modulo'));
            }
        }

        $this->load->view('meu_modulo/form', $data);
    }

    /**
     * Apagar item
     * URL: /admin/meu_modulo/delete/123
     */
    public function delete($id)
    {
        if (!staff_can('delete', 'meu_modulo')) {
            access_denied('meu_modulo');
        }

        if ($this->meu_modulo_model->delete($id)) {
            set_alert('success', _l('deleted', _l('meu_modulo_item')));
        }

        redirect(admin_url('meu_modulo'));
    }
}
```

---

## ClientsController (Área Cliente)

Para funcionalidades na área de clientes.

### Template

```php
<?php

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

class Meu_modulo extends ClientsController
{
    public function __construct()
    {
        parent::__construct();
        $this->load->model('meu_modulo/meu_modulo_model');
    }

    /**
     * Página principal cliente
     * URL: /meu_modulo ou /meu_modulo/index
     */
    public function index()
    {
        // Verificar se cliente logado
        if (!is_client_logged_in()) {
            redirect(site_url('authentication/login'));
        }

        $contact_id = get_contact_user_id();
        $client_id = get_client_user_id();

        $data = [
            'items' => $this->meu_modulo_model->get_by_client($client_id),
        ];

        // Métodos específicos de ClientsController
        $this->data($data);
        $this->title(_l('meu_modulo_title'));
        $this->view('meu_modulo/client_index');
        $this->layout();
    }

    /**
     * Ver detalhe
     * URL: /meu_modulo/view/123
     */
    public function view($id)
    {
        if (!is_client_logged_in()) {
            redirect(site_url('authentication/login'));
        }

        $item = $this->meu_mod