76 lines
5.2 KiB
Markdown
Executable File
76 lines
5.2 KiB
Markdown
Executable File
# 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:
|
|
```text
|
|
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:
|
|
```json
|
|
"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)
|
|
1. [ ] As rotas de Admin estão protegidas por permissões?
|
|
2. [ ] As imagens/arquivos são excluídos fisicamente do disco ao deletar do banco?
|
|
3. [ ] O layout é responsivo e segue o padrão do Dashboard?
|
|
4. [ ] O arquivo `.zip` foi gerado contendo todas as alterações mais recentes?
|
|
5. [ ] 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.*
|