Usuários, Cargos e Permissões

Três conceitos diferentes definem o que uma pessoa pode fazer:

Conceito	O que é	Onde fica
Cargo	O papel da pessoa no sistema	Campo perfil do documento users/{uid}
Situação da conta	Se a conta pode entrar e operar agora	Derivada de ativo, statusAprovacao e trocaSenhaObrigatoria
Permissões	As ações liberadas pelo cargo	ROLES_CONFIG em src/domain/entities/user.ts

As permissões do cargo só valem quando a conta é operacional. Uma Engenharia bloqueada, por exemplo, continua com cargo engenharia, mas não tem permissão nenhuma.

Cargos

Valor (perfil)	Nome na interface	Atribuível pela Administração
admin	Programadora / Administradora	Sim
projetista	Projetista – Ferramentaria	Sim
engenharia	Engenharia de Processo / Industrial	Sim
gerencia	Gerência	Sim
convidado	Convidado	Não. É o estado do autocadastro até a decisão da Administração

Situação da conta

Calculada por situacaoDoUsuario():

Situação	Quando	O que a pessoa vê
pendente	statusAprovacao: 'pendente' (ou cadastro antigo: Gerência inativa com perfilSolicitado)	Só a tela Cadastro em análise
ativo	Conta aprovada e ativo: true	O sistema, conforme o cargo
bloqueado	Conta aprovada e ativo: false	Login recusado ("desativado pela Administradora")
rejeitado	statusAprovacao: 'rejeitado'	Login recusado, com o motivo, se houver

Contas sem statusAprovacao, criadas antes desse campo, são tratadas como aprovadas quando estão ativas.

Conta operacional

Uma conta opera no sistema somente quando está ativa, aprovada, com cargo atribuível e sem troca de senha pendente (trocaSenhaObrigatoria diferente de true). A mesma regra aparece em três lugares:

• isContaOperacional(), no domínio;
• isActiveUser(), em firestore.rules;
• isActiveUser(), em storage.rules.

A tela que a sessão mostra vem de telaDaSessao():

flowchart TD
  A[Usuário autenticado] --> B{Perfil existe e situação é ativo ou pendente?}
  B -- não --> L[Sessão encerrada, volta ao login]
  B -- sim --> C{Situação pendente?}
  C -- sim --> P[Tela Cadastro em análise]
  C -- não --> D{trocaSenhaObrigatoria?}
  D -- sim --> T[Tela Defina sua nova senha]
  D -- não --> S[Sistema, conforme o cargo]

Permissões por cargo

Permissão	Administração	Projetista	Engenharia	Gerência	Convidado
Consultar dados (canConsultar)	✅	✅	✅	✅	❌
Cadastrar (canCadastrar)	✅	✅	❌	❌	❌
Editar (canEditar)	✅	✅	❌	❌	❌
Excluir (canExcluir)	✅	❌	❌	❌	❌
Aprovar reutilizações (canAprovar)	✅	✅	❌	❌	❌
Solicitar reutilização (canSolicitar)	✅	✅	✅	❌	❌
Gerir usuários (canGerenciarUsuarios)	✅	❌	❌	❌	❌
Ver auditoria (canVerLogs)	✅	❌	❌	❌	❌
Pedir alteração de cargo	❌ (altera cargos diretamente)	✅	✅	✅	❌

A matriz dos quatro cargos é a oficial do projeto (imagem institucional "Retool ADM – Controle de Acesso"). Ela é fixada como teste de regressão em src/tests/domain/entities/user.test.ts. Perfis desconhecidos caem no menor privilégio (configDoPerfil → Convidado).

Como a Administração é identificada

Uma conta é da Administração quando perfil == 'admin' e a conta é operacional:

• na interface, isAdministrador() e canGerenciarUsuarios/canVerLogs;
• no servidor, isAdmin() em firestore.rules e a mesma checagem na Cloud Function.

Não existe administrador com credenciais fixas no código.

Onde as permissões são aplicadas

Camada	Mecanismo
Rotas	ProtectedLayout (situação da conta) e RoleRoute (/categorias para Administração e Projetista; /administracao para Administração) em src/App.tsx
Interface	usePermissions() esconde botões, menus e abas
Contextos e casos de uso	Checam de novo antes de gravar (ex.: exigirAdministracao, ErroPermissao)
Servidor	firestore.rules, storage.rules e a Cloud Function. É a garantia real; a interface apenas esconde

Detalhes em Segurança.

Documento users/{uid}

Campo	Descrição
uid, email, nome	Identificação (o uid é o do Firebase Auth)
perfil	Cargo
ativo	Conta liberada ou bloqueada
statusAprovacao	pendente, aprovado ou rejeitado
trocaSenhaObrigatoria	true enquanto a senha temporária não for trocada
criadoEm, atualizadoEm, criadoPorUid	Datas ISO e autor da criação administrativa
aprovadoPorUid, aprovadoEm, rejeitadoPorUid, rejeitadoEm, motivoRejeicao	Decisão sobre o cadastro
senhaAlteradaEm, senhaRedefinidaEm, senhaRedefinidaPorUid	Histórico de senha (nunca a senha)
perfilSolicitado	Legado do cadastro antigo; não é mais gravado

Primeira conta de Administração

Como não há administrador fixo, a primeira conta é promovida uma única vez, manualmente:

1. Na tela de login, use Cadastre-se aqui com um e-mail seu e uma senha forte. A conta entra como Convidado.
2. No Firebase Console, abra o projeto que o .env faz o app usar (ver Configuração do Ambiente), vá em Firestore Database → users e edite o documento com o seu e-mail:

   { "perfil": "admin", "ativo": true, "statusAprovacao": "aprovado" }
   

3. A tela Cadastro em análise libera o sistema sozinha (ou recarregue a página). A partir daí, use Administração para os demais usuários.

Os fluxos de cadastro, aprovação, cargo e senha estão em Fluxos de Acesso.