controles/docs/README.md

# Sistema de Controles OCI

Sistema de gerenciamento para a Organização Comunista Internacionalista (OCI) com controle de militantes, cotas, pagamentos e materiais.

## 🚀 Status Atual

✅ **Sistema com Arquitetura de Permissões Corrigida**
- Aplicação Flask rodando com Docker
- Redis cache integrado e funcionando
- Banco de dados SQLite inicializado
- Usuário admin configurado com OTP
- 30 militantes de teste criados
- Estrutura organizacional completa
- **Sistema de permissões implementado no nível de dados**
- **Menus sempre visíveis, controle transparente**

## 🎯 Arquitetura de Permissões

O sistema implementa uma estratégia de controle de permissões no **nível de dados**, garantindo que:

- **Menus permanecem sempre visíveis** - Não há restrições na interface
- **Dados são filtrados por hierarquia** - Admin → CC → CR → Setor → Célula
- **Templates nunca quebram** - Sempre renderizam, mesmo com dados vazios
- **Tesoureiros têm poder adequado** - Podem fazer tudo que secretários fazem

### Diagrama da Arquitetura

```mermaid
graph TD
    A[User Request] --> B[Controller Layer]
    B --> C{Permission Check}
    C -->|Admin| D[All Data]
    C -->|CC| E[All Data]
    C -->|CR| F[CR Data Only]
    C -->|Setor| G[Setor Data Only]
    C -->|Célula| H[Célula Data Only]
    C -->|No Permission| I[Empty Data]
    
    D --> J[Template Rendering]
    E --> J
    F --> J
    G --> J
    H --> J
    I --> J
    
    J --> K[Always Renders Successfully]
```

## 🏗️ Arquitetura

O sistema foi refatorado seguindo o padrão MVC (Model-View-Controller):

```
controles/
├── app.py                    # Ponto de entrada da aplicação
├── controllers/              # Controladores (lógica de rotas)
├── models/                   # Modelos (operações de banco)
├── services/                 # Serviços (lógica de negócio)
├── templates/                # Views (templates HTML)
├── static/                   # Assets estáticos
└── functions/                # Funções utilitárias
```

## 🐳 Docker Setup

### Pré-requisitos
- Docker e Docker Compose instalados
- Porta 5000 disponível para a aplicação
- Porta 6379 disponível para Redis

### Inicialização Rápida

```bash
# Clonar o repositório
git clone <repository-url>
cd controles

# Iniciar o ambiente completo
make dev-up

# Verificar status
docker-compose ps

# Ver logs
make docker-logs
```

### Comandos Úteis

```bash
# Iniciar serviços
make dev-up

# Parar serviços
make dev-down

# Ver logs
make docker-logs

# Status do cache Redis
make cache-status

# Limpar cache
make cache-clear

# Reconstruir containers
make docker-build
```

## 🔐 Acesso ao Sistema

### Credenciais do Admin
- **URL**: http://localhost:5000
- **Usuário**: admin
- **Senha**: admin123
- **OTP Secret**: JBSWY3DPEHPK3PXP

### Configuração OTP
1. Instale um aplicativo autenticador (Google Authenticator, Microsoft Authenticator)
2. Configure manualmente:
   - Nome: admin
   - Segredo: JBSWY3DPEHPK3PXP
   - Tipo: TOTP
   - Algoritmo: SHA1
   - Dígitos: 6
   - Intervalo: 30 segundos

**OU** use o QR Code gerado em `/tmp/admin_qr.png` dentro do container.

## 📊 Funcionalidades

### Gestão de Militantes
- Cadastro completo com dados pessoais e profissionais
- Endereços e contatos
- Responsabilidades organizacionais
- Estados (Ativo, Desligado, Suspenso, Afastado)

### Gestão Financeira
- Cotas mensais
- Pagamentos diversos
- Vendas de materiais
- Assinaturas anuais

### Estrutura Organizacional
- Comitês Centrais
- Comitês Regionais
- Setores
- Células

### Relatórios
- Relatórios de cotas
- Relatórios de vendas
- Relatórios de pagamentos

## 🗄️ Banco de Dados

### Estrutura
- **SQLite** com SQLAlchemy ORM
- **Redis** para cache de performance
- Migrações automáticas
- Dados de teste incluídos

### Inicialização
O banco é inicializado automaticamente no primeiro startup com:
- 30 militantes de teste
- Estrutura organizacional completa
- Tipos de pagamento e materiais
- Usuário admin configurado

## 🔧 Tecnologias

- **Backend**: Flask 2.3.3
- **Frontend**: Bootstrap 5, HTML5, CSS3, JavaScript
- **Database**: SQLite + SQLAlchemy 2.0.21
- **Cache**: Redis 7.4.4
- **Authentication**: Flask-Login + OTP (pyotp)
- **Container**: Docker + Docker Compose
- **Server**: Gunicorn

## 📁 Estrutura de Arquivos

```
controles/
├── app.py                    # Aplicação principal
├── controllers/              # Controladores MVC
│   ├── auth_controller.py    # Autenticação
│   ├── home_controller.py    # Dashboard
│   ├── militante_controller.py # Militantes
│   ├── pagamento_controller.py # Pagamentos
│   ├── cota_controller.py    # Cotas
│   └── usuario_controller.py # Usuários
├── models/                   # Modelos de dados
├── services/                 # Serviços de negócio
├── templates/                # Templates HTML
├── static/                   # Assets estáticos
├── functions/                # Funções utilitárias
├── docs/                     # Documentação
├── docker-compose.yml        # Configuração Docker
├── Dockerfile               # Imagem Docker
└── requirements.txt         # Dependências Python
```

