dockerfluxodecaixapro/rules/03_MODULOS.md

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:

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

  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:

  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.