🔐 Aprovação de Usuários¶
1. O que é este módulo?¶
O módulo de Aprovação de Usuários é o ponto de controle de acesso do Portal de Uploads. Ele permite que os administradores revisem e aprovem (ou reprovem) solicitações de novos usuários, além de gerenciar todos os acessos existentes — editar permissões, resetar senhas e desativar contas.
Quando uma pessoa se cadastra pela primeira vez no portal, ela fica com status "pendente" e não consegue acessar nenhum módulo até que um administrador revise e aprove sua solicitação. Esse controle garante que apenas pessoas autorizadas consigam enviar dados para o Datalake.
Quem pode acessar: Somente usuários com role admin. A proteção é feita via
@require_role(["admin"]), que bloqueia automaticamente qualquer tentativa de acesso por usuários não autorizados, inclusive por acesso direto via URL.
2. Telas Disponíveis¶
O módulo é organizado em duas abas principais:
📋 Aba 1 — Solicitações Pendentes¶
Exibe todas as solicitações de acesso que ainda não foram revisadas, apresentadas como cards individuais com as informações do solicitante (nome, e-mail, username, data da solicitação).
O que você pode fazer nesta aba:
| Ação | Descrição |
|---|---|
| ✅ Aprovar | Aceita a solicitação, seleciona a role (perfil de acesso) e cria automaticamente o usuário na base |
| ❌ Reprovar | Rejeita a solicitação e a move para o histórico |
Roles disponíveis para atribuição:
As roles determinam quais módulos o usuário poderá acessar. Exemplos comuns: admin, comercial, custo de reposição, controladoria. Ao aprovar, o administrador seleciona a role adequada em um dropdown.
👥 Aba 2 — Gestão de Usuários¶
Lista todos os usuários já cadastrados no portal, com funcionalidades de busca, edição e gerenciamento:
| Funcionalidade | Descrição |
|---|---|
| 🔍 Buscar | Pesquisa por nome, e-mail ou username. O sistema suporta busca parcial. |
| ✏️ Editar | Altera nome, e-mail, username, role e status (ativo/inativo) de qualquer usuário |
| 🔑 Resetar Senha | Força a redefinição de senha — zera o hash atual e marca must_change_password = TRUE, obrigando o usuário a criar uma nova senha no próximo login |
| 🗑️ Excluir | Remove permanentemente o registro do usuário da base |
| 📄 Paginação | Navegação entre páginas de resultados para facilitar a gestão de grandes volumes de usuários |
3. Como Usar — Passo a Passo¶
Aprovando uma solicitação¶
- Acesse o módulo "Aprovação de Usuários" no Dashboard principal
- Na aba "Solicitações Pendentes", visualize os cards com as solicitações aguardando revisão
- Para cada solicitação, revise os dados do usuário (nome, e-mail, username)
- Selecione a role (perfil de acesso) adequada no dropdown
- Clique em "Aprovar" — o sistema criará o usuário automaticamente
- Um e-mail de boas-vindas será enviado ao novo usuário (se o serviço de e-mail estiver disponível)
Reprovando uma solicitação¶
- Na aba "Solicitações Pendentes", localize a solicitação
- Clique em "Reprovar" — a solicitação será movida para o histórico com status
reprovado
Editando um usuário existente¶
- Vá para a aba "Gestão de Usuários"
- Use a barra de busca para localizar o usuário desejado
- Clique no botão de edição do card do usuário
- Altere os campos necessários (role, status ativo/inativo, etc.)
- Clique em "Salvar" para confirmar as alterações
4. Validações e Segurança¶
O módulo implementa diversas camadas de proteção para evitar inconsistências:
| Validação | Como funciona |
|---|---|
| Idempotência no MERGE | Ao aprovar, o sistema utiliza a instrução MERGE do BigQuery, que verifica se o username já existe antes de inserir. Isso significa que se o botão de aprovar for clicado duas vezes (por engano ou latência), não serão criados registros duplicados. |
| Proteção contra concorrência | A atualização de status (pendente → concluido) verifica quantas linhas foram afetadas (num_dml_affected_rows). Se outro administrador já processou a mesma solicitação, o sistema detecta e impede a operação duplicada. |
| Controle de interações em tempo real | O session_state rastreia quais solicitações já foram processadas durante a sessão atual, bloqueando interações com cards que já foram movidos para o histórico. |
| Fail-safe de notificação | O envio de e-mail de boas-vindas é protegido com try/except. Se o serviço de e-mail falhar, um alerta visual (st.warning) é exibido, mas a aprovação do usuário permanece válida — o acesso não é prejudicado. |
| Sanitização de inputs | Todos os parâmetros são passados via ScalarQueryParameter, prevenindo injeções de SQL e corrupção de tipos de dados. |
5. Dados e Integrações¶
Tabelas do BigQuery¶
| Camada | Tabela | Finalidade |
|---|---|---|
| Silver | solicitacoes_portal_upload |
Armazena todas as solicitações de acesso (pendentes, aprovadas, reprovadas) com metadados de controle |
| Silver | usuarios_portal_upload |
Cadastro ativo de todos os usuários do portal, com role, status e dados de autenticação |
Campos de Auditoria¶
Toda ação no módulo registra automaticamente:
decided_by— E-mail do administrador que tomou a decisãodecided_at— Data e hora exata da aprovação/reprovação (UTC)updated_at— Data e hora da última edição do registro
6. Monitoramento e Telemetria¶
O módulo integra ferramentas de analytics para acompanhar o uso:
- GA4 + Clarity: Heatmaps de interação, monitoramento de troca de abas e fluxo de navegação
- Decision Tracking: Rastreamento da taxa de conversão (Aprovação vs. Reprovação) para análise de demanda e volume de novos usuários
- Performance: Cada operação é monitorada via
get_tracker(), registrando tempo de execução e sucesso das queries
📅 Documentação atualizada em Março 2026.