- inits centralizados, READMEs atualizados

- padronizando o nome de get_db_connection e session para get_db_session, para não confundir com session do Flask ou sessoes web - corrigindo potenciais erros -- has_permission nao consegue com lazy load carregar permission depois de load_user fechar a conexao, entao joinedLoad com Permission antes de fechar -- db.rollback não existe caso db = get_db_session() apareça muito depois dentro do try, padronizando antes de try --- comparar role por nivel (Role.SECRETARIO_GERAL) e nao por nome ("Secretario Geral") - unificacao de get_otp_qr_code - mudança de nowutc() para now(UTC) conforme novo padrão
2026-02-20 17:19:15 -03:00
parent 6882b57081
commit 2b1668206d
38 changed files with 1250 additions and 1187 deletions
--- a/docs/README.md
+++ b/docs/README.md
@@ -2,26 +2,41 @@

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

-## 🚀 Status Atual
+## Trilha Recomendada de Leitura

-✅ **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**
+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`

-## 🎯 Arquitetura de Permissões
+## Índice por Tema

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

- **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
+- `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

@@ -46,87 +61,6 @@ graph TD
    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
@@ -152,80 +86,6 @@ make docker-build
 - 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
@@ -235,6 +95,7 @@ controles/
 - API responses: Variável

 ### Monitoramento
+
 ```bash
 # Status do cache
 make cache-status
@@ -246,68 +107,6 @@ make docker-logs
 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