diff --git a/docs/STATUS_IMPLEMENTACAO.md b/docs/STATUS_IMPLEMENTACAO.md new file mode 100644 index 0000000..4256470 --- /dev/null +++ b/docs/STATUS_IMPLEMENTACAO.md @@ -0,0 +1,428 @@ +# Status de Implementação do Sistema de Controles + +> Gerado em: 2026-03-05 +> Baseado na análise do código-fonte e na demanda original. + +--- + +## Legenda de Status + +| Ícone | Significado | +|-------|-------------| +| ✅ | Implementado e funcional | +| ⚠️ | Parcialmente implementado | +| ❌ | Não implementado | + +--- + +## Resumo Geral + +| Requisito | Status | Progresso | +|-----------|--------|-----------| +| 1. Gerenciamento de Militantes | ⚠️ Parcial | 80% | +| 2. Gestão de Células e Setores | ⚠️ Parcial | 75% | +| 3. Registros de Depósitos | ⚠️ Parcial | 50% | +| 4. Cadastro de Objetivos | ❌ Não iniciado | 0% | +| 5. Relatórios Financeiros | ⚠️ Parcial | 40% | +| 6. Controle Hierárquico (RBAC) | ✅ Implementado | 90% | +| 7. Alterações de Responsáveis | ⚠️ Parcial | 60% | +| 8. Auditoria e Rastreabilidade | ❌ Não iniciado | 5% | +| 9. Segurança | ⚠️ Parcial | 70% | +| 10. Compatibilidade com Planilhas | ❌ Não iniciado | 0% | +| 11. Usabilidade / Responsividade | ⚠️ Parcial | 65% | +| 12. Carteirinha do Militante | ❌ Não iniciado | 0% | +| 13. Desacoplamento | ✅ Implementado | 90% | + +--- + +## Detalhamento por Requisito + +--- + +### 1. Gerenciamento de Militantes + +**Status: ⚠️ Parcial (80%)** + +| Funcionalidade | Status | Observações | +|----------------|--------|-------------| +| Cadastro de militantes | ✅ | Formulário completo com dados pessoais, profissionais, acadêmicos e sindicais | +| Edição de militantes | ✅ | Rota e modal de edição funcionais | +| Listagem de militantes | ✅ | Tabela com filtros e ordenação | +| Exclusão de militantes | ✅ | Com confirmação via modal | +| Níveis de permissão (8 níveis) | ✅ | RBAC hierárquico implementado com 8 níveis | +| Hierarquias de usuários | ✅ | Estrutura Célula → Setor → CR → CC | +| Status do militante (ativo, suspenso, etc.) | ✅ | 4 estados: ATIVO, DESLIGADO, SUSPENSO, AFASTADO | +| Status de Aspirante | ✅ | Período mínimo de 3 meses com avaliação obrigatória | +| Quadro-Orientador | ✅ | Responsabilidade especial implementada | +| Alterar nível do usuário | ✅ | Rota `/usuarios//alterar_nivel` | +| Avaliação do aspirante | ⚠️ | Modelo prevê, mas interface de avaliação pode estar incompleta | +| Histórico de avaliações | ⚠️ | Registro existe no modelo, verificar completude da UI | + +**O que falta:** +- Verificar se a interface de avaliação do aspirante está completa com todos os campos (participação, desenvolvimento político, pontos fortes, recomendações) + +--- + +### 2. Gestão de Células e Setores + +**Status: ⚠️ Parcial (75%)** + +| Funcionalidade | Status | Observações | +|----------------|--------|-------------| +| Cadastro de células | ✅ | Formulário e rotas funcionais | +| Cadastro de setores | ✅ | Formulário e rotas funcionais | +| Cadastro de CRs | ✅ | Comitês Regionais cadastráveis | +| Cadastro de CC | ✅ | Comitê Central cadastrável | +| Organização hierárquica | ✅ | Células → Setores → CRs → CC | +| Responsável geral da célula | ✅ | Campo `responsavel` no modelo | +| Responsável de finanças | ✅ | Adicionado via migration recente | +| Responsável de imprensa | ✅ | Adicionado via migration recente | +| Edição de células | ✅ | Template `editar_celula.html` existe | +| Edição de setores | ⚠️ | Template de edição de setor não foi confirmado | +| Listagem hierárquica visual | ⚠️ | Listagens existem, mas visualização em árvore pode estar incompleta | +| Atribuição de responsáveis via UI | ⚠️ | Funcionalidade adicionada no banco, verificar interface | + +**O que falta:** +- Confirmar que a UI de atribuição dos responsáveis de finanças e imprensa está completa +- Verificar se a edição de setores está implementada +- Adicionar visualização hierárquica em árvore (Célula → Setor → CR → CC) + +--- + +### 3. Registros de Depósitos + +**Status: ⚠️ Parcial (50%)** + +| Funcionalidade | Status | Observações | +|----------------|--------|-------------| +| Registro de cotas mensais | ✅ | Modelo `CotaMensal` com cálculo automático | +| Registro de pagamentos gerais | ✅ | Modelo `Pagamento` multi-tipo | +| Pagamento por PIX | ✅ | Modelo `TransacaoPIX` com QR code | +| Depósitos por célula | ✅ | Modelo `PagamentoCelula` | +| Depósitos por setor | ⚠️ | Rota existe, verificar completude do modelo | +| Depósitos por CR | ⚠️ | Rota existe, verificar completude do modelo | +| Valor, data e fonte do depósito | ✅ | Campos presentes nos modelos | +| Depósito vinculado a objetivo/material | ⚠️ | Parcialmente via `TipoMaterial`, mas sem `Objetivo` | +| Depósitos em eventos específicos | ❌ | Não há modelo de `Evento` com depósitos vinculados | +| Registro de coletas em plenárias | ❌ | Não implementado | +| Registro de coletas em formações | ❌ | Não implementado | +| Contribuintes permanentes (CF) | ⚠️ | Existe como tipo de pagamento, mas sem funcionalidade específica | + +**O que falta:** +- Criar modelo `Evento` (plenária, formação, célula) para vincular depósitos/coletas a eventos específicos +- Implementar registro de coletas por evento com informação de "para qual objetivo" +- Separar claramente o registro de contribuintes permanentes (CF) + +--- + +### 4. Cadastro de Objetivos + +**Status: ❌ Não implementado (0%)** + +| Funcionalidade | Status | Observações | +|----------------|--------|-------------| +| Modelo de Objetivos | ❌ | Não existe no banco de dados | +| Objetivos por militante | ❌ | Não implementado | +| Objetivos gerais por evento | ❌ | Não implementado | +| Objetivos de venda de materiais | ❌ | Não implementado | +| Objetivos de coleta em eventos | ❌ | Não implementado | +| Objetivos por nível (Nacional, Regional, Setor, Célula) | ❌ | Não implementado | +| Acompanhamento de progresso | ❌ | Não implementado | +| Interface de cadastro de objetivos | ❌ | Nenhum template existe | +| Relatório de atingimento de objetivos | ❌ | Não implementado | + +**O que falta (tudo):** +- Criar modelo `Objetivo` com campos: tipo_evento, instancia (Célula/Setor/CR/CC/Nacional), militante (opcional), valor_meta, data_evento +- Criar rotas CRUD para objetivos +- Criar interface para cadastro e acompanhamento +- Vincular depósitos/coletas a objetivos +- Criar relatório de progresso por objetivo + +--- + +### 5. Relatórios Financeiros + +**Status: ⚠️ Parcial (40%)** + +| Funcionalidade | Status | Observações | +|----------------|--------|-------------| +| Modelo de relatório de cotas | ✅ | `RelatorioCotasMensais` existe | +| Modelo de relatório de vendas | ✅ | `RelatorioVendasMateriais` existe | +| Template de criação de relatório | ✅ | Templates `novo_relatorio_*.html` existem | +| Template de listagem de relatórios | ✅ | Templates `listar_relatorios_*.html` existem | +| Lógica de geração de relatórios | ❌ | `functions/relatorio.py` está **vazio** | +| Relatório por célula | ❌ | Não implementado na lógica | +| Relatório por setor | ❌ | Não implementado na lógica | +| Relatório por CR | ❌ | Não implementado na lógica | +| Relatório por CC (nacional) | ❌ | Não implementado na lógica | +| Filtro por período | ⚠️ | Parcialmente nos templates | +| Cotas detalhadas | ⚠️ | Modelo existe, lógica de aggregação ausente | +| Contribuintes financeiros (CF) | ⚠️ | Tipo de pagamento existe, sem relatório específico | +| Contribuintes permanentes | ⚠️ | Sem segmentação clara nos relatórios | +| Coletas para eventos | ❌ | Depende do módulo de Eventos/Objetivos | +| Exportação (PDF/CSV/Excel) | ❌ | Não implementado | + +**O que falta:** +- **Prioridade máxima:** Implementar `functions/relatorio.py` com toda a lógica de aggregação de dados +- Criar queries de aggregação por nível hierárquico (célula, setor, CR, CC) +- Adicionar exportação em PDF e/ou CSV +- Criar relatórios consolidados com breakdown por categoria (cotas, CF, materiais, coletas) + +--- + +### 6. Controle Hierárquico (RBAC) + +**Status: ✅ Implementado (90%)** + +| Funcionalidade | Status | Observações | +|----------------|--------|-------------| +| 8 níveis de permissão | ✅ | De Militante Básico a Secretário Geral | +| Tabelas RBAC no banco | ✅ | `roles`, `permissions`, `role_permissions`, `user_roles` | +| Decorators de acesso | ✅ | `@require_login`, `@require_permission`, `@require_role`, etc. | +| Permissões por instância | ✅ | `@require_instance_permission`, `@require_instance_access` | +| Herança de permissões | ✅ | Nível superior herda permissões dos níveis abaixo | +| Filtragem de dados por hierarquia | ✅ | Queries filtradas por nível de acesso | +| Verificação de hierarquia entre usuários | ✅ | `user.is_higher_or_equal_than()` | +| Permissões de finanças e imprensa | ✅ | Roles específicos por instância | +| Testes de permissões | ✅ | `tests/test_permissions.py` existe | + +**O que falta:** +- Garantir que o RBAC cobre os novos módulos a serem criados (Objetivos, Eventos, Auditoria) + +--- + +### 7. Alterações de Responsáveis + +**Status: ⚠️ Parcial (60%)** + +| Funcionalidade | Status | Observações | +|----------------|--------|-------------| +| Alterar responsável de célula | ✅ | Campo `responsavel_id` editável | +| Alterar responsável financeiro | ✅ | Adicionado via migration | +| Alterar responsável de imprensa | ✅ | Adicionado via migration | +| Rota para alterar nível do usuário | ✅ | `/usuarios//alterar_nivel` | +| Registro histórico de mudanças | ❌ | Não há tabela de histórico de responsáveis | +| Interface de histórico | ❌ | Sem template para visualizar mudanças | +| Notificação ao alterar responsável | ❌ | Não implementado | + +**O que falta:** +- Criar modelo `HistoricoResponsavel` com: instancia_tipo, instancia_id, responsavel_anterior_id, responsavel_novo_id, tipo_responsabilidade, data_mudanca, alterado_por_id +- Criar interface para visualizar histórico de responsáveis por instância + +--- + +### 8. Auditoria e Rastreabilidade + +**Status: ❌ Não iniciado (5%)** + +| Funcionalidade | Status | Observações | +|----------------|--------|-------------| +| Log de sessões | ⚠️ | `last_activity` e `logout_reason` no modelo `Usuario` | +| Log de alterações | ❌ | Sem modelo de `AuditLog` | +| Rastrear quem fez o quê e quando | ❌ | Não implementado | +| Log de criação/edição/exclusão | ❌ | Não implementado | +| Log de alterações financeiras | ❌ | Não implementado | +| Interface de auditoria para admins | ❌ | Não implementado | +| Filtro por usuário, data, ação | ❌ | Não implementado | + +**O que falta (tudo):** +- Criar modelo `AuditLog` com: user_id, acao, modelo_afetado, registro_id, dados_anteriores (JSON), dados_novos (JSON), ip_address, timestamp +- Implementar hooks automáticos nos modelos SQLAlchemy (usando `event.listen`) para capturar INSERT, UPDATE, DELETE +- Criar interface de auditoria no painel admin +- Adicionar filtros por usuário, data, entidade + +--- + +### 9. Segurança + +**Status: ⚠️ Parcial (70%)** + +| Funcionalidade | Status | Observações | +|----------------|--------|-------------| +| Autenticação com usuário e senha | ✅ | bcrypt para hash de senha | +| OTP / 2FA (autenticação em dois fatores) | ✅ | pyotp + QR code implementados | +| Proteção CSRF | ✅ | Flask-WTF com tokens CSRF | +| Timeout de sessão | ✅ | 30 minutos configurável | +| Reset de OTP pelo admin | ✅ | Rota `/admin/users//reset-otp` | +| Reset de senha pelo admin | ✅ | Rota `/admin/users//reset-password` | +| Ativar/desativar usuários | ✅ | Toggle de status | +| Criptografia de dados sensíveis | ⚠️ | `cryptography` está nas dependências, uso não confirmado | +| HTTPS / TLS | ⚠️ | Dependente de configuração de produção (Nginx/gunicorn) | +| Validação de CPF | ✅ | `functions/validations.py` | +| Rate limiting (anti-brute force) | ❌ | Não implementado | +| Logs de tentativas de login | ❌ | Não implementado | + +**O que falta:** +- Implementar rate limiting nas rotas de login +- Garantir que dados financeiros sensíveis (valores, CPF) estejam criptografados no banco +- Documentar configuração de HTTPS para produção + +--- + +### 10. Compatibilidade com Planilhas dos CRs + +**Status: ❌ Não iniciado (0%)** + +| Funcionalidade | Status | Observações | +|----------------|--------|-------------| +| Importação de planilhas Excel | ❌ | Não implementado | +| Importação de planilhas CSV | ❌ | Não implementado | +| Exportação para Excel | ❌ | Não implementado | +| Exportação para CSV | ❌ | Não implementado | +| Mapeamento de colunas da planilha | ❌ | Não implementado | +| Validação de dados importados | ❌ | Não implementado | +| Interface de importação/exportação | ❌ | Nenhum template existe | + +**O que falta (tudo):** +- Adicionar biblioteca `openpyxl` ou `pandas` para leitura/escrita de Excel +- Criar rota de importação com preview e validação antes de confirmar +- Criar rota de exportação com filtros (por período, instância, tipo) +- Documentar o formato esperado das planilhas dos CRs + +--- + +### 11. Usabilidade e Responsividade + +**Status: ⚠️ Parcial (65%)** + +| Funcionalidade | Status | Observações | +|----------------|--------|-------------| +| Framework CSS responsivo | ✅ | Bootstrap via `Bootstrap-Flask` | +| Templates com layout responsivo | ✅ | `base.html` usa Bootstrap grid | +| Ordenação de tabelas | ✅ | `table_sort.js` implementado | +| Formulários com validação | ✅ | `forms.js` implementado | +| Modais para ações rápidas | ✅ | Modais para criar/editar/excluir militantes | +| Navegação por breadcrumb | ⚠️ | Verificar se está completo em todas as páginas | +| Otimização para mobile | ⚠️ | Bootstrap ajuda, mas tabelas complexas podem quebrar no mobile | +| Feedback visual de ações (toast/alert) | ⚠️ | Parcialmente implementado | +| Loading states | ⚠️ | Não confirmado | +| Suporte a múltiplos idiomas | ❌ | Sistema apenas em português (OK para o caso de uso) | + +**O que falta:** +- Revisar tabelas grandes para mobile (considerar scroll horizontal ou layout card) +- Garantir feedback visual (mensagens de sucesso/erro) em todas as ações +- Testar em dispositivos móveis reais + +--- + +### 12. Carteirinha do Militante + +**Status: ❌ Não iniciado (0%)** + +| Funcionalidade | Status | Observações | +|----------------|--------|-------------| +| Geração de imagem PNG | ❌ | `Pillow` está nas dependências, mas sem uso para carteirinha | +| Logo da organização na carteirinha | ❌ | Não implementado | +| Número de cadastro do militante | ❌ | Verificar se existe campo de número único | +| QR Code com chave de recuperação | ❌ | `qrcode` está nas dependências, mas sem uso para carteirinha | +| Download da carteirinha | ❌ | Não implementado | +| Geração automática no cadastro | ❌ | Não implementado | +| Template visual da carteirinha | ❌ | Não implementado | + +**O que falta (tudo):** +- Verificar/criar campo de número único de cadastro no modelo `Militante` +- Criar função em `functions/` para gerar o PNG usando Pillow: + - Fundo com template da organização + - Nome do militante + - Número de cadastro + - QR code com token de recuperação de senha +- Criar rota `/militantes//carteirinha` que gera e faz download do PNG +- Adicionar botão "Baixar Carteirinha" na tela de visualização do militante + +--- + +### 13. Desacoplamento + +**Status: ✅ Implementado (90%)** + +| Funcionalidade | Status | Observações | +|----------------|--------|-------------| +| Mínimo de frameworks | ✅ | Flask + SQLAlchemy + bibliotecas padrão | +| Sem dependência de cloud | ✅ | Roda localmente com SQLite | +| Containerização com Docker | ✅ | Dockerfile e docker-compose.yml presentes | +| Build automatizado | ✅ | Makefile para comandos comuns | +| Configuração via .env | ✅ | python-dotenv utilizado | +| Banco de dados portável | ✅ | SQLite sem necessidade de servidor externo | + +**O que falta:** +- Avaliar se `openpyxl/pandas` (para planilhas) adicionaria dependência pesada demais +- Documentar como compilar e rodar do zero no README + +--- + +## Backlog Priorizado + +### 🔴 Alta Prioridade (bloqueadores de uso em produção) + +| # | Tarefa | Requisito | Esforço | +|---|--------|-----------|---------| +| 1 | Implementar `functions/relatorio.py` com lógica de geração | Req. 5 | Alto | +| 2 | Criar módulo de Objetivos (modelo, rotas, templates) | Req. 4 | Alto | +| 3 | Criar módulo de Eventos com registro de coletas/depósitos | Req. 3 | Médio | +| 4 | Implementar Auditoria (AuditLog automático) | Req. 8 | Médio | + +### 🟡 Média Prioridade (funcionalidades importantes) + +| # | Tarefa | Requisito | Esforço | +|---|--------|-----------|---------| +| 5 | Histórico de mudança de responsáveis | Req. 7 | Baixo | +| 6 | Carteirinha do militante em PNG | Req. 12 | Médio | +| 7 | Exportação de relatórios para PDF/CSV | Req. 5 | Médio | +| 8 | Rate limiting no login | Req. 9 | Baixo | + +### 🟢 Baixa Prioridade (melhorias e integrações) + +| # | Tarefa | Requisito | Esforço | +|---|--------|-----------|---------| +| 9 | Importação/exportação de planilhas Excel | Req. 10 | Alto | +| 10 | Revisão de responsividade mobile | Req. 11 | Médio | +| 11 | Completar interface de avaliação do aspirante | Req. 1 | Baixo | +| 12 | Verificar e completar edição de setores | Req. 2 | Baixo | + +--- + +## Arquitetura de Arquivos — O que existe + +``` +controles/ +├── app.py ✅ 44 rotas implementadas +├── functions/ +│ ├── database.py ✅ 25+ modelos SQLAlchemy +│ ├── rbac.py ✅ Sistema RBAC completo +│ ├── permissions.py ✅ Funções de checagem de permissão +│ ├── decorators.py ✅ Decorators de autorização +│ ├── auth.py ✅ Utilitários de autenticação +│ ├── cota_calculator.py ✅ Cálculo automático de cotas +│ ├── validations.py ✅ Validação de CPF +│ └── relatorio.py ❌ ARQUIVO VAZIO — precisa ser implementado +├── routes/ +│ └── admin.py ✅ Rotas do painel admin +├── templates/ ✅ ~64 templates HTML +├── static/ +│ └── js/ ✅ 9 módulos JavaScript +├── tests/ ✅ Testes de permissão e rotas admin +└── docs/ ✅ Documentação RBAC e hierarquia +``` + +--- + +## Novos Arquivos a Criar + +| Arquivo | Propósito | +|---------|-----------| +| `functions/relatorio.py` | Lógica de geração de relatórios (já existe vazio) | +| `functions/audit.py` | Sistema de auditoria e log | +| `functions/carteirinha.py` | Geração de carteirinha em PNG | +| `routes/objetivos.py` | Blueprint para CRUD de objetivos | +| `routes/eventos.py` | Blueprint para CRUD de eventos/coletas | +| `routes/relatorios.py` | Blueprint para geração/download de relatórios | +| `templates/novo_objetivo.html` | Interface de cadastro de objetivo | +| `templates/listar_objetivos.html` | Listagem de objetivos | +| `templates/novo_evento.html` | Interface de cadastro de evento | +| `templates/listar_eventos.html` | Listagem de eventos | +| `templates/relatorio_consolidado.html` | Relatório financeiro consolidado | +| `templates/auditoria.html` | Interface de auditoria para admin | + +--- + +*Documento gerado automaticamente com base na análise do código-fonte em 2026-03-05.*