Gerenciamento de Usuários, Papéis e Permissões

O Projeto Base USP utiliza o pacote spatie/laravel-permission para fornecer um sistema flexível de controle de acesso baseado em papéis (Roles) e permissões (Permissions). Além disso, integra funcionalidades básicas de gerenciamento de usuários na área administrativa, incluindo a capacidade de criar usuários buscando dados do sistema Replicado da USP.

Estrutura de Papéis e Permissões

Conceitos

• Permissão (Permission): Define uma ação específica que um usuário pode ou não realizar (ex: 'editar artigo', 'ver relatórios financeiros', 'acessar área admin'). No contexto do Senha Única, também representa vínculos (ex: 'Docente', 'Alunogr') ou níveis hierárquicos ('admin', 'manager').
• Papel (Role): Um agrupamento de permissões. Atribuir um papel a um usuário concede a ele todas as permissões associadas àquele papel (ex: o papel 'Editor' pode ter as permissões 'criar artigo', 'editar artigo', 'publicar artigo').
• Guards: Mecanismos de autenticação. O spatie/laravel-permission permite associar papéis e permissões a guards específicos. No projeto base, usamos principalmente:
  • web: O guard padrão do Laravel para sessões web. Permissões e papéis específicos da sua aplicação devem usar este guard.
  • senhaunica: (Ou o nome definido em User::$vinculoNs e User::$hierarquiaNs) Usado internamente pelo pacote uspdev/senhaunica-socialite para gerenciar as permissões hierárquicas e de vínculo vindas da autenticação USP.

Papéis e Permissões Padrão

O seeder Database\Seeders\RolesAndPermissionsSeeder é executado durante a instalação (php artisan db:seed) e cria os seguintes itens essenciais:

• Papéis Padrão (Guard web):
  • admin: Para administradores do sistema.
  • usp_user: Atribuído automaticamente a usuários registrados como "Comunidade USP" ou criados via busca no Replicado.
  • external_user: Atribuído automaticamente a usuários registrados como "Externo".
  • Você pode adicionar outros papéis específicos da sua aplicação aqui ou em migrations/seeders próprios.
• Permissões Padrão (Guard senhaunica):
  • Hierárquicas: admin, boss, manager, poweruser, user (definidas em App\Models\User::$permissoesHierarquia).
  • Vínculo: Servidor, Docente, Estagiario, Alunogr, Alunopos, etc. (definidas em App\Models\User::$permissoesVinculo). Permissões mais específicas como Docente.ACL ou Alunogr.8 podem ser criadas dinamicamente durante o login/criação do usuário.

Importante: O pacote uspdev/senhaunica-socialite gerencia automaticamente a atribuição/sincronização das permissões do guard senhaunica durante o login via Senha Única. A área administrativa do projeto base foca no gerenciamento dos papéis e permissões do guard web.

Área Administrativa (/admin)

Uma seção dedicada para funcionalidades administrativas, acessível apenas para usuários com o papel admin.

• Acesso: Requer que o usuário esteja logado e possua o papel admin (atribuído manualmente ou via SENHAUNICA_ADMINS no .env). O item "Área Administrativa" aparecerá no menu principal para esses usuários.
• Dashboard Admin (/admin/dashboard): Página inicial da área administrativa, contendo links para as funcionalidades disponíveis.

Funcionalidades de Gerenciamento de Usuários

• Listar Usuários (/admin/users):
  • Controller: App\Http\Controllers\Admin\UserController::index()
  • View: resources/views/admin/users/index.blade.php
  • Descrição: Exibe uma tabela paginada com todos os usuários registrados no banco de dados local. As colunas incluem: ID, Nome, Email, Nº USP (CodPes, se houver), Papéis (do guard web), Status de Verificação de Email e Data de Criação. Fornece links para as ações de criação.
• Criar Usuário USP (via Replicado) (/admin/users/create/usp):
  • Controller: App\Http\Controllers\Admin\UserController::createUsp() (GET), storeUsp() (POST)
  • View: resources/views/admin/users/create_usp.blade.php
  • Descrição: Permite ao administrador criar um novo usuário buscando informações básicas diretamente do sistema Replicado da USP.
  • Fluxo:
    1. Admin insere o Número USP (CodPes) do usuário desejado.
    2. Ao submeter, o controller storeUsp() utiliza o pacote uspdev/replicado (Pessoa::fetch, Pessoa::email) para buscar o nome completo e o email principal do usuário no Replicado.
    3. Validações: Verifica se o Nº USP foi encontrado, se possui email principal e se o Nº USP ou email já não existem na tabela users.
    4. Se válido, cria um novo registro na tabela users com os dados obtidos.
    5. Atribui automaticamente o papel usp_user.
    6. Marca o email como verificado (email_verified_at preenchido), pois a fonte (Replicado) é confiável.
    7. Gera uma senha inicial aleatória segura.
    8. Redireciona para o dashboard admin com uma mensagem de sucesso exibindo a senha inicial gerada.
       • ATENÇÃO PRODUÇÃO: O método de informar a senha inicial (via flash message) NÃO é seguro para produção. Recomenda-se modificar este fluxo para enviar a senha via um canal seguro, forçar o usuário a redefinir a senha no primeiro login ou usar um fluxo de convite.
• Criar Usuário Manualmente (/admin/users/create/manual):
  • Controller: App\Http\Controllers\Admin\UserController::createManual() (GET), storeManual() (POST)
  • View: resources/views/admin/users/create_manual.blade.php
  • Descrição: Permite ao administrador criar um novo usuário (USP ou externo) fornecendo todas as informações manualmente.
  • Fluxo:
    1. Admin preenche: Nome Completo, Email, Senha, Confirmação de Senha.
    2. O campo Número USP (CodPes) é opcional.
    3. Ao submeter, o controller storeManual() valida os dados.
    4. Cria um novo registro na tabela users.
    5. Lógica de Papel e Verificação:
       • Se o Nº USP foi fornecido, o usuário recebe o papel usp_user e seu email é marcado como verificado (email_verified_at preenchido).
       • Se o Nº USP NÃO foi fornecido, o usuário recebe o papel external_user e seu email NÃO é verificado (email_verified_at permanece nulo), exigindo que o usuário passe pelo fluxo de verificação de email.
    6. Redireciona para o dashboard admin com uma mensagem de sucesso.
    7. Uma senha segura é sugerida na view para facilitar a criação.

Extensibilidade

O sistema spatie/laravel-permission é altamente extensível:

• Novos Papéis/Permissões: Podem ser criados programaticamente (ex: em Seeders ou Migrations) usando Role::create(['name' => 'nome_papel']) e Permission::create(['name' => 'nome_permissao']). Lembre-se de especificar o guard_name correto (web para sua aplicação).
• Atribuição: Use os métodos fornecidos pelo trait HasRoles no model User:
  • $user->assignRole('nome_papel');
  • $user->givePermissionTo('nome_permissao');
  • $user->syncRoles(['papel1', 'papel2']);
  • $user->syncPermissions(['permissao1', 'permissao2']);
• Verificação: Use as diretivas Blade (@role, @hasrole, @can) ou os métodos no model ($user->hasRole('...'), $user->can('...')).

Consulte a documentação oficial do Spatie Laravel Permission para mais detalhes sobre funcionalidades avançadas.