# Módulo Modelo para o SysCMS (Template)

Este documento define o padrão arquitetural para a criação de novos módulos no SysCMS, utilizando o módulo **`modelo`** como referência oficial e template instalável.

## Por que o módulo `modelo`?

O módulo `modelo` foi criado especificamente para servir de base limpa e padronizada para novos desenvolvimentos. Ele implementa:

1.  **Estrutura MVC Completa**: Controllers, Models e Views organizados.
2.  **Instalação Automatizada**: Inclui arquivo `.zip` pronto para teste de instalação via painel.
3.  **Independência**: Migrations autossuficientes que não quebram se outros módulos estiverem desativados.
4.  **Padrões de Código**: Namespace correto, rotas separadas (admin/public) e internacionalização.

O módulo encontra-se em `modules/modelo` e seu pacote de instalação em `modules/modelo/modelo.zip`.

---

## Estrutura de Diretórios

Um módulo padrão deve seguir rigorosamente a seguinte estrutura:

```text
modules/
└── [nome-do-modulo]/
    ├── module.json                 # Metadados e configurações principais
    ├── routes/
    │   └── web.php                 # Definição de rotas (Admin e Pública)
    ├── Providers/
    │   └── [Nome]ServiceProvider.php # Registro do módulo no container
    ├── classes/
    │   ├── Controllers/
    │   │   ├── [Nome]Controller.php  # Controller Admin (protegido)
    │   │   └── PublicController.php  # Controller Público (aberto)
    │   └── Models/
    │       └── [Nome].php            # Modelo Eloquent
    ├── database/
    │   └── migrations/             # Scripts de banco de dados
    │       ├── 001_create_[tabela]_table.php
    │       └── 002_insert_[modulo]_module.php
    ├── locales/                    # Arquivos de tradução
    │   ├── pt_BR/
    │   ├── en_US/
    │   └── [outros_idiomas]/
    └── views/                      # Templates Twig
        ├── admin/                  # Views do painel administrativo
        └── public/                 # Views do site público
```

---

## Componentes Essenciais

### 1. Configuração (`module.json`)
Arquivo JSON que define a identidade do módulo, suas permissões e dependências.

```json
{
    "name": "faq",
    "display_name": "FAQ Manager",
    "version": "1.1.0",
    "permissions": ["faq.view", "faq.manage"],
    "providers": ["Modules\\Faq\\Providers\\FaqServiceProvider"],
    "routes": {"web": "routes/web.php"},
    "views": "views",
    "locales": "locales",
    "module_public": true
}
```

### 2. Rotas (`routes/web.php`)
Separação clara entre rotas administrativas (protegidas) e públicas.

```php
// Rota Administrativa (Protegida por Middleware e Permissões no Controller)
$app->addRoute('GET', '/admin/faq', [\Modules\Faq\Controllers\FaqController::class, 'index']);

// Rota Pública
$app->addRoute('GET', '/faq', [\Modules\Faq\Controllers\PublicController::class, 'index']);
```

### 3. Service Provider (`Providers/FaqServiceProvider.php`)
Responsável por registrar as views, traduções e configurações do módulo no boot do sistema.

### 4. Controllers

*   **Admin (`FaqController.php`)**:
    *   Herda de `BaseAdminController`.
    *   Verifica permissões (`$user->hasPermission('faq.view')`).
    *   Gerencia CRUD (Create, Read, Update, Delete).
    *   Renderiza views admin (`@faq/admin/index.twig`).

*   **Público (`PublicController.php`)**:
    *   Herda de `BaseController`.
    *   Consulta dados públicos (`faqs_visibility = 'public'`).
    *   Renderiza views públicas (`@faq/public/index.twig`).

### 5. Migrations
*   **Criação da Tabela**: Define a estrutura de dados (ex: `faqs_id`, `faqs_question`, `faqs_bus_id`).
*   **Registro do Módulo**: Insere o registro na tabela `modules` para que o sistema reconheça o novo componente.

### 6. Views (Twig)
*   **Admin**: Estende `layouts/dashboard.twig`. Usa componentes Bootstrap e alertas do sistema.
*   **Público**: Estende `layouts/base.twig`. Foca na apresentação do conteúdo para o visitante.

---

## Guia para Criar um Novo Módulo

Para criar um novo módulo usando o `faq` como base:

1.  **Copie a pasta `modules/faq`** e renomeie para o novo nome (ex: `news`).
2.  **Edite o `module.json`**:
    *   Atualize `name`, `display_name` e `providers`.
    *   Defina as novas permissões (ex: `news.view`).
3.  **Renomeie e Refatore as Classes**:
    *   `FaqController` -> `NewsController`.
    *   `FaqServiceProvider` -> `NewsServiceProvider`.
    *   `Faq` (Model) -> `News`.
    *   Atualize os `namespace` em todos os arquivos PHP.
4.  **Atualize as Rotas**:
    *   Em `routes/web.php`, aponte para os novos controllers.
5.  **Ajuste as Migrations**:
    *   Renomeie os arquivos e as tabelas dentro deles.
6.  **Traduções**:
    *   Atualize os arquivos em `locales/` com as chaves do novo módulo.
7.  **Instalação**:
    *   O instalador de módulos detectará o novo `module.json` e executará as migrações automaticamente.

---
*Documento gerado para orientação de desenvolvimento no SysCMS.*