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

```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]
```

## 📊 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

```bash
# 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](docs/permission_fixes_summary.md)

---

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