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.

Trilha Recomendada de Leitura

1. docs/architecture_summary.md
2. docs/rbac.md
3. docs/permission_strategy.md
4. docs/redis_cache_setup.md
5. docs/permission_fixes_summary.md

Índice por Tema

Arquitetura

• docs/architecture_summary.md: visão geral do estado da arquitetura.
• docs/mvc_refactoring.md: detalhes da refatoração MVC.

Permissões e Segurança de Acesso

• docs/rbac.md: níveis de papel e herança de permissões.
• docs/permission_strategy.md: estratégia de filtragem de dados e uso em templates.
• docs/permission_fixes_summary.md: resumo das correções aplicadas em permissões.

Infra e Performance

• docs/redis_cache_setup.md: configuração e uso de cache Redis.

Histórico Técnico

• docs/alteracoes_db_connection.md: alterações no gerenciamento de conexão/sessão de banco.

Como Manter Esta Pasta Organizada

• Preferir um arquivo por assunto (evitar documentos muito amplos).
• Começar cada documento com contexto, problema e decisão.
• Registrar trade-offs e impactos de manutenção.
• Atualizar este índice sempre que um novo documento for criado.

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]

📊 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

📈 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

📋 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