README

Sistema de gestão de papéis e permissões (RBAC) para Laravel — construído para cobrir desde o pequeno negócio até ao grupo corporativo, com um módulo Premium de sugestão e otimização automática de permissões.

Feito com o contexto angolano em mente: suporte multi-empresa/filiais (grupos económicos), validação de NIF (AGT), e nomenclatura em português.

Índice

• Instalação
• Planos
• Uso básico
• Multi-empresa
• Middlewares e Blade
• Comandos Artisan
• Módulo Premium — Motor de Sugestão e Otimização
• Auditoria

Instalação

composer require jquembi/rule-manager

Publicar a configuração e correr as migrações:

php artisan vendor:publish --tag=rule-manager-config
php artisan migrate

Adicionar o trait ao seu model de utilizador:

use RuleManager\Traits\HasRoles;

class User extends Authenticatable
{
    use HasRoles;
}

Planos

O pacote funciona igual tecnicamente em qualquer plano — a diferença é apenas quais funcionalidades fazem sentido ativar em config/rule-manager.php:

// config/rule-manager.php
'plano' => env('RULE_MANAGER_PLANO', 'basico'),

Uso básico

use RuleManager\Models\Role;
use RuleManager\Models\Permission;

// Criar permissões
Permission::create(['nome' => 'Criar Faturas', 'modulo' => 'Financeiro']); // slug: criar.faturas

// Criar papel e atribuir permissões
$gestor = Role::create(['nome' => 'Gestor Financeiro']);
$gestor->darPermissao('criar.faturas', 'ver.faturas');

// Atribuir papel a um utilizador
$utilizador->atribuirPapel('gestor.financeiro');

// Verificar
$utilizador->temPermissao('criar.faturas'); // true
$utilizador->temPapel('gestor.financeiro');  // true

// Permissão pontual, sem papel (útil em negócios pequenos)
$utilizador->darPermissaoDireta('exportar.faturas');

Multi-empresa (corporativo)

Para grupos económicos com holding e filiais:

use RuleManager\Models\Empresa;

$holding = Empresa::create(['nome' => 'Grupo XYZ, Lda', 'nif' => '5417123456']);

$filial = Empresa::create([
    'nome' => 'XYZ Comercial, Lda',
    'nif' => '5417987654',
    'empresa_mae_id' => $holding->id,
    'provincia' => 'Luanda',
]);

// Papéis podem ser específicos de uma empresa/filial
$gestorFilial = Role::create(['nome' => 'Gestor de Loja', 'empresa_id' => $filial->id]);

Empresa::nifEhValido($nif) valida o formato do NIF (pessoa coletiva ou singular) segundo os padrões da AGT.

Middlewares e Blade

// routes/web.php
Route::middleware('permissao:faturas.criar')->group(function () {
    // ...
});

Route::middleware('papel:administrador|gestor.financeiro')->group(function () {
    // ...
});

@temPermissao('faturas.criar')
    <button>Nova Fatura</button>
@endtemPermissao

@temPapel('administrador')
    <a href="/admin">Painel de Administração</a>
@endtemPapel

Comandos Artisan

# Criar permissão
php artisan rule-manager:criar-permissao "Criar Faturas" --modulo=Financeiro

# Criar papel
php artisan rule-manager:criar-papel "Gestor Financeiro"

# Instalar um pacote padrão de papéis/permissões (Financeiro, RH, Vendas, Stock...)
php artisan rule-manager:instalar-padrao

Módulo Premium — Motor de Sugestão e Otimização

Ative no .env:

RULE_MANAGER_PLANO=premium

O motor (PermissionOptimizerService) analisa a matriz de papéis/permissões e o histórico de auditoria e devolve 5 tipos de sugestão:

1. Fusão de papéis — papéis com similaridade de Jaccard ≥ 80% (configurável) entre os seus conjuntos de permissões.
2. Agrupamento de permissões — permissões que aparecem quase sempre juntas nos papéis (co-ocorrência ≥ 90%).
3. Permissões concedidas e não usadas — cruza atribuições com o log de auditoria; sinaliza o que não foi exercido nos últimos N dias (princípio do menor privilégio).
4. Papéis órfãos — papéis sem nenhum utilizador atribuído.
5. Novos papéis sugeridos — agrupa utilizadores por assinatura real de permissões; se ≥ N utilizadores partilham exatamente o mesmo conjunto sem um papel único que os cubra, sugere consolidar num novo papel.

Via Artisan

php artisan rule-manager:otimizar
php artisan rule-manager:otimizar --json
php artisan rule-manager:otimizar --empresa=3

Via código (Facade ou injeção de dependência)

use RuleManager\Facades\RuleManager;

$relatorio = RuleManager::gerarRelatorioCompleto();

// ou apenas uma análise específica
$fusoes = RuleManager::sugerirFusaoDePapeis();

Exemplo de saída de sugerirFusaoDePapeis():

[
    [
        'papel_a' => 'gestor.financeiro',
        'papel_b' => 'contabilista.senior',
        'similaridade' => 0.86,
        'recomendacao' => 'Os papéis "Gestor Financeiro" e "Contabilista Sénior" partilham 86% das permissões. Considere fundi-los num único papel.',
    ],
]

Os limiares são ajustáveis em config/rule-manager.php → otimizacao.

Auditoria

Toda atribuição/revogação de papel e permissão, e toda verificação de acesso (temPermissao()), fica registada em permission_audit_logs. Esse histórico alimenta diretamente o item 3 do motor de otimização (permissões não usadas).

'auditoria' => [
    'ativo' => true,
    'reter_dias' => 365,
],

Licença

MIT.