141 lines
4.8 KiB
Markdown
Executable File
141 lines
4.8 KiB
Markdown
Executable File
# Sistema de Módulos
|
|
|
|
O SysCMS é baseado em módulos independentes. Cada módulo deve ser autossuficiente e seguir uma estrutura rígida.
|
|
|
|
## Estrutura de um Módulo
|
|
Cada módulo reside em `modules/{nome_do_modulo}/` e contém:
|
|
|
|
- **module.json**: Arquivo de configuração (OBRIGATÓRIO).
|
|
- **classes/**: Código fonte (Controllers, Models, Services).
|
|
- **routes/**: Definições de rotas (`web.php`, `api.php`).
|
|
- **views/**: Templates Twig.
|
|
- **locales/**: Arquivos de tradução (i18n).
|
|
- **database/migrations/**: Migrações de banco de dados.
|
|
|
|
## O Arquivo `module.json`
|
|
Exemplo de estrutura obrigatória:
|
|
```json
|
|
{
|
|
"name": "blog",
|
|
"display_name": "Blog",
|
|
"description": "Sistema de blog",
|
|
"version": "1.0.0",
|
|
"author": "SysCMS Team",
|
|
"dependencies": ["users"],
|
|
"permissions": [
|
|
"blog.view", "blog.create", "blog.edit", "blog.delete"
|
|
],
|
|
"settings": {
|
|
"posts_per_page": 10
|
|
},
|
|
"providers": [
|
|
"Modules\\Blog\\Providers\\BlogServiceProvider"
|
|
],
|
|
"routes": {
|
|
"web": "routes/web.php",
|
|
"api": "routes/api.php"
|
|
},
|
|
"views": "views",
|
|
"locales": "locales",
|
|
"menu": {
|
|
"dashboard": {
|
|
"icon": "bi bi-journal-richtext",
|
|
"label": "Blog",
|
|
"route": "blog.index",
|
|
"order": 10
|
|
},
|
|
"public": {
|
|
"label": "Blog",
|
|
"route": "blog.public",
|
|
"order": 5
|
|
}
|
|
}
|
|
}
|
|
```
|
|
|
|
## Regras de Desenvolvimento de Módulos
|
|
|
|
### 1. Classes e Namespaces
|
|
- Namespace base: `Modules\{NomeDoModulo}\`
|
|
- Controllers: `Modules\{NomeDoModulo}\Controllers\`
|
|
- Models: `Modules\{NomeDoModulo}\Models\`
|
|
|
|
### 2. Views e Templates
|
|
- **Localização**: `/modules/{nome}/views/`
|
|
- **Extensão**: `.twig`
|
|
- **Estrutura**: Deve herdar de layouts base quando necessário (`{% extends "layouts/dashboard.twig" %}`).
|
|
- **Tradução**: NUNCA usar texto hardcoded. Usar `{{ __('modulo.chave') }}`.
|
|
|
|
### 3. Rotas
|
|
- Definidas em `routes/web.php` ou `routes/api.php`.
|
|
- Usar `$app->addRoute(...)`.
|
|
|
|
### 4. Internacionalização (i18n)
|
|
- Suporte obrigatório a 5 idiomas:
|
|
- `pt_BR` (Padrão)
|
|
- `en_US`
|
|
- `es_ES`
|
|
- `de_DE`
|
|
- `fr_FR`
|
|
- Arquivos JSON em `locales/{idioma}/{modulo}.json`.
|
|
|
|
### 5. Instalação e Migrações
|
|
- **Diretório**: `database/migrations/` dentro da pasta do módulo.
|
|
- **Estrutura**: Use classes PHP padrão que contenham métodos `up()` e `down()`.
|
|
- **Registro do Módulo**: É OBRIGATÓRIO incluir uma migração que registre o módulo na tabela `modules` e o associe às empresas existentes na tabela `bus_modules`.
|
|
- **Exemplo de Migração de Registro**:
|
|
```php
|
|
class InsertMeuModulo
|
|
{
|
|
public function up()
|
|
{
|
|
// Lógica para inserir na tabela 'modules' e 'bus_modules'
|
|
}
|
|
public function down()
|
|
{
|
|
// Lógica para remover o registro
|
|
}
|
|
}
|
|
```
|
|
- O sistema executará automaticamente essas migrações ao instalar ou atualizar o módulo.
|
|
|
|
### 6. Service Providers e Configuração Dinâmica
|
|
- **Objetivo**: Permitir que o módulo interaja com o core sem modificar arquivos do sistema (como `Application.php`).
|
|
- **Localização**: `classes/Providers/{NomeDoModulo}ServiceProvider.php`.
|
|
- **Registro**: Deve ser listado no `module.json` sob a chave `"providers"`.
|
|
- **Funcionalidades Permitidas**:
|
|
- Registrar rotas públicas dinamicamente (`$app->addPublicPath()`).
|
|
- Registrar middlewares globais ou protegidos (`$app->addGlobalMiddleware()`, `$app->addProtectedMiddleware()`).
|
|
- Injetar variáveis globais no Twig.
|
|
- **Exemplo**:
|
|
```php
|
|
namespace Modules\MeuModulo\Providers;
|
|
|
|
use Kernel\Application;
|
|
|
|
class MeuModuloServiceProvider
|
|
{
|
|
public function register() {}
|
|
|
|
public function boot()
|
|
{
|
|
$app = Application::getInstance();
|
|
|
|
// Registrar rota pública (sem autenticação)
|
|
$app->addPublicPath('/meu-modulo/publico');
|
|
$app->addPublicPath('/meu-modulo/assets/*'); // Suporta wildcard no final
|
|
|
|
// Registrar middleware
|
|
$app->addProtectedMiddleware(new \Modules\MeuModulo\Middleware\MeuMiddleware());
|
|
}
|
|
}
|
|
```
|
|
|
|
### 7. Registro Obrigatório de Recursos
|
|
- **Locales e Views**: É OBRIGATÓRIO registrar as chaves `"views": "views"` e `"locales": "locales"` no `module.json`. Sem isso, o sistema não carregará os arquivos de tradução nem as views do módulo, resultando em chaves de tradução (ex: `modulo.chave`) aparecendo na interface em vez do texto traduzido.
|
|
|
|
### 8. Proibições
|
|
- **NUNCA** modifique arquivos do diretório `kernel/` ou `app/` para instalar um módulo.
|
|
- **NUNCA** adicione hardcode de nomes de módulos no core.
|
|
- Tudo deve ser feito via **Service Providers** e **Hooks**.
|