Requisitos do Projeto - ime-usp-br/laravel_11_starter_kit GitHub Wiki

Requisitos do Projeto

Este documento detalha os Requisitos Funcionais (RF - o que o sistema deve fazer) e os Requisitos Não Funcionais (RNF - as qualidades do sistema) ideais para o Projeto Base USP, concebido como um starter kit para aplicações Laravel 11 na Universidade de São Paulo.

A análise do status de implementação baseia-se nos arquivos de código-fonte, configurações e documentação.

Requisitos Funcionais (RF)

Descrevem as funcionalidades essenciais que o projeto base DEVE oferecer ou facilitar.

RF01: Autenticação e Autorização Integrada com Senha Única USP

  • RF01.1: Permitir a autenticação de usuários utilizando o sistema centralizado de Senha Única da USP. [Implementado]
    • Detalhes: Utiliza uspdev/senhaunica-socialite e rotas/controllers específicos (/socialite/login, /callback).
  • RF01.2: Implementar um sistema de gestão de papéis (roles) para definir diferentes níveis de acesso. [Implementado (Base)]
    • Detalhes: Utiliza spatie/laravel-permission. Papéis padrão (admin, usp_user, external_user) são criados via RolesAndPermissionsSeeder.
  • RF01.3: Possibilitar a associação de permissões específicas a cada papel. [Implementado (Base)]
    • Detalhes: Funcionalidade central do spatie/laravel-permission. Permissões Senha Única (hierarquia, vínculo) e permissões de aplicação (guard web).
  • RF01.4: Manter um registro de auditoria (log) das tentativas de autenticação (sucesso/falha). [Parcialmente Implementado (Requer Refinamento)]
    • Detalhes: Laravel dispara eventos de login/falha que podem ser logados, mas um log de auditoria específico e detalhado pode precisar de implementação adicional (ex: listener de eventos dedicado).
  • RF01.5: Oferecer mecanismos para proteger contra ataques de força bruta (throttling). [Implementado (Padrão Laravel)]
    • Detalhes: O LoginRequest padrão do Breeze/Laravel já inclui rate limiting.
  • RF01.6: Integrar um processo para garantir a identidade do sistema ao usuário durante a autenticação (prevenção de phishing). [Configuração de Ambiente/Servidor]
    • Detalhes: Geralmente assegurado por HTTPS (configuração do servidor) e validação do domínio/certificado, não diretamente no código base do framework.

