First Commit

rules/17_MODULE_TEMPLATE.md

@@ -0,0 +1,130 @@
+# 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.*