First Commit

rules/20_CRIACAO_DE_NOVOS_MODULOS.md

@@ -0,0 +1,75 @@
+# 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.*