First Commit

rules/51_UPLOADS_STORAGE.md

@@ -0,0 +1,62 @@
+# 📁 Regra de Armazenamento de Arquivos e Uploads (51_UPLOADS_STORAGE.md)
+
+## ❗ Regra Fundamental
+**Nenhum módulo do SysCMS deve gravar arquivos diretamente no diretório `public/`.**
+
+Todos os uploads, arquivos gerados pelo sistema ou mídias de usuários devem ser obrigatoriamente armazenados no diretório `storage/uploads/{nome-do-modulo}/`.
+
+---
+
+## 🏗️ Estrutura de Armazenamento (Padrão Único e Definitivo)
+- **Localização Física**: `storage/uploads/{nome-do-modulo}/`
+- **URL de Acesso**: `url('storage/uploads/{nome-do-modulo}/' ~ nome_arquivo)`
+- **Funciona em**: Windows e Linux (Docker)
+- **OBRIGATÓRIO**: Subpastas por módulo (ex: `storage/uploads/erpcarriers/`, `storage/uploads/blog/`)
+- **PROIBIDO**: Uso de Links Simbólicos (Symlinks), Junctions ou Atalhos.
+- **Este padrão é definitivo e imutável** - NUNCA deve ser alterado
+---
+
+## 🌐 Acesso via Web
+Os arquivos em `storage/uploads/{nome-do-modulo}/` são acessíveis via rota do sistema.
+
+### Geração de URLs
+Para acessar um arquivo via navegador, utilize o helper `url()` apontando para `storage/uploads/{nome-do-modulo}/`:
+- **Correto**: `url('storage/uploads/blog/imagem.jpg')`
+- **Incorreto**: `url('public/uploads/imagem.jpg')`
+- **Incorreto**: `url('storage/imagem.jpg')` (sem módulo)
+
+---
+
+## 🛠️ Implementação no Código (PHP)
+
+### 1. Definindo o Diretório de Upload
+Sempre utilize caminhos absolutos baseados na raiz do projeto e inclua o nome do módulo:
+```php
+$moduleName = 'erpcarriers'; // Exemplo
+$uploadDir = dirname(__DIR__, 4) . '/storage/uploads/' . $moduleName . '/';
+if (!is_dir($uploadDir)) {
+    mkdir($uploadDir, 0755, true);
+}
+```
+
+### 2. Salvando o Caminho no Banco de Dados
+Grave apenas o nome do arquivo:
+- **BD**: `imagem.jpg`
+- **NÃO**: `blog/imagem.jpg` (redundante se a pasta for padrão)
+
+### 3. Exibindo no Frontend (Twig)
+```twig
+<img src="{{ url('storage/uploads/erpcarriers/' ~ registro.imagem) }}" alt="...">
+```
+
+---
+
+## 🛡️ Segurança e Manutenção
+1. **Proteção de Diretório**: O diretório `storage/` contém um arquivo `.htaccess` que impede a execução de scripts PHP, garantindo que arquivos maliciosos enviados por upload não sejam executados.
+2. **Limpeza**: Ao remover um registro que possui arquivos associados, o arquivo físico deve ser removido utilizando `unlink()`.
+3. **Nomes de Arquivos**: Use nomes únicos (ex: `TRA` + random_bytes + timestamp + extensão) para evitar conflitos.
+
+---
+
+## ⚠️ Importante
+Este padrão está definido como definitivo e imutável no [DECISIONS.md](../../DECISIONS.md). Em caso de dúvida, consulte sempre o DECISIONS.md antes de implementar funcionalidades de upload.