controles/docs/rbac.md

# Sistema de Permissões RBAC (Role-Based Access Control)

## Níveis de Permissão

O sistema de permissões é hierárquico, onde cada nível herda as permissões do nível anterior. A hierarquia é a seguinte (do menor para o maior nível):

### 1. Militante Básico
- Acesso apenas aos seus próprios dados
- Visualização de sua célula
- Sem permissões administrativas

### 2. Secretário de Célula
- Todas as permissões do Militante Básico
- Gerenciamento de militantes da sua célula
- Visualização de dados da célula
- Cadastro de novos militantes na célula

### 3. Membro de Setor
- Todas as permissões do Secretário de Célula
- Visualização de dados de todas as células do setor
- Acesso a relatórios do setor

### 4. Secretário de Setor
- Todas as permissões do Membro de Setor
- Gerenciamento de todas as células do setor
- Criação de novas células no setor
- Geração de relatórios do setor
- Gerenciamento de militantes do setor

### 5. Membro de CR (Comitê Regional)
- Todas as permissões do Secretário de Setor
- Visualização de dados de todos os setores do CR
- Acesso a relatórios do CR

### 6. Secretário de CR
- Todas as permissões do Membro de CR
- Gerenciamento de todos os setores do CR
- Criação de novos setores no CR
- Geração de relatórios do CR
- Gerenciamento de militantes do CR

### 7. Membro do CC (Comitê Central)
- Todas as permissões do Secretário de CR
- Visualização de dados de todos os CRs
- Acesso a relatórios nacionais

### 8. Secretário Geral / Secretário de Organização do CC
- Todas as permissões do Membro do CC
- Gerenciamento de todos os CRs
- Criação de novos CRs
- Geração de relatórios nacionais
- Gerenciamento de todos os militantes
- Configurações do sistema

## Implementação Técnica

O sistema RBAC é implementado através de:

1. **Roles**: Definem os níveis de acesso
2. **Permissions**: Definem as ações permitidas
3. **Role-Permission Mapping**: Mapeia quais permissões cada role possui
4. **User-Role Assignment**: Atribui roles aos usuários

### Estrutura do Banco de Dados

```sql
-- Roles
CREATE TABLE roles (
    id INTEGER PRIMARY KEY,
    nome VARCHAR(50) UNIQUE NOT NULL,
    nivel INTEGER NOT NULL,
    descricao TEXT
);

-- Permissions
CREATE TABLE permissions (
    id INTEGER PRIMARY KEY,
    nome VARCHAR(50) UNIQUE NOT NULL,
    descricao TEXT
);

-- Role-Permission Mapping
CREATE TABLE role_permissions (
    role_id INTEGER,
    permission_id INTEGER,
    PRIMARY KEY (role_id, permission_id),
    FOREIGN KEY (role_id) REFERENCES roles(id),
    FOREIGN KEY (permission_id) REFERENCES permissions(id)
);

-- User-Role Assignment
CREATE TABLE user_roles (
    user_id INTEGER,
    role_id INTEGER,
    PRIMARY KEY (user_id, role_id),
    FOREIGN KEY (user_id) REFERENCES users(id),
    FOREIGN KEY (role_id) REFERENCES roles(id)
);
```

## Exemplos de Permissões

### Permissões Básicas
- `view_own_data`: Visualizar seus próprios dados
- `edit_own_data`: Editar seus próprios dados
- `view_cell_data`: Visualizar dados da célula

### Permissões de Célula
- `manage_cell_members`: Gerenciar membros da célula
- `create_cell_member`: Criar novos membros na célula
- `view_cell_reports`: Visualizar relatórios da célula

### Permissões de Setor
- `manage_sector_cells`: Gerenciar células do setor
- `create_sector_cell`: Criar novas células no setor
- `view_sector_reports`: Visualizar relatórios do setor

### Permissões de CR
- `manage_cr_sectors`: Gerenciar setores do CR
- `create_cr_sector`: Criar novos setores no CR
- `view_cr_reports`: Visualizar relatórios do CR

### Permissões de CC
- `manage_cc_crs`: Gerenciar CRs
- `create_cc_cr`: Criar novos CRs
- `view_cc_reports`: Visualizar relatórios nacionais
- `system_config`: Configurar o sistema

## Uso no Código

