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

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

# 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

# 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

# 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

   docker-compose logs redis
   docker-compose restart redis
   

2. Aplicação não inicia

   docker-compose logs app
   docker-compose down && docker-compose up -d
   

3. Cache não funciona

   make cache-status
   make cache-clear
   

4. Erro de OTP

   # Verificar se o segredo está correto
   echo "JBSWY3DPEHPK3PXP" | base32 -d
   

5. Erro de permissão QR Code

   # 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
• Sistema RBAC
• Cache Redis
• Resumo da Arquitetura

🤝 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

---

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