Rule 20: Criação de Novos Módulos (Baseado no Sucesso do PhotoEssay)

Dica Proativa: Utilize o comando php syscli make:module [nome] para gerar automaticamente a estrutura base descrita abaixo.

Esta regra serve como guia definitivo para a IA coder criar novos módulos no SysCMS/Portal, utilizando o módulo PhotoEssay como padrão de ouro em estrutura, segurança, multi-idioma e integração com o core.

1. Estrutura de Diretórios Padronizada

Todo módulo deve seguir rigorosamente a estrutura abaixo:

modules/nome-do-modulo/
├── classes/
│   ├── Controllers/      # AdminController, UserController, PublicController
│   ├── Models/           # Models ORM
│   └── Providers/        # ServiceProvider para registro do módulo
├── database/
│   └── migrations/       # Scripts SQL de criação de tabelas e registro no sistema
├── locales/              # Traduções em 5 idiomas (pt_BR, en_US, es_ES, de_DE, fr_FR)
├── routes/
│   └── web.php           # Definição de rotas
├── views/                # Templates Twig separados por contexto (admin, user, public)
├── module.json           # Configuração de menus, permissões e metadados
└── modulo.zip            # Pacote compactado para instalação/atualização

2. Configuração do `module.json` e Menu

O module.json deve suportar múltiplos itens de menu para diferentes perfis.

dashboard: Itens visíveis para o usuário comum.
admin/ads/reports: Itens visíveis apenas para Admin/Super Admin.
Importante: O rótulo do menu deve usar chaves de tradução (ex: photoessay.menu.admin_essays).

Exemplo de estrutura de menu e registro de recursos:

"menu": {
    "dashboard": { "icon": "bi bi-camera", "label": "photoessay.menu.essays", "route": "user/photoessay", "permission": "photoessay.view" },
    "admin": { "icon": "bi bi-shield", "label": "photoessay.menu.admin_list", "route": "admin/photoessay", "permission": "photoessay.approve" }
},
"views": "views",
"locales": "locales"

3. Multi-Idioma (Locales)

Sempre implemente traduções nos 5 idiomas obrigatórios.

Registro de Locales: Certifique-se de que a chave "locales": "locales" existe no module.json para que as traduções sejam carregadas. Sem este registro, o sistema não encontrará os arquivos JSON e exibirá apenas as chaves (ex: modulo.chave).
Nunca deixe chaves faltando em um idioma que existam no outro.
O aviso de responsabilidade (show.disclaimer) deve usar o termo Portal em vez de SysCMS.

4. Segurança e Validação (Lições do PhotoEssay)

Verificação de Propriedade: Em rotas de edição ou exclusão (UserController), SEMPRE verifique se o recurso pertence ao usuário logado.
Try-Catch: Use blocos try-catch em operações de banco de dados e sistema de arquivos para retornar respostas JSON amigáveis em caso de erro.
Caminhos de Arquivos: NUNCA use ROOT_PATH para exclusão de arquivos se o ambiente for Windows/Docker instável. Use caminhos absolutos baseados em dirname(__DIR__, 4) para localizar a pasta storage/uploads/{nome-do-modulo}/.
- Exemplo Correto: $filePath = dirname(__DIR__, 4) . '/storage/uploads/photoessay/' . $image->path;
- NUNCA escreva diretamente na pasta public/. Use storage/uploads/{nome-do-modulo}/ e acesse via helper url().

5. Interface e Experiência do Usuário (UX)

Operações AJAX: Para exclusões de itens de galeria ou mudanças de status, utilize AJAX para evitar o recarregamento da página.
Feedback Visual: Implemente confirmações antes de excluir (confirm()) e remova o elemento do DOM imediatamente após o sucesso do AJAX.
Componentes UI: Utilize ícones Bootstrap (BI) e classes utilitárias para botões de ação (vermelho para excluir, azul para editar).

6. Integração com o Core

Se o módulo precisar de múltiplos links no sidebar, certifique-se de que o BaseAdminController.php no Core esteja configurado para iterar sobre todos os itens do array menu do módulo, ignorando apenas as chaves navbar e public.
O arquivo sidebar.twig deve renderizar o item.label diretamente para permitir que as traduções do módulo funcionem corretamente.

7. Migrations e Instalação

A migration 002_insert_... deve registrar o módulo na tabela modules, definindo o ícone, nome de exibição e ordem.
Garanta que as permissões necessárias sejam inseridas na tabela permissions e vinculadas aos papéis (roles) corretos.

8. Checklist de Finalização (Aprovação Perfeita)

As rotas de Admin estão protegidas por permissões?
As imagens/arquivos são excluídos fisicamente do disco ao deletar do banco?
O layout é responsivo e segue o padrão do Dashboard?
O arquivo .zip foi gerado contendo todas as alterações mais recentes?
O termo "SysCMS" foi substituído por "Portal" em textos de aviso?

Esta regra foi criada após a implementação bem-sucedida do módulo PhotoEssay, incorporando todas as correções de bugs de caminho, ajustes de tradução e melhorias de sidebar solicitadas pelo usuário.

5.2 KiB Executable File Raw Permalink Blame History