controles/README.md

# Sistema de Controle de Militantes

Sistema para gerenciamento de militantes, células, setores e comitês regionais.

## Estrutura de Permissões (RBAC)

O sistema utiliza um sistema de controle de acesso baseado em papéis (RBAC) com a seguinte hierarquia:

### Níveis de Papéis

1. **Militante Básico** (Nível 1)
   - Visualizar próprios dados
   - Editar próprios dados
   - Visualizar dados da célula

2. **Secretário de Célula** (Nível 2)
   - Todas as permissões do Militante Básico
   - Gerenciar membros da célula
   - Criar membros na célula
   - Visualizar relatórios da célula

3. **Membro de Setor** (Nível 3)
   - Todas as permissões do Secretário de Célula
   - Visualizar relatórios do setor

4. **Secretário de Setor** (Nível 4)
   - Todas as permissões do Membro de Setor
   - Gerenciar células do setor
   - Criar células no setor

5. **Membro de CR** (Nível 5)
   - Todas as permissões do Secretário de Setor
   - Visualizar relatórios do CR

6. **Secretário de CR** (Nível 6)
   - Todas as permissões do Membro de CR
   - Gerenciar setores do CR
   - Criar setores no CR

7. **Membro do CC** (Nível 7)
   - Todas as permissões do Secretário de CR
   - Visualizar relatórios nacionais

8. **Secretário Geral** (Nível 8)
   - Todas as permissões do Membro do CC
   - Gerenciar CRs
   - Criar CRs
   - Configurar sistema

## Instalação

1. Clone o repositório
2. Crie um ambiente virtual:
   ```bash
   python -m venv venv
   source venv/bin/activate  # Linux/Mac
   # ou
   venv\Scripts\activate  # Windows
   ```
3. Instale as dependências:
   ```bash
   pip install -r requirements.txt
   ```
4. Execute as migrações do banco de dados:
   ```bash
   python sql/migrate_db.py
   ```
5. Configure as variáveis de ambiente no arquivo `.env`:
   ```
   FLASK_APP=app.py
   FLASK_ENV=development
   SECRET_KEY=sua_chave_secreta
   MAIL_SERVER=seu_servidor_smtp
   MAIL_PORT=587
   MAIL_USE_TLS=True
   MAIL_USERNAME=seu_email
   MAIL_PASSWORD=sua_senha
   ```
6. Execute o aplicativo:
   ```bash
   flask run
   ```

## Uso

### Decoradores de Permissão

O sistema fornece três decoradores para controle de acesso:

1. `@require_permission(permission_name)`
   - Verifica se o usuário tem uma permissão específica
   - Exemplo: `@require_permission('create_cell_member')`

2. `@require_role(role_name)`
   - Verifica se o usuário tem um papel específico
   - Exemplo: `@require_role('Secretário de Célula')`

3. `@require_minimum_role(min_level)`
   - Verifica se o usuário tem um papel com nível mínimo
   - Exemplo: `@require_minimum_role(Role.SECRETARIO_CR)`

### Verificando Permissões no Código

```python
# Verificar se um usuário tem uma permissão
if user.has_permission('create_cell_member'):
    # Faça algo

# Verificar se um usuário tem um papel
if user.has_role('Secretário de Célula'):
    # Faça algo

# Obter o papel mais alto do usuário
highest_role = user.get_highest_role()
if highest_role and highest_role.nivel >= Role.SECRETARIO_CR:
    # Faça algo
```

## Estrutura do Banco de Dados

O sistema utiliza as seguintes tabelas para o RBAC:

- `roles`: Armazena os papéis disponíveis
- `permissions`: Armazena as permissões disponíveis
- `role_permissions`: Mapeia papéis para permissões
- `user_roles`: Mapeia usuários para papéis

## Segurança

- Todas as senhas são armazenadas com hash bcrypt
- Sessões expiram após período de inatividade
- Controle de acesso granular baseado em papéis
- Proteção contra CSRF
- Validação de entrada de dados