## 🚨 Problemas Resolvidos

### ✅ QR Code Admin
- **Problema**: Erro de permissão ao salvar QR code
- **Solução**: Múltiplos caminhos de fallback, salvamento em `/tmp/`

### ✅ Conexão Redis
- **Problema**: Falhas de conexão durante startup
- **Solução**: Retry logic com backoff exponencial

### ✅ Método OTP
- **Problema**: Método `generate_otp_secret` ausente
- **Solução**: Implementado na classe Usuario

### ✅ Rede Docker
- **Problema**: Serviços não se comunicavam
- **Solução**: Configuração explícita de redes

### ✅ Segredo OTP Inválido
- **Problema**: Segredo OTP não estava em formato base32 válido
- **Solução**: Alterado para `JBSWY3DPEHPK3PXP` (formato base32 válido)

### ✅ Verificação de Arquivo QR Code
- **Problema**: `PermissionError` ao verificar existência do arquivo
- **Solução**: Removida verificação de existência, implementado sistema de fallback

## 📈 Performance

### Cache Redis
- Dashboard statistics: 5 minutos
- Militante data: 30 minutos
- Pagamento data: 30 minutos
- API responses: Variável

### Monitoramento
```bash
# Status do cache
make cache-status

# Logs da aplicação
make docker-logs

# Logs do Redis
docker-compose logs redis
```

## 🔍 Troubleshooting

### Problemas Comuns

1. **Redis não conecta**
   ```bash
   docker-compose logs redis
   docker-compose restart redis
   ```

2. **Aplicação não inicia**
   ```bash
   docker-compose logs app
   docker-compose down && docker-compose up -d
   ```

3. **Cache não funciona**
   ```bash
   make cache-status
   make cache-clear
   ```

4. **Erro de OTP**
   ```bash
   # Verificar se o segredo está correto
   echo "JBSWY3DPEHPK3PXP" | base32 -d
   ```

5. **Erro de permissão QR Code**
   ```bash
   # O QR code agora salva em /tmp/admin_qr.png
   # Se não conseguir salvar, use configuração manual
   ```

### Logs
- Aplicação: `logs/controles.log`
- Cache: `logs/cache.log`
- Docker: `docker-compose logs`

## 📚 Documentação

- [Arquitetura MVC](docs/mvc_refactoring.md)
- [Sistema RBAC](docs/rbac.md)
- [Cache Redis](docs/redis_cache_setup.md)
- [Resumo da Arquitetura](docs/architecture_summary.md)

## 🤝 Contribuição

1. Fork o projeto
2. Crie uma branch para sua feature
3. Commit suas mudanças
4. Push para a branch
5. Abra um Pull Request

## 📄 Licença

Este projeto é privado para uso da OCI.

## 📞 Suporte

Para suporte técnico, entre em contato com a equipe de desenvolvimento.

## 📋 Recommended Next Steps

### High Priority
1. **Add Unit Tests**: Create comprehensive test coverage for models and services
2. **API Documentation**: Add OpenAPI/Swagger documentation
3. **Logging**: Implement structured logging throughout the application
4. **Configuration Management**: Centralize configuration management

### Medium Priority
1. **Repository Pattern**: Implement for better data access abstraction
2. **Caching**: Add Redis caching for frequently accessed data
3. **Background Jobs**: Implement Celery for background task processing
4. **Monitoring**: Add application monitoring and health checks

### Low Priority
1. **Event System**: Implement for decoupled component communication
2. **API Versioning**: Add support for multiple API versions
3. **GraphQL**: Consider GraphQL for more flexible data querying
4. **Microservices**: Evaluate splitting into microservices if needed

## 🔧 Correções de Permissões Recentes

### Problema Identificado
Durante a implementação inicial, foi descoberto que aplicar restrições no nível de template estava causando o desaparecimento dos menus administrativos.

### Solução Implementada
- **Controle movido para o nível de dados**: Filtragem acontece nos controllers
- **Templates simplificados**: `user_can()` sempre retorna `True`
- **Menus sempre visíveis**: Nenhuma restrição na interface
- **Degradação graceful**: Erros retornam dados vazios, nunca quebram

### Controllers Atualizados
- ✅ `militante_controller.py` - Filtragem hierárquica implementada
- ✅ `cota_controller.py` - Controle baseado em permissões
- ✅ `material_controller.py` - Acesso flexível por nível
- ✅ `pagamento_controller.py` - Filtragem organizacional

### Templates Corrigidos
- ✅ `listar_cotas.html` - URLs e referências corrigidas
- ✅ `listar_tipos_materiais.html` - Variáveis e campos ajustados
- ✅ `base.html` - Menus sempre visíveis

### Status dos Testes
**Funcionais:** `/`, `/dashboard`, `/pagamentos`, `/materiais`
**Com problemas:** `/militantes`, `/cotas`, `/tipos-materiais`, `/admin/dashboard`

Para detalhes completos, consulte: [docs/permission_fixes_summary.md](docs/permission_fixes_summary.md)

---

**Última atualização**: Julho 2025
**Versão**: 1.0.0
**Status**: ✅ Produção