dockerfluxodecaixapro/rules/17_MODULE_TEMPLATE.md

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:

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.

{
    "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.

// 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.