# Sistema de Perfis de Acesso V2 (RBAC)

Este documento documenta o funcionamento técnico do sistema de Perfis de Acesso (RBAC) implementado no Core V2 e orienta como novos módulos devem consumi-lo e integrá-lo.

---

## 1. Visão Geral

O ecossistema V2 adota um modelo de **Controle de Acesso Baseado em Perfis (RBAC)** 100% isolado do sistema legado de permissões do Sentinel (V1). 

Em vez de salvar as permissões individuais de cada módulo diretamente no cadastro do usuário, o sistema adota a seguinte arquitetura:
1. Um **Perfil de Acesso** (`V2Role`) define os níveis de permissão (`none`, `read`, `write`) para cada módulo administrativo registrado no Core.
2. O **Usuário** apenas aponta para um perfil por meio da coluna `v2_role_id`.
3. O usuário herda automaticamente as permissões definidas no perfil associado.
4. Contas de **Suporte Técnico** (`suporte@maxima.inf.br`) e usuários com o papel **Super Admin** (`super-admin` no Sentinel V1) possuem acesso total implícito e ignoram as regras restritivas dos perfis.

---

## 2. Estrutura de Dados e Componentes

### Banco de Dados
- **Tabela `v2_roles`**: Mapeia os perfis de acesso da V2.
  - `id` (UUID): Identificador único gerado na aplicação.
  - `name` (String): Nome amigável do perfil (ex: *Financeiro*, *Redação*).
  - `slug` (String): Identificador único legível em formato kebab-case.
  - `permissions_v2` (JSONB): Matriz de permissões mapeando a chave do módulo para o seu nível de acesso.
- **Tabela `users`**: Coluna `v2_role_id` (UUID indexado, nulo por padrão) estabelecendo a relação física.

### Classes de Suporte
- **Model [V2Role](file:///home/devmaxima/projects/layout_lotep/app/V2/Core/Models/V2Role.php)**: Mapeamento Eloquent da tabela `v2_roles` com auto-geração de UUID no evento `creating` e soft-deletes ativos.
- **Serviço [PermissionService](file:///home/devmaxima/projects/layout_lotep/app/V2/Core/Services/PermissionService.php)**: Centraliza a resolução lógica de permissões, buscando do cache/relação do perfil V2, e expõe as APIs do CRUD de Perfis.
- **Middleware [V2PermissionMiddleware](file:///home/devmaxima/projects/layout_lotep/app/V2/Core/Middleware/V2PermissionMiddleware.php)**: Intercepta as rotas do CMS filtrando-as contra a matriz de permissões.
- **ViewComposer [SidebarComposer](file:///home/devmaxima/projects/layout_lotep/app/V2/Core/ViewComposers/SidebarComposer.php)**: Filtra os itens do menu lateral do CMS ocultando os módulos para os quais o usuário logado não possui acesso de leitura (`read` ou `write`).

---

## 3. Como Consumir as Permissões

O Core V2 expõe três mecanismos principais para verificar o acesso de operadores a um módulo:

### A. Em Arquivos Blade (Diretivas Customizadas)
Para ocultar ou exibir botões de ações, tabelas ou trechos da UI com base na permissão do operador:

```blade
{{-- Verifica se tem acesso de escrita (Write) no módulo Exemplo --}}
@v2can('Exemplo', 'write')
    <a href="{{ route('v2.exemplo.create') }}" class="btn btn-success">Cadastrar</a>
@endv2can

{{-- Verifica se tem pelo menos acesso de leitura (Read) no módulo Exemplo --}}
@v2can('Exemplo', 'read')
    <a href="{{ route('v2.exemplo.index') }}" class="btn btn-default">Visualizar</a>
@endv2can
```

### B. Em Código PHP (Helper Global)
Caso precise fazer checagens dentro de Controllers, Repositories ou Services:

```php
// Verifica permissão de leitura
if (\v2_can('Exemplo', 'read')) {
    // Código para exibir ou processar a visualização
}

// Verifica permissão de escrita (salvamento/exclusão)
if (\v2_can('Exemplo', 'write')) {
    // Código de persistência
}
```

---

## 4. Como os Módulos devem implementar (ou não)

### O que o Módulo DEVE fazer:

1. **Registrar o `active_pattern` no `ModuleProvider`**:
   Para que a interceptação e bloqueio de rotas ocorram de forma automática pelo middleware central do Core, todo módulo novo ou existente deve declarar o padrão de URLs de suas rotas administrativas no método `getConfig()` do seu `ModuleProvider` correspondente.
   
   *Exemplo:*
   ```php
   public function getConfig(): array
   {
       return [
           'title' => 'Gerenciador de Campanhas',
           'group' => 'CONTEÚDO',
           'icon' => 'fa fa-gift',
           'active_pattern' => 'cms/campanhas*', // Crucial para o middleware interceptar
           // ...
       ];
   }
   ```

2. **Proteger métodos de persistência nos Controllers**:
   O middleware central `V2PermissionMiddleware` faz a verificação automática baseada na URL:
   - Se a requisição for do tipo **GET**, ele valida acesso de leitura (`read`).
   - Se a requisição for do tipo **POST/PUT/DELETE**, ele valida acesso de escrita (`write`).
   
   Apesar dessa barreira automática na rota, boas práticas de segurança exigem que os controladores também verifiquem programaticamente se o usuário tem acesso de escrita em operações críticas de alteração de estado no banco de dados.

   *Exemplo:*
   ```php
   public function store(Request $request)
   {
       if (!\v2_can('Campanhas', 'write')) {
           abort(403, 'Ação não autorizada.');
       }
       // ...
   }
   ```

### O que o Módulo NÃO deve fazer:

1. **NÃO crie tabelas de permissões próprias**:
   O controle de acesso de todos os módulos administrativos da V2 deve ser centralizado nas tabelas e no `PermissionService` do Core. Criar tabelas adicionais gera retrabalho de interface administrativa e fragmentação do banco de dados.
   
2. **NÃO defina middlewares de controle de rotas redundantes**:
   Não há necessidade de registrar novos middlewares nas rotas do seu módulo para controlar acesso administrativo básico. O middleware `CmsAuthenticate` (encadeado ao `V2PermissionMiddleware`) já protege todas as rotas registradas sob o prefixo `cms/`.

3. **NÃO tente atribuir permissões diretamente ao usuário**:
   A coluna `permissions_v2` na tabela `users` foi depreciada em favor de `v2_roles.permissions_v2` e não deve ser preenchida de forma ad-hoc. Toda associação de privilégios de acesso deve obrigatoriamente se dar por meio de um Perfil de Acesso cadastrado.