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