refactor: Implementa arquitetura MVC limpa
- Separa modelos em entidades individuais - Cria camada de serviços para acesso a dados - Implementa controladores para lógica de negócio - Organiza rotas em blueprints por funcionalidade - Adiciona documentação de arquitetura no README - Cria script para preparação da estrutura 🤖 Generated with [Claude Code](https://claude.ai/code) Co-Authored-By: Claude <noreply@anthropic.com>
This commit is contained in:
LS
184
README.md
184
README.md
@@ -1,134 +1,116 @@
|
||||
# Sistema de Controle de Militantes
|
||||
# Sistema de Controles
|
||||
|
||||
Sistema para gerenciamento de militantes, células, setores e comitês regionais.
|
||||
Sistema de gestão para controle de militantes, pagamentos, cotas e relatórios.
|
||||
|
||||
## Estrutura de Permissões (RBAC)
|
||||
## Arquitetura MVC
|
||||
|
||||
O sistema utiliza um sistema de controle de acesso baseado em papéis (RBAC) com a seguinte hierarquia:
|
||||
O projeto segue a arquitetura Model-View-Controller (MVC) para separação de responsabilidades:
|
||||
|
||||
### Níveis de Papéis
|
||||
### Models
|
||||
|
||||
1. **Militante Básico** (Nível 1)
|
||||
- Visualizar próprios dados
|
||||
- Editar próprios dados
|
||||
- Visualizar dados da célula
|
||||
Os modelos representam as entidades do sistema e estão organizados em:
|
||||
|
||||
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
|
||||
- **models/entities/**: Classes de entidades do banco de dados (SQLAlchemy)
|
||||
- `base.py`: Configuração do SQLAlchemy e classe Base
|
||||
- `usuario.py`: Modelo de usuário
|
||||
- `militante.py`: Modelo de militante
|
||||
- `cota_mensal.py`: Modelo de cota mensal
|
||||
- etc.
|
||||
|
||||
3. **Membro de Setor** (Nível 3)
|
||||
- Todas as permissões do Secretário de Célula
|
||||
- Visualizar relatórios do setor
|
||||
### Controllers
|
||||
|
||||
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
|
||||
Os controladores contêm a lógica de negócio e manipulam os dados dos modelos:
|
||||
|
||||
5. **Membro de CR** (Nível 5)
|
||||
- Todas as permissões do Secretário de Setor
|
||||
- Visualizar relatórios do CR
|
||||
- **controllers/**: Implementação dos controladores
|
||||
- `auth_controller.py`: Controle de autenticação
|
||||
- `usuario_controller.py`: Operações com usuários
|
||||
- `militante_controller.py`: Operações com militantes
|
||||
- `home_controller.py`: Controlador da página inicial
|
||||
- etc.
|
||||
|
||||
6. **Secretário de CR** (Nível 6)
|
||||
- Todas as permissões do Membro de CR
|
||||
- Gerenciar setores do CR
|
||||
- Criar setores no CR
|
||||
### Views
|
||||
|
||||
7. **Membro do CC** (Nível 7)
|
||||
- Todas as permissões do Secretário de CR
|
||||
- Visualizar relatórios nacionais
|
||||
As views são os templates que exibem os dados para o usuário:
|
||||
|
||||
8. **Secretário Geral** (Nível 8)
|
||||
- Todas as permissões do Membro do CC
|
||||
- Gerenciar CRs
|
||||
- Criar CRs
|
||||
- Configurar sistema
|
||||
- **templates/**: Templates Jinja2
|
||||
- Organizados por funcionalidade (admin, militantes, cotas, etc.)
|
||||
|
||||
### Services
|
||||
|
||||
Camada adicional para encapsular a lógica de acesso a dados:
|
||||
|
||||
- **services/**: Serviços para acesso a dados
|
||||
- `database_service.py`: Gerenciamento de conexões com o banco
|
||||
- `usuario_service.py`: Acesso a dados de usuários
|
||||
- `militante_service.py`: Acesso a dados de militantes
|
||||
- etc.
|
||||
|
||||
### Routes
|
||||
|
||||
Rotas da aplicação organizadas em blueprints:
|
||||
|
||||
- **routes/**: Módulos de rotas (Flask Blueprints)
|
||||
- `main.py`: Rotas principais
|
||||
- `auth.py`: Rotas de autenticação
|
||||
- `admin.py`: Rotas administrativas
|
||||
- `militante.py`: Rotas para gerenciamento de militantes
|
||||
- etc.
|
||||
|
||||
## 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
|
||||
1. Clone o repositório:
|
||||
```
|
||||
git clone [URL_DO_REPOSITORIO]
|
||||
```
|
||||
|
||||
2. Crie e ative um ambiente virtual:
|
||||
```
|
||||
python -m venv myenv
|
||||
source myenv/bin/activate # Linux/Mac
|
||||
myenv\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
|
||||
|
||||
4. Inicialize o banco de dados:
|
||||
```
|
||||
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
|
||||
python app.py --init
|
||||
```
|
||||
|
||||
## Uso
|
||||
5. Execute a aplicação:
|
||||
```
|
||||
python app.py
|
||||
```
|
||||
|
||||
### Decoradores de Permissão
|
||||
## Credenciais padrão
|
||||
|
||||
O sistema fornece três decoradores para controle de acesso:
|
||||
- **Administrador**:
|
||||
- Usuário: admin
|
||||
- Senha: admin123
|
||||
|
||||
1. `@require_permission(permission_name)`
|
||||
- Verifica se o usuário tem uma permissão específica
|
||||
- Exemplo: `@require_permission('create_cell_member')`
|
||||
## Desenvolvimento
|
||||
|
||||
2. `@require_role(role_name)`
|
||||
- Verifica se o usuário tem um papel específico
|
||||
- Exemplo: `@require_role('Secretário de Célula')`
|
||||
Para adicionar novos recursos, siga a arquitetura MVC:
|
||||
|
||||
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)`
|
||||
1. Crie modelos necessários em `models/entities/`
|
||||
2. Implemente serviços para acesso a dados em `services/`
|
||||
3. Crie controladores com lógica de negócio em `controllers/`
|
||||
4. Adicione rotas em módulos existentes ou crie novos em `routes/`
|
||||
5. Desenvolva templates em `templates/`
|
||||
|
||||
### Verificando Permissões no Código
|
||||
## Testes
|
||||
|
||||
```python
|
||||
# Verificar se um usuário tem uma permissão
|
||||
if user.has_permission('create_cell_member'):
|
||||
# Faça algo
|
||||
Execute os testes usando pytest:
|
||||
|
||||
# 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
|
||||
```
|
||||
python -m pytest
|
||||
```
|
||||
|
||||
## Estrutura do Banco de Dados
|
||||
Ou use o script de teste:
|
||||
|
||||
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
|
||||
```
|
||||
./run_tests.sh
|
||||
```
|
||||
Reference in New Issue
Block a user