Fluxos de Acesso

Fluxos de Acesso

Passo a passo de cada fluxo de conta. Os conceitos de cargo, situação e permissões estão em Usuários, Cargos e Permissões.

As regras de cada fluxo ficam nos casos de uso de src/application/usecases/ e são expostas pelo AuthContext:

Caso de uso	Fluxo
SolicitarCadastroUseCase	Cadastro público
DecidirCadastroUseCase	Aprovação ou rejeição de cadastro
SolicitarAlteracaoCargoUseCase	Pedido de alteração de cargo
DecidirSolicitacaoCargoUseCase	Decisão sobre o pedido de cargo
CriarContaAdministrativaUseCase	Conta criada pela Administração
ConcluirTrocaSenhaUseCase	Troca obrigatória de senha

Tela de Administração

/administracao, somente para a Administração. As abas:

Aba	Rota	Conteúdo
Cadastros pendentes	/administracao/cadastros	Convidados aguardando decisão e as 10 decisões mais recentes
Solicitações de cargo	/administracao/cargos	Pedidos pendentes e histórico de decisões
Usuários	/administracao/usuarios	Contas: criar, alterar cargo, bloquear, gerar nova senha e excluir
Histórico de ações	/administracao/logs	Auditoria (ver Logs e Auditoria)

Sem aba na URL, a tela abre onde há pendências: cadastros primeiro, depois cargos e, por fim, usuários. O menu Administração e o sino mostram quantas pendências existem.

1. Cadastro público e aprovação

sequenceDiagram
  actor V as Visitante
  participant App
  participant Auth as Firebase Auth
  participant FS as Firestore
  actor A as Administração
  V->>App: Cadastre-se (nome, e-mail, senha)
  App->>Auth: createUserWithEmailAndPassword
  App->>FS: users/{uid} = convidado, ativo false, pendente
  App->>FS: notificação conta_nova para cada admin ativo
  App->>FS: log "cadastro"
  App-->>V: Tela "Cadastro em análise"
  A->>App: Administração → Cadastros pendentes → escolhe o cargo → Aprovar
  App->>FS: perfil = cargo, ativo true, statusAprovacao aprovado
  App->>FS: notificação conta_decidida + log "aprovacao_usuario"
  FS-->>App: perfil atualizado em tempo real
  App-->>V: Sistema liberado com o cargo definido

Loading

1. O formulário público não tem campo de cargo. A conta sempre nasce como convidado, ativo: false, statusAprovacao: 'pendente'. As regras recusam qualquer outro formato de autocadastro.
2. Cada administrador ativo recebe a notificação "Novo cadastro aguardando aprovação".
3. A sessão continua aberta, mas só mostra a tela Cadastro em análise. As regras negam a leitura de qualquer dado.
4. Na aba Cadastros pendentes, a Administração:
   • aprova, escolhendo o cargo (obrigatório): a conta passa a ativo: true e aprovado, e o sistema é liberado em tempo real;
   • rejeita, com motivo opcional: a conta fica rejeitado e inativa, e o registro é mantido. O próximo login é recusado exibindo o motivo, e a mesma conta não consegue se cadastrar de novo.
5. O solicitante recebe conta_decidida, e a notificação conta_nova de quem decidiu é marcada como resolvida.

Se o cadastro falhar depois de criar a conta no Auth, a conta de autenticação é apagada. Assim o e-mail pode ser usado de novo.

Conta de autenticação sem perfil: quem entra com uma conta do Auth sem documento em users (criada no Console ou com o perfil excluído) é tratado como um novo cadastro. A conta vira Convidado pendente, e a Administração é notificada.

2. Alteração de cargo pelo próprio usuário

sequenceDiagram
  actor U as Usuário
  participant App
  participant FS as Firestore
  actor A as Administração
  U->>App: Menu do perfil → Solicitar alteração de cargo
  App->>FS: lote: solicitacoes_cargo/{id} (pendente) + pendencias_cargo/{uid}
  App->>FS: notificação cargo_solicitado para cada admin + log "solicitacao_cargo"
  A->>App: Administração → Solicitações de cargo → Aprovar ou Rejeitar
  alt aprovada
    App->>FS: lote: solicitação aprovada + users/{uid}.perfil = solicitado + remove a trava
  else rejeitada
    App->>FS: lote: solicitação rejeitada + remove a trava (cargo inalterado)
  end
  App->>FS: notificação cargo_decidido + log "aprovacao_cargo" / "rejeicao_cargo"

Loading

• Disponível para contas operacionais que não são da Administração. A Administração altera cargos diretamente.
• O pedido registra solicitante, cargo atual, cargo solicitado, justificativa opcional (até 500 caracteres), data e status.
• A trava pendencias_cargo/{uid}, criada no mesmo lote, garante no servidor uma única solicitação pendente por usuário.
• O cargo só muda na aprovação, no mesmo lote atômico que fecha a solicitação. As regras exigem isso.
• Ninguém decide a própria solicitação.
• Se o cargo do usuário mudou desde o pedido, o painel mostra um aviso.

