# 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**.