File manager

File manager - Edit - /var/www/html/portalHomolog/.cursor/rules/rules.mdc

Back
--- alwaysApply: true --- # Padrões e Regras de Desenvolvimento do Projeto ## 🎨 Regras de FRONT-END 1. Arquitetura 100% Componentizada Todo o Front-End deve ser desenvolvido obrigatoriamente de forma componentizada, reutilizando os componentes existentes em resources/views/components. Caso não exista um componente adequado, deve ser criado um novo seguindo rigorosamente o padrão do projeto, visando reutilização futura. 2. Internacionalização (i18n) Obrigatória Todas as strings visuais devem ser internacionalizadas utilizando `{{ __('texto') }}`, sem exceções. 3. Identidade Visual e Estabilidade A identidade visual existente deve ser rigorosamente preservada, mantendo um aspecto clean e moderno. Refatorações estruturais não podem, em hipótese alguma, gerar alterações visuais, de layout ou de comportamento perceptível ao usuário final. 4. Framework UI Utilizar exclusivamente Bootstrap puro, explorando ao máximo seus recursos nativos. Nunca usar CSS personalizado para UI, apenas para comportamentos visuais que não forem contemplados pelo framework bootstrap. 5. Organização de Assets Arquivos CSS e JS devem ser separados por módulo/área em pastas coesas sob `public/` (ex.: `public/pmar/css` e `public/pmar/js` para o portal/admin principal; `public/mobiangra-assets/css`, `public/mobiangra-assets/js` e `public/mobiangra-assets/images` para o MobiAngra; demais eixos em `public/{nome-do-modulo}/`). É expressamente proibido o uso de CSS ou JS inline, seja diretamente nas linhas ou nas views Blade, bem como a mistura de códigos em arquivos desconexos. 6. Controle de Permissões na View A renderização de ações (botões, toggles, links) deve respeitar permissões finas via: `auth()->user()->getPermissaoDetalhes('<PERMISSAO_DO_MODULO>')`. Sem permissão, a ação não aparece. Obedeça os padrões atuais, onde é checado em todas as camadas sobre a respectiva permissão ao usuário, inclusive na View, onde os botões já tem um tratamento, como por exemplo: Passado em cima na view: @include('components.buttons._headLineButtonsBackAdd', [ 'headLine' => __($headLine), 'routeBack' => 'admin.contas.index', 'routeBackParams' => [], 'nameBack' => __("Voltar"), "permission" => "SYSADMIN", ]) Botão de Ação de Exemplo: @if (auth()->user()->getPermissaoDetalhes("SYSADMIN")['excluir']) <form class="d-inline" action="{{ route("admin.contas.destroy", $user->id) }}" method="post" onsubmit="return confirmDelete(this)"> @csrf @method('delete') @foreach($filterParams as $key => $value) @if($value) <input type="hidden" name="{{ $key }}" value="{{ $value }}"> @endif @endforeach <input type="hidden" name="confirm" value="{{ __('* Este usuário será excluído e esta ação não poderá ser desfeita, deseja continuar?') }}"> <button type="submit" class="btn btn-sm btn-danger" title="{{ __('Excluir') }}"> <i class="fa-solid fa-trash"></i> </button> </form> @endif 7. Componentes Padronizados Devem ser priorizados e reutilizados os componentes já existentes no projeto, incluindo, mas não se limitando a: * Headers e ações: components.buttons._headLineButtonsBackAdd * Tabelas: x-tables._table 8. Toggle de Status Só deve ser exibido se houver permissão de `editar`. Após alteração, a página deve ser recarregada para manter consistência visual sem perder qualquer filtragem que tenha sido feita na página. 9. Acessibilidade (A11y) Todo o Front-End deve seguir WCAG, com HTML semântico, ARIA adequado e contraste correto. 10. Persistência de Filtros e Buscas Sempre que houver campos de busca, filtros ou pesquisa, o valor informado deve ser persistido após qualquer operação (ex: editar, excluir, visualizar, salvar e retornar). O estado da pesquisa deve ser mantido. Então É proibido perder o contexto da busca ao retornar para a listagem. --- ## ⚙ Regras de BACK-END 0. Segurança como Base Permissões devem ser verificadas em múltiplas camadas. É proibido trafegar IDs ou parâmetros sensíveis via URL. 1. MVC Estrito e Organização por Módulo/Eixo Cada módulo deve estar totalmente organizado por eixo em todas as camadas (Model, Controller, Service, etc.), seguindo exatamente o padrão dos módulos existentes. 2. Um Arquivo por Camada por Módulo Cada módulo deve possuir um único arquivo por camada (Model, Service, Middleware, Request, Resource, Controller, Enums), evitando fragmentação funcional. 3. Permissão Única por Módulo Cada módulo possui uma única permissão principal, definida em Enum/Middleware/Kernel de permissões (ex.: `GERENCIADOR_DE_X`), distribuída em Visualizar, Adicionar, Editar e Excluir. 4. Middleware Obrigatório no Admin Todo módulo admin deve possuir middleware próprio. Comportamento padrão em falha de acesso: * Logout * Invalidação de sessão * Regeneração de token * Redirecionamento para `admin.login` com mensagem institucional 5. Controllers Magros e Disciplinados Controllers devem: * Apenas orquestrar fluxo * Aplicar `checkPermissao($permissao, 'visualizar\|adicionar\|editar\|excluir')` * Nunca conter lógica de persistência ou regras de negócio, servindo apenas para direcionar o fluxo dos sistemas. 6. Separação Clara de Responsabilidades a. Models Entidades, relacionamentos e regras estruturais de dados. b. Middleware Centralização e aplicação de permissões e acesso. c. Requests Validação, sanitização completas das entradas e retornos adequados ao usuário. d. Services Somente operações de persistência e CRUD. Sem lógica complexa. e. Resources Regras de Negócio, Lógicas avançadas, orquestrações e fluxos especiais do módulo. f. Controllers Coordenação entre camadas, sem lógica de negócio detalhada. 7. Validação e Sanitização Rigorosas Nenhuma entrada do usuário é confiável. Toda validação deve ocorrer antes de qualquer execução. 8. Banco de Dados e Performance * Usar eager loading * Evitar consultas em loop * Paginação obrigatória quando aplicável (se sim, exibir na view com padrão laravel existente) * Uso correto de índices 9. Transações Obrigatórias Operações críticas devem ser atômicas. 10. Tratamento de Exceções e Logs Exceções devem ser tratadas de forma padronizada, com logs internos claros e mensagens amigáveis ao usuário. 11. Documentação e Padronização Métodos públicos devem conter PHPDoc e seguir PSR-12. 12. Refatoração Estrutural Obrigatória Todo módulo que for refatorado deve ser integralmente alinhado às regras arquiteturais do projeto, mantendo: * Zero impacto visual * Zero mudança de comportamento * Melhoria exclusiva de arquitetura, organização, manutenibilidade e segurança. 13. Análise Proativa de Riscos Riscos técnicos, falhas de segurança ou inconsistências devem ser imediatamente reportados com proposta de correção. 14. Padronização e Redução de Migrations Deve-se minimizar a quantidade de migrations por módulo. Sempre que possível, consolidar estruturas relacionadas em uma única migration, evitando fragmentação excessiva. Princípios: - Uma migration por módulo quando viável - Evitar migrations pequenas e isoladas sem necessidade real - Priorizar coesão estrutural - Não comprometer clareza nem versionamento lógico do banco 15. Painel administrativo (`admin.painel`) e permissões em usuários (obrigatório ao criar módulo) Ao implementar qualquer novo módulo da área administrativa (nova permissão principal `GERENCIADOR_DE_`, `SYSADMIN` ou equivalente), a entrega não está completa* sem: * Cartão no painel principal: incluir o módulo no array `$todosModulos` em `resources/views/admin/dashboard.blade.php` (rota nomeada, ícone Font Awesome alinhado ao restante do painel, rótulo traduzível com `__()`, e o campo `permission` exatamente igual à constante da permissão principal usada no middleware/controller). Sem isso, o módulo não aparece em `/admin/painel` para quem tem a permissão. * Matriz de permissões na gestão de usuários: garantir que a permissão exista em `App\Enums\StatusPermission` com um `case` e rótulo em português; as telas `resources/views/admin/contas/create.blade.php` e `edit.blade.php` montam a tabela a partir dos `cases()` desse enum — toda permissão nova deve constar aí para o SysAdmin poder conceder visualizar/adicionar/editar/excluir ao cadastrar ou editar usuário. * Local correto do módulo administrativo: módulos administrativos não devem estar na área pública (ex.: `/conta-angra`); devem ser acessíveis e descobertos exclusivamente via painel administrativo (`/admin/painel`), seguindo o padrão institucional (dashboard + permissão). --- ## REGRAS DE SEGURANÇA Todas as regras abaixo são obrigatórias para qualquer novo código, refatoração ou correção. Cada regra é atômica, acionável e rastreável à classe de vulnerabilidade correspondente. ### Injeção (SQL/NoSQL/Comando) // mitiga: OWASP A03 - Injection 1. NUNCA concatenar valores vindos de usuário em `DB::raw()`, `whereRaw()`, `selectRaw()`, `orderByRaw()` ou SQL manual — SEMPRE usar bindings (`?` ou `:nome`) ou o query builder do Eloquent (`where`, `whereIn`, etc.). 2. NUNCA montar trechos de SQL com interpolação de strings (`\"... $variavel ...\"`) para filtros de busca, ordenação ou paginação — se precisar de SQL bruto, SEMPRE validar a lista de valores permitidos (whitelist) antes de usá-los. 3. NUNCA usar `exec()`, `shell_exec()`, `system()`, `passthru()`, `proc_open()` ou `popen()` em código HTTP; se for estritamente necessário em console commands, SEMPRE validar argumentos com whitelist de opções e caminhos e documentar o uso no relatório de segurança do módulo. 4. SEMPRE tratar dados de filtros numéricos (IDs, anos, limites) como tipos fortes (`int`, `float`) antes de usá-los em consultas — nunca confiar na string crua de `Request`. ### Autenticação e Sessão // mitiga: OWASP A07 - Identification and Authentication Failures 5. NUNCA implementar fluxo de login fora dos controllers/middlewares já existentes (`AuthenticationController`, middleware `auth`, `secretarias`, etc.) — novos mecanismos de autenticação devem reutilizar essas camadas. 6. SEMPRE usar `Auth::attempt()` / guard do Laravel para autenticação de usuários; é proibido validar senha “na mão” (comparando hash diretamente ou usando queries customizadas). 7. NUNCA armazenar senhas, tokens de sessão ou códigos de recuperação em texto puro no banco ou em logs — SEMPRE usar hashing forte (`bcrypt`/`password_hash`) e apagar tokens sensíveis assim que usados. 8. SEMPRE regenerar a sessão (`$request->session()->regenerate()`) após login bem-sucedido ou troca de senha, como já feito em `AuthenticationController`. ### Autorização e Controle de Acesso // mitiga: OWASP A01 - Broken Access Control 9. NUNCA expor funcionalidades administrativas (CRUDs, relatórios internos, dashboards) fora do contexto `/admin/` e sem o middleware de permissão específico do módulo. 10. SEMPRE* chamar `checkPermissao($permissao, 'visualizar\|adicionar\|editar\|excluir')` em todo Controller admin antes de acessar Services/Resources — controllers sem essa verificação são proibidos. 11. SEMPRE aplicar autorização também na camada de Service/Resource quando o método puder ser reutilizado por múltiplos controllers (defesa em profundidade). 12. NUNCA confiar apenas na view para esconder ações; qualquer botão/rota que dependa de permissão deve ser protegido no Controller, no middleware e (quando aplicável) em policies. ### Exposição de Dados Sensíveis // mitiga: OWASP A02 - Cryptographic Failures, A04 - Insecure Design 13. NUNCA retornar modelos Eloquent completos (`Model::all()`, `->get()`) diretamente em JSON para endpoints públicos — SEMPRE usar DTOs/Resources com `select` explícito dos campos permitidos. 14. SEMPRE filtrar entidades por `status = 'ATIVADO'` (ou equivalente) em endpoints de catálogo público (`secretarias_dados`, `telefones_dados`, etc.), evitando exposição de registros inativos/rascunho. 15. NUNCA logar dados sensíveis (senhas, tokens, CPF completo, e-mail + token) em `Log::info()`, `Log::error()` ou exceptions; truncar/anonimizar antes de registrar. 16. NUNCA trafegar IDs ou parâmetros sensíveis em query string pública quando puderem ser usados para enumeração ou associação de conta — SEMPRE usar UUIDs já padronizados ou identificadores opacos. ### Validação e Sanitização de Inputs // mitiga: OWASP A05 - Security Misconfiguration, A03 - Injection, A07 - XSS 17. SEMPRE usar `FormRequest` dedicada para qualquer formulário novo (publico ou admin), definindo regras em `rules()` e mensagens em `messages()` — validação diretamente no Controller (`$request->validate(...)`) só é aceita para casos triviais e internos. 18. NUNCA usar `{!! ... !!}` em Blade com conteúdo que venha de usuário/BD sem sanitização prévia — SEMPRE passar por `HtmlSanitizer::sanitize()` (ou helper específico) antes de renderizar HTML não escapado. 19. SEMPRE usar `e()`/`{{ }}` (escape automático) para textos, títulos, labels, mensagens e qualquer conteúdo que não precise ser HTML rico. 20. SEMPRE remover/normalizar atributos perigosos (`on`, `javascript:`, `data:` não-imagem) nos campos de texto rico, reutilizando `App\Helpers\HtmlSanitizer` ou Requests/Resources que já fazem essa limpeza. 21. NUNCA* decodificar entidades (`html_entity_decode`) e renderizar diretamente em `{!! !!}` — sempre sanitizar primeiro. ### Uploads e Arquivos // mitiga: OWASP A05 - Security Misconfiguration, A01 - Broken Access Control 22. SEMPRE seguir integralmente a seção `📎 Upload de Arquivos` abaixo para qualquer novo upload ou refatoração: armazenamento apenas em `storage/`, validação via `FileUploadHelper`, symlinks controlados e proibição absoluta de gravação em `public/`. 23. NUNCA aceitar extensões potencialmente executáveis (`php`, `phtml`, `phar`, `pht`, `inc`, `cgi`, `sh`, etc.), mesmo que o arquivo esteja indo para `storage/` — a blocklist de `FileUploadHelper` deve permanecer alinhada à configuração do Apache. ### Templates, Blade e PDFs // mitiga: OWASP A03 - Injection, A05 - Misconfiguration 24. NUNCA* usar `Blade::render()` com conteúdo editável em banco (páginas HTML, campos de texto rico, CMS) — somente é permitido compilar views estáticas do código-fonte. 25. SEMPRE manter `config/dompdf.php` com `'enable_php' => false` globalmente; o uso de `<script type=\"text/php\">` só é permitido em templates internos e deve ser ativado por render via `setOptions(['isPhpEnabled' => true])` em controllers específicos, sem dados HTML não confiáveis. ### HTTP, CSRF e Rate Limiting // mitiga: OWASP A06 - Vulnerable & Outdated Components, A05 - Misconfiguration 26. SEMPRE usar `@csrf` em formulários Blade que fazem `POST/PUT/PATCH/DELETE` e garantir que APIs web usem proteção CSRF adequada (ou `sanctum`/tokens dedicados quando forem stateless). 27. SEMPRE aplicar `throttle` em rotas públicas que aceitam `POST` ou consultas sensíveis (`throttle:web-public` ou política específica) para reduzir superfícies de força-bruta e scraping. 28. NUNCA desabilitar verificação SSL em requisições HTTP externas (`CURLOPT_SSL_VERIFYPEER/HOST = false`, `verify => false` no Guzzle) para código de produção; exceções só são aceitas em ambientes de teste e documentadas no relatório de segurança do módulo. ### Dependências e Ambiente // mitiga: OWASP A06 - Vulnerable and Outdated Components, A05 - Misconfiguration 29. SEMPRE rodar `composer audit` (ou ferramenta SCA equivalente) antes de releases importantes e tratar, no mínimo, vulnerabilidades Críticas e Altas das dependências (`laravel/framework`, bibliotecas PDF, bibliotecas de upload/parsing, etc.). 30. NUNCA versionar arquivos `.env`, chaves privadas, dumps de banco ou credenciais em qualquer pasta do repositório — variáveis sensíveis devem existir apenas em `.env` e nos secret managers da infraestrutura. 31. SEMPRE manter `APP_DEBUG=false` e `APP_ENV=production` em produção; qualquer teste com `APP_DEBUG=true` deve ser restrito a ambientes de desenvolvimento/homologação. 32. SEMPRE alinhar a configuração de segurança do Apache (vhosts) com as regras de aplicação (por exemplo, bloqueio de `.php`/`.phtml`/`.phar` em `public/` e `storage/`), documentando mudanças em `docs/cybersec/`. ### Logs, Monitoramento e Resposta a Incidentes // mitiga: OWASP A09 - Security Logging and Monitoring 33. SEMPRE registrar tentativas de violações de segurança detectadas pelos helpers (`FileUploadHelper::logSecurityViolation`, sanitizadores, validações de permissão) com contexto mínimo (IP, usuário autenticado, módulo afetado), sem incluir dados sensíveis. 34. SEMPRE criar/atualizar um relatório em `docs/cybersec/` ao corrigir falhas de segurança relevantes (como feito para o incidente do Boletim Oficial), descrevendo vetor, impacto, correção e regras derivadas. --- ## 📎 Upload de Arquivos Regras obrigatórias para qualquer funcionalidade nova ou refatorada que envolva upload, anexo ou persistência de arquivos enviados pelo usuário. Referência de implementação: `app/Helpers/FileUploadHelper.php`, `config/filesystems.php`, `deploy.sh` e relatórios em `docs/cybersec/`. ### 1. Armazenamento: storage + symlink (proibido gravar em `public/`) * É proibido persistir uploads com `$file->move(public_path(...))`, `file_put_contents` em `public/` ou qualquer escrita direta sob `public/` (exceto assets estáticos versionados no Git). * Obrigatório gravar no disco `public` do Laravel: `storage/app/public/{pasta-do-modulo}/`. * Obrigatório expor arquivos via link simbólico configurado em `config/filesystems.php` → chave `links`, recriado no deploy com `php artisan storage:link`. * Padrões já adotados no projeto: * Link genérico: `public/storage` → `storage/app/public` * Links por módulo em caminhos legados (ex.: `public/pmar/assets/files/atas`, `public/downloads/legislacoes-pdf`) * Ao criar pasta nova de upload: 1. Definir subpasta em `storage/app/public/{nome}/` 2. Registrar o symlink em `config/filesystems.php` (`links`) 3. Incluir `{nome}` no array `STORAGE_PUBLIC_DIRS` de `deploy.sh` 4. Se existir diretório físico legado em `public/`, implementar migração no `deploy.sh` (mover arquivos para o storage antes de recriar o symlink), como em `migrate_legislacao_pdf_legacy_directory()` * Em produção, `public/` permanece 755 (somente leitura para o PHP-FPM); escrita ocorre apenas em `storage/` (775) e `bootstrap/cache/`. ### 2. Validação de conteúdo com `FileUploadHelper` * É proibido confiar apenas em `mimes:`, `File::types()` ou extensão informada pelo cliente. * Obrigatório usar `App\Helpers\FileUploadHelper` antes de persistir: * Tipo único e bem definido (PDF, imagem): `FileUploadHelper::validateFile($file, $extensoes, $mimeTypes)` — valida extensão (whitelist), MIME real e magic bytes. * Whitelist ampla (Office, ZIP, anexos diversos): `FileUploadHelper::containsDangerousContent($file)` — bloqueia executáveis, polyglots e conteúdo `<?php` / `<?=` sem rejeitar documentos legítimos. * Métodos de conveniência quando aplicável: `processSafeImageUpload`, `processSafeDocumentUpload`, `processSafeGeneralUploadPublicDisk`, `processSafeDocumentUploadStorageLink`. * A blocklist `DANGEROUS_EXTENSIONS` do helper deve permanecer alinhada ao `public/.htaccess` (`.php`, `.phtml`, `.phar`, `.pht`, `.inc`, etc.). ### 3. Validação na Request e mensagens ao usuário * Regras Laravel na `FormRequest` do módulo: `file`, `mimes`/`mimetypes`, `max` (tamanho em KB). * Mensagens traduzíveis com `__()` no método `messages()` da Request. * Falhas de segurança ou persistência devem lançar `ValidationException` (retorno ao formulário), nunca exceção não tratada (HTTP 500). ### 4. Persistência e metadados no banco * Persistir no banco apenas o nome do arquivo ou caminho relativo ao disco (`atas/arquivo.pdf`, `legislacoes-pdf/nome.pdf`), nunca caminho absoluto nem nome original cru do usuário. * Usar `basename()` / helpers do Model para sanitizar nomes; rejeitar path traversal (`../`). * Nomes de arquivo gerados pelo sistema (`uniqid`, slug + sufixo aleatório) após validação — não reutilizar o nome original sem sanitização. * Exclusão/atualização: remover arquivo antigo somente após confirmação de sucesso do novo upload; suportar limpeza em storage e, se necessário, caminho legado físico pré-symlink. ### 5. URLs públicas e compatibilidade legada * URLs de download devem usar helpers/attributes do Model (ex.: `getPublicPdfUrlAttribute`), apontando para o caminho público servido pelo symlink, não para `storage/` diretamente. * Refatorações que migram de `public/` físico para storage devem preservar URLs já publicadas quando houver tráfego externo ou links indexados (symlink no mesmo segmento de URL ou redirecionamento documentado). ### 6. Segurança em camadas (defesa em profundidade) * Upload autenticado + permissão do módulo verificada em Controller/Service e middleware. * Apache: `public/.htaccess` bloqueia execução de scripts em subdiretórios (incluindo symlinks sob `public/`). * Registrar tentativas suspeitas: o helper já faz log em violações (`logSecurityViolation`); não silenciar falhas de validação. * Proibido servir upload com nome/extensão controlável pelo usuário que permita interpretação como script (`.php`, `.phtml`, dupla extensão `arquivo.php.pdf`). ### 7. Checklist obrigatório ao implementar upload em módulo novo 1. Pasta em `storage/app/public/{modulo}/` 2. Entrada em `config/filesystems.php` → `links` 3. Entrada em `deploy.sh` → `STORAGE_PUBLIC_DIRS` (+ migração legada se aplicável) 4. Validação via `FileUploadHelper` + `FormRequest` 5. Persistência via `Storage::disk('public')` (ou método seguro do helper) 6. Exclusão segura no Service 7. URL pública documentada no Model/Resource 8. Teste manual: arquivo válido aceito; arquivo com `<?php` ou extensão perigosa rejeitado 9. Verificar pós-deploy: symlink ativo (`readlink public/...`) e `storage/` gravável pelo PHP-FPM --- ## ✍ Comunicação e Tipografia 1. Travessões tipográficos proibidos Não utilizar travessões tipográficos (`—`, `–`, `―` e similares) em textos, comentários, labels, e-mails, views, mensagens ou documentação do projeto. Para separações textuais, usar sempre o hífen simples (`-`). Objetivo: manter padronização visual e evitar elementos de escrita frequentemente associados a textos gerados por I.A., preservando comunicação natural, consistente e alinhada ao padrão do projeto. --- ## 📝 Notas Finais * Sempre reutilize componentes existentes * Preserve integralmente a experiência do usuário * Segurança e permissões são inegociáveis * Código deve ser limpo, previsível e escalável * Todo módulo admin deve integrar permissões, middleware e dashboard conforme o padrão institucional * Novo módulo: checklist do item 15 (painel + `StatusPermission`) antes de considerar a tarefa encerrada * Upload de arquivos: checklist da seção Upload de Arquivos (item 7) antes de considerar a tarefa encerrada

| ver. 1.4 | Github | . | PHP 8.3.28 | Generation time: 0.02 | proxy | phpinfo | Settings