3. Alteração direta de cargo, bloqueio e exclusão

Na aba Usuários, a Administração pode:

Ação	Regras
Alterar o cargo (seletor na linha)	Só para contas aprovadas (ativas ou bloqueadas), nunca a própria. Log alteracao_perfil
Bloquear / desbloquear	Não vale para cadastros pendentes (esses são liberados pela aprovação) nem para a própria conta. O bloqueio encerra a sessão da pessoa em tempo real. Logs bloqueio_usuario / desbloqueio_usuario
Excluir	Com confirmação; nunca a própria conta. Apaga o documento users/{uid} e registra exclusao

A exclusão não apaga a conta do Firebase Auth, porque o SDK do navegador não permite. Sem o perfil, a pessoa não acessa dados; se entrar de novo, volta como Convidado pendente. A remoção definitiva da autenticação é feita no Firebase Console.

A tabela da aba tem busca por nome ou e-mail e filtro por situação.

4. Conta criada pela Administração (senha temporária)

1. Usuários → Nova conta: nome, e-mail e cargo. Não há campo de senha.
2. O sistema gera uma senha temporária de 14 caracteres com crypto.getRandomValues, com amostragem sem viés. A senha tem maiúscula, minúscula, dígito e símbolo e evita caracteres ambíguos (0/O, 1/l/I). O código está em src/domain/services/senhaTemporaria.ts.
3. A conta é criada numa instância secundária do Firebase App (getSecondaryAuthApp()), para não derrubar a sessão da administradora. O Firebase Auth guarda apenas o hash da senha.
4. O perfil nasce ativo: true, aprovado e trocaSenhaObrigatoria: true. As regras recusam uma criação administrativa sem essa exigência. Se o perfil não puder ser gravado, a conta de autenticação é desfeita.
5. A senha aparece uma única vez para a administradora, com botão Copiar. Ela é descartada ao clicar em Concluir ou ao sair da tela e nunca vai para URL, armazenamento do navegador, Firestore ou logs.
6. Log criacao_usuario, sem a senha.

5. Nova senha temporária para uma conta existente

Botão 🔑 na linha de uma conta aprovada (ativa ou bloqueada) na aba Usuários, útil quando alguém esquece a senha.

• Executada pela Cloud Function redefinirSenhaTemporaria (retool/functions/src/index.ts, região southamerica-east1), porque o SDK do navegador não altera a senha de outra pessoa.
• A função refaz a autorização no servidor: quem chama precisa ser Administração operacional. Ela não vale para a própria conta nem para cadastros pendentes ou rejeitados.
• Passos no servidor:
  1. marca trocaSenhaObrigatoria: true, o que já nega acesso aos dados;
  2. gera a senha com o CSPRNG do Node;
  3. aplica a senha no Firebase Auth;
  4. revoga as sessões abertas da conta;
  5. grava o log redefinicao_senha. Se a troca falhar, a exigência anterior é restaurada e a falha é registrada.
• A senha volta uma única vez, no mesmo cartão da criação de conta.
• Requer o deploy das Functions (plano Blaze). Sem ele, a tela avisa que o serviço está indisponível.

6. Troca obrigatória de senha no primeiro acesso

flowchart TD
  L[Login com a senha temporária] --> T[Tela Defina sua nova senha]
  T --> V{Política da nova senha OK?}
  V -- não --> T
  V -- sim --> R[Reautentica com a senha temporária e grava a nova no Auth]
  R -- senha temporária errada --> F[Log troca_senha com resultado falha] --> T
  R -- ok --> P[users/uid.trocaSenhaObrigatoria = false e senhaAlteradaEm]
  P --> S[Log troca_senha e o sistema é liberado]

Loading

• Enquanto trocaSenhaObrigatoria for true, a sessão só mostra essa tela, e as regras negam leitura e escrita de dados. Isso vale até para a Administração.
• Política da nova senha (validarNovaSenha): no mínimo 8 caracteres, letras e números, igual à confirmação e diferente da senha temporária.
• A interface só libera o sistema quando o servidor confirma a gravação. O listener do perfil ignora escritas locais ainda pendentes, o que evita liberar a tela antes de as regras aceitarem.

7. Login e logout

• Login: e-mail e senha no Firebase Auth. Se a conta estiver bloqueada ou rejeitada, o acesso é recusado com o motivo e registrado como login com resultado negado. Nos demais casos, o registro é login com sucesso, indicando se a pessoa entrou como Convidado ou com senha temporária.
• Logout: registrado como logout antes de encerrar a sessão.
• Tentativas com senha errada não geram log: sem autenticação, não há identidade para registrar (ver Logs e Auditoria).
• Mudanças feitas pela Administração (aprovação, cargo, bloqueio, exclusão) chegam à sessão da pessoa em tempo real.