controles/docs/STATUS_IMPLEMENTACAO.md

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/<id>/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/<id>/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/<id>/reset-otp
Reset de senha pelo admin	✅	Rota /admin/users/<id>/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/<id>/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.