131 lines
5.2 KiB
Markdown
Executable File
131 lines
5.2 KiB
Markdown
Executable File
# 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.*
|