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.*