RF02: Gerenciamento Básico de Usuários (Administrativo)

  • RF02.1: Fornecer uma interface administrativa básica para gestão de usuários. [Implementado (Base)]
    • Detalhes: Rotas /admin/users, /admin/users/create/*, controller AdminUserController e views correspondentes.
  • RF02.2: Integrar a funcionalidade de busca de usuários no sistema Replicado da USP. [Implementado]
    • Detalhes: O controller AdminUserController::storeUsp utiliza uspdev/replicado (Pessoa::fetch, Pessoa::email).
  • RF02.3: Permitir a atribuição e revogação de papéis e permissões (guard web) aos usuários via interface administrativa. [Implementado (Base)]
    • Detalhes: A interface de gerenciamento (/senhaunica-users, se usada a do pacote) permite associar papéis/permissões do guard web. A interface admin deste projeto base (/admin/users) foca na criação, a edição de papéis/perm precisaria ser adicionada ou usar a interface do uspdev/senhaunica-socialite. Sugestão: Adicionar edição de papéis/perm web em /admin/users.
  • RF02.4: Implementar o conceito de "menor privilégio" ao definir permissões para contas de serviço. [Diretriz / A Implementar]
    • Detalhes: O projeto base fornece a estrutura (Spatie), mas a aplicação deste princípio depende do desenvolvimento de cada aplicação derivada.
  • RF02.5: Manter um histórico de auditoria das ações administrativas (criação, edição, atribuição de papéis). [A Implementar (Detalhado)]
    • Detalhes: Similar ao RF01.4, requer logging específico além dos logs gerais do Laravel. Pacotes como spatie/laravel-activitylog podem ajudar.

RF03: Utilização do Tema Visual Padrão da USP

  • RF03.1: Incorporar o tema visual padrão da USP (laravel-usp-theme) como padrão. [Implementado]
    • Detalhes: Pacote incluído no composer.json, layout layouts/app.blade.php estende laravel-usp-theme::master.
  • RF03.2: Facilitar a customização do tema, mantendo a base visual. [Suportado (Pelo Tema)]
    • Detalhes: O laravel-usp-theme permite customizações via publicação de views e configuração. O uso de Tailwind neste projeto permite estilizações adicionais.

RF04: Configurações Essenciais da Aplicação

  • RF04.1: Centralizar configurações via arquivos .env e config/. [Implementado (Padrão Laravel)]
  • RF04.2: Permitir a configuração de serviços de e-mail (SMTP). [Implementado (Via Configuração)]
    • Detalhes: Arquivo config/mail.php e variáveis MAIL_* no .env.
  • RF04.3: Integrar suporte e configuração para sistemas de cache (Redis, Memcached, etc.). [Implementado (Via Configuração)]
    • Detalhes: Arquivo config/cache.php e variável CACHE_STORE. Drivers comuns do Laravel estão disponíveis.
  • RF04.4: Integrar suporte e configuração para sistemas de filas (BD, Redis, etc.). [Implementado (Via Configuração)]
    • Detalhes: Arquivo config/queue.php, variável QUEUE_CONNECTION e migrations para tabelas jobs/failed_jobs.
  • RF04.5: Incluir configurações padrão de segurança (ex: CSRF). [Implementado (Padrão Laravel)]
    • Detalhes: Middleware VerifyCsrfToken habilitado por padrão no grupo web.

RF05: Mecanismos de Segurança Fundamentais

  • RF05.1: Implementar validação de entrada de dados robusta no servidor. [Implementado (Via Form Requests)]
    • Detalhes: O projeto utiliza Form Requests em app/Http/Requests/ para validação.
  • RF05.2: Utilizar codificação de saída (output encoding) para prevenir XSS. [Implementado (Padrão Blade)]
    • Detalhes: A sintaxe {{ $variavel }} do Blade escapa dados por padrão.
  • RF05.3: Forçar o uso de HTTPS. [Configuração de Ambiente/Servidor]
    • Detalhes: Deve ser configurado no servidor web (Apache/Nginx) ou via middleware (TrustProxies e URL::forceScheme('https') no AppServiceProvider se atrás de proxy/load balancer). O projeto base não força por padrão no código.
  • RF05.4: Proteger informações sensíveis (senhas) com hashing seguro. [Implementado (Padrão Laravel)]
    • Detalhes: O model User padrão do Laravel já usa o cast hashed para o atributo password.
  • RF05.5: Implementar tratamento de erros seguro (sem exposição de detalhes em produção). [Implementado (Padrão Laravel)]
    • Detalhes: Controlado pela variável APP_DEBUG no .env.
  • RF05.6: Fornecer um sistema de logging abrangente. [Implementado (Base)]
    • Detalhes: Utiliza o Monolog via config/logging.php. Logging específico (auditoria) requer implementação adicional.
  • RF05.7: Incentivar o princípio de "nunca confiar nas entradas do usuário". [Diretriz]
    • Detalhes: É uma prática de desenvolvimento a ser seguida, não uma feature implementada per se, embora as validações (RF05.1) ajudem.

RF06: Suporte a Testes

  • RF06.1: Incluir estrutura básica para testes unitários. [Implementado (Estrutura + Exemplos)]
    • Detalhes: Diretório tests/Unit com ExampleTest.php e testes para Notifications/Seeders. Usa PHPUnit.
  • RF06.2: Incluir estrutura básica para testes de integração/feature. [Implementado (Estrutura + Exemplos)]
    • Detalhes: Diretório tests/Feature com testes para Auth, Profile, Admin, etc. Usa PHPUnit e RefreshDatabase.
  • RF06.3: Incluir estrutura básica para testes de navegador (Dusk). [Implementado (Estrutura + Exemplos)]
    • Detalhes: Diretório tests/Browser com testes para fluxos principais. DuskTestCase customizado.
  • RF06.4: Documentar configuração e execução dos testes. [Implementado (Base)]
    • Detalhes: README.md e Testes.md (gerado por você) explicam como rodar (php artisan test, php artisan dusk) e o ambiente .env.testing.

Requisitos Não Funcionais (RNF)

Descrevem as qualidades e restrições do sistema.

RNF01: Desempenho

  • RNF01.1: Aplicação base leve e com impacto mínimo. [Objetivo Arquitetural]
    • Detalhes: Laravel 11 é relativamente leve. A escolha de pacotes adicionais foi criteriosa. O desempenho final dependerá da aplicação construída sobre a base.
  • RNF01.2: Autenticação/Autorização eficientes. [Alcançado Parcialmente]
    • Detalhes: Fluxos padrão são eficientes. Cache de permissões do Spatie ajuda. A performance pode depender da latência da rede com Senha Única/Replicado. Otimizações de cache são configuráveis.

RNF02: Segurança

  • RNF02.1: Desenvolvimento seguindo melhores práticas de segurança. [Prática Contínua / Objetivo]
    • Detalhes: O projeto base implementa padrões Laravel (CSRF, hashing, escaping). Aderência a outras práticas (validação, autorização) é incentivada.
  • RNF02.2: Facilitar implementação de medidas de segurança adicionais. [Suportado (Estrutura)]
    • Detalhes: Estrutura Laravel e Spatie facilitam adicionar Gates, Policies, Middlewares de segurança.
  • RNF02.3: Incentivar Privacy by Design. [Diretriz]
    • Detalhes: O projeto base não implementa funcionalidades específicas de privacidade, mas sua estrutura permite incorporar esses princípios.

RNF03: Usabilidade

  • RNF03.1: Estrutura clara e organizada para desenvolvedores. [Suportado (Estrutura Laravel)]
    • Detalhes: Segue a estrutura padrão do Laravel 11.
  • RNF03.2: Interface administrativa intuitiva. [Implementado (Base)]
    • Detalhes: A interface admin fornecida é básica. Sugestão: Melhorar a UX/UI da área admin pode ser um objetivo futuro.

RNF04: Confiabilidade

  • RNF04.1: Código robusto e bem testado. [Alcançado Parcialmente]
    • Detalhes: O projeto base inclui testes para funcionalidades chave. A cobertura e robustez DEVEM ser mantidas e expandidas.
  • RNF04.2: Tratamento adequado de exceções. [Implementado (Padrão Laravel)]
    • Detalhes: Utiliza o Handler de Exceções do Laravel (app/Exceptions/Handler.php).

RNF05: Escalabilidade

  • RNF05.1: Arquitetura flexível sem limitações inerentes. [Objetivo Arquitetural]
    • Detalhes: A arquitetura Laravel é geralmente escalável. A escalabilidade dependerá das escolhas de implementação da aplicação derivada.
  • RNF05.2: Suporte a serviços externos escaláveis (cache, filas). [Implementado (Via Configuração)]
    • Detalhes: Suporta Redis, Memcached, SQS, etc., via configuração.

RNF06: Manutenabilidade

  • RNF06.1: Código bem documentado e seguindo padrões (PSR-12). [Suportado (Ferramentas) / Prática Contínua]
    • Detalhes: PSR-12 é o padrão. Laravel Pint está configurado. A documentação (como esta) é um esforço contínuo.
  • RNF06.2: Arquitetura modular (SRP, DRY). [Suportado (Estrutura Laravel) / Diretriz]
    • Detalhes: A estrutura do Laravel (MVC, Service Providers) incentiva a modularidade. Os princípios DEVEM ser aplicados durante o desenvolvimento. Boas práticas documentadas.
  • RNF06.3: Facilitar atualização/adição de funcionalidades ao projeto base. [Objetivo Arquitetural]
    • Detalhes: Depende da manutenção de baixo acoplamento e código limpo.
  • RNF06.4: Utilizar padrões de projeto comuns Laravel. [Suportado (Estrutura Laravel)]
    • Detalhes: O projeto utiliza MVC, Facades, Service Providers, Eloquent, etc.

RNF07: Portabilidade

  • RNF07.1: Compatível com diferentes ambientes USP. [Objetivo / Configuração]
    • Detalhes: Usa tecnologias padrão (PHP, MySQL/Postgres/SQLite). A compatibilidade depende da configuração correta do ambiente de destino.
  • RNF07.2: Minimizar dependências de infraestrutura específicas. [Objetivo Arquitetural]
    • Detalhes: Usa abstrações do Laravel (Filesystem, Cache, Queue) que permitem trocar drivers facilmente.

RNF08: Testabilidade

  • RNF08.1: Arquitetura projetada para facilitar testes automatizados. [Suportado (Estrutura Laravel)]
    • Detalhes: O uso de IoC Container, Facades (com Mocks), Eloquent (com DB in-memory) facilita os testes.
  • RNF08.2: Fornecer exemplos de testes unitários e de integração/feature/browser. [Implementado (Estrutura + Exemplos)]
    • Detalhes: Diretório tests/ contém exemplos.

RNF09: Conformidade

  • RNF09.1: Conformidade com políticas de segurança e privacidade USP. [Processo Externo / Diretriz]
    • Detalhes: O projeto base fornece ferramentas de segurança, mas a conformidade final depende da implementação específica e das políticas vigentes da USP.
  • RNF09.2: Utilizar componentes de terceiros confiáveis e licenciados. [Prática Contínua]
    • Detalhes: As dependências são gerenciadas via Composer/NPM. As licenças (principalmente MIT, algumas GPL) DEVEM ser verificadas periodicamente.

Esta documentação de requisitos estabelece uma base sólida, mas DEVE ser considerada um documento vivo, a ser revisado e atualizado conforme o Projeto Base USP evolui.