```python
# Verificar permissão
if user.has_permission('manage_cell_members'):
    # Permitir ação

# Verificar nível
if user.has_role_level(3):  # Membro de Setor
    # Permitir ação

# Verificar hierarquia
if user.is_higher_or_equal_than(other_user):
    # Permitir ação
```

# Controle de Acesso Baseado em Funções (RBAC)

## Estrutura Hierárquica

O sistema possui uma estrutura hierárquica com os seguintes níveis:
- Célula (base)
- Setor (agrupa células)
- Comitê Regional - CR (agrupa setores)
- Comitê Central - CC (único, agrupa CRs)

## Regras de Associação

- Cada militante pertence a apenas uma célula
- Cada célula pertence a apenas um setor
- Cada setor pertence a apenas um CR
- Existe apenas um Comitê Central (CC)

## Permissões por Instância

### Célula
- **Secretário(a)**: 
  - `MANAGE_CELL_MEMBERS`: Gerenciar membros da célula
  - `VIEW_CELL_DATA`: Visualizar dados da célula
  - `VIEW_CELL_REPORTS`: Visualizar relatórios da célula
  - `REGISTER_CELL_PAYMENT`: Registrar pagamentos da célula

- **Tesoureiro(a)**:
  - `VIEW_CELL_DATA`: Visualizar dados da célula
  - `VIEW_CELL_REPORTS`: Visualizar relatórios da célula
  - `REGISTER_CELL_PAYMENT`: Registrar pagamentos da célula

- **Militante**:
  - `VIEW_OWN_DATA`: Visualizar apenas seus próprios dados

### Setor
- **Secretário(a)**:
  - `MANAGE_SECTOR_CELLS`: Gerenciar células do setor
  - `VIEW_SECTOR_REPORTS`: Visualizar relatórios do setor
  - `REGISTER_SECTOR_PAYMENT`: Registrar pagamentos do setor

- **Tesoureiro(a)**:
  - `VIEW_SECTOR_REPORTS`: Visualizar relatórios do setor
  - `REGISTER_SECTOR_PAYMENT`: Registrar pagamentos do setor

### CR
- **Secretário(a)**:
  - `MANAGE_CR_SECTORS`: Gerenciar setores do CR
  - `VIEW_CR_REPORTS`: Visualizar relatórios do CR
  - `REGISTER_CR_PAYMENT`: Registrar pagamentos do CR

- **Tesoureiro(a)**:
  - `VIEW_CR_REPORTS`: Visualizar relatórios do CR
  - `REGISTER_CR_PAYMENT`: Registrar pagamentos do CR

### CC
- **Secretário(a)**:
  - `MANAGE_CC_CRS`: Gerenciar CRs
  - `VIEW_CC_REPORTS`: Visualizar relatórios do CC
  - `REGISTER_CC_PAYMENT`: Registrar pagamentos do CC
  - `SYSTEM_CONFIG`: Configurar o sistema

- **Tesoureiro(a)**:
  - `VIEW_CC_REPORTS`: Visualizar relatórios do CC
  - `REGISTER_CC_PAYMENT`: Registrar pagamentos do CC

## Regras de Acesso a Dados

1. **Visualização de Dados**:
   - Militantes podem ver apenas seus próprios dados
   - Secretários e tesoureiros podem ver dados de sua instância
   - O CC tem acesso a todos os dados

2. **Registro de Pagamentos**:
   - Apenas tesoureiros e secretários podem registrar pagamentos
   - O registro é restrito à instância do usuário
   - O CC pode registrar pagamentos em qualquer nível

## Implementação Técnica

O controle de acesso é implementado através de:

1. **Decorators**:
   - `@require_login`: Verifica se o usuário está logado
   - `@require_permission`: Verifica se o usuário tem uma permissão específica
   - `@require_instance_permission`: Verifica permissão em uma instância específica
   - `@require_instance_access`: Verifica acesso a uma instância específica

2. **Verificações de Acesso**:
   - Cada rota verifica as permissões necessárias
   - O acesso é negado se o usuário não tiver as permissões requeridas
   - Mensagens de erro são exibidas para o usuário

3. **Filtragem de Dados**:
   - As consultas ao banco de dados são filtradas baseadas nas permissões
   - Cada nível hierárquico tem suas próprias regras